Eventi
19 nov, 23 - 21 nov, 23
Ottenere il vantaggio competitivo necessario con potenti soluzioni di intelligenza artificiale e cloud partecipando a Microsoft Ignite online.
Iscriviti subitoQuesto browser non è più supportato.
Esegui l'aggiornamento a Microsoft Edge per sfruttare i vantaggi di funzionalità più recenti, aggiornamenti della sicurezza e supporto tecnico.
Nota
Alcune informazioni sono relative a un prodotto non definitivo, che potrebbe subire modifiche sostanziali prima del rilascio sul mercato. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
Importante
La funzionalità descritta in questo argomento è disponibile nelle build di anteprima di Windows a partire dalla build 22631.2787 per Windows 11 e dalla build 19045.3758 per Windows 10, anche se le build più recenti sono consigliate perché contengono miglioramenti della stabilità. Per informazioni sulle build di anteprima di Windows, vedere Windows 10 Insider Preview.
Windows Search attualmente usa la Ricerca Web dall'app Microsoft Bing per restituire contenuto Web e risultati di ricerca. Nello Spazio economico europeo (SEE) è possibile abilitare le app installate che implementano un provider di ricerca Web per restituire contenuto Web e risultati di ricerca in Windows Search tramite Impostazioni.
I provider di Ricerca si integrano con l'esperienza di Ricerca creando un pacchetto MSIX con un file manifesto del pacchetto che fornisce le informazioni necessarie per il sistema operativo per registrare il provider di ricerca. Gli utenti possono aggiungere un provider di ricerca a Windows installando il pacchetto dell'app associato e possono rimuovere il provider di ricerca tramite la pagina Aggiungi o rimuovi programmi nell'app di Impostazioni di Windows.
Per lo sviluppo e il test, quando la modalità Developer è abilitata e l'app del provider di ricerca è stata trasferita localmente nel dispositivo, verrà visualizzata nell'elenco dei provider di ricerca disponibili. Per altre informazioni, vedere Funzionalità della modalità Developer e debug.
Dopo aver registrato il provider di ricerca con il sistema operativo, le query utente vengono passate all'endpoint HTTP specificato dal provider nel manifesto del pacchetto usando una stringa di query standardizzata. L'endpoint restituisce i risultati suggeriti in un documento JSON. Con ogni URL suggerito nel documento di risposta, il provider di ricerca include l'URL dell'endpoint di anteprima, che restituisce un documento HTML visualizzato nel riquadro di anteprima nell'interfaccia utente dei risultati della ricerca.
Questo articolo fornisce indicazioni per la creazione di un pacchetto di app del provider di ricerca e i dettagli sui protocolli per l'implementazione degli endpoint HTTP del provider di ricerca.
I provider di ricerca si registrano con il sistema operativo fornendo un pacchetto MSIX contenente le informazioni necessarie sul provider, ad esempio il nome del provider di ricerca e gli endpoint HTTP per suggerimenti e anteprime.
Il file manifesto del pacchetto dell'app supporta molte estensioni e funzionalità diverse per le app di Windows. Il formato manifesto del pacchetto dell'app è definito da un set di schemi documentati nel Riferimento dello schema del manifesto del pacchetto. I provider di ricerca dichiarano le informazioni di registrazione all'interno di uap3:AppExtension. L'attributo Nome dell'estensione deve essere impostato su com.microsoft.windows.websearchprovider".
I provider di Ricerca devono includere uap3:Properties come figlio di uap3:AppExtension. Lo schema del manifesto del pacchetto non applica la struttura dell'elemento uap3:Properties diverso dalla richiesta di XML ben corretto. Nella parte restante di questa sezione viene descritto il formato XML previsto dal sistema operativo per registrare correttamente un provider di ricerca.
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
<uap3:Properties>
<!-- Search provider registration content goes here -->
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
uap3:Properties
EndPoint
Protocollo
URL dell'endpoint HTTPS a cui il sistema operativo invierà richieste di query di ricerca.
Schema del protocollo che verrà usato durante l'avvio dei risultati della ricerca Web forniti. Se il protocollo specificato non è registrato da un'app nel sistema operativo, verrà avviato il browser predefinito per i risultati della ricerca. Per altre informazioni sulla registrazione degli schemi di protocollo, vedere uap:Protocol.
URL dell'endpoint HTTPS a cui il sistema operativo invierà una richiesta per visualizzare l'icona a forma di stellina nella casella di ricerca. Per altre informazioni, vedere Implementare un endpoint dell'icona a forma di stellina. Questa funzionalità è supportata a partire dalla build 19045.4233 di Windows 10 e dalla build 22621.3371 di Windows 11.
Di seguito viene riportato un file manifesto del pacchetto di esempio appmanifest.xml
per la registrazione di un provider di Windows Search.
<!-- appxmanifest.xml -->
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
<uap3:Properties>
<Endpoint>https://customsearchendpoint</Endpoint>
<Protocol>customsearch</Protocol>
<DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
<uap:Extension Category="windows.protocol">
<uap:Protocol Name="customsearch"/>
</uap:Extension>
I provider di ricerca devono esporre e registrare un endpoint HTTPS chiamato dal sistema operativo quando un utente digita nella casella Windows Search. Questo endpoint deve restituire una stringa in formato JSON contenente i suggerimenti di ricerca per la query utente fornita. Il contenuto deve essere distribuito tramite HTTPS. L'integrazione della ricerca non supporta il contenuto distribuito tramite HTTP.
La richiesta HTTPS all'endpoint del suggerimento usa il formato seguente.
https://contoso.com?setlang=en-US&cc=US&qry=
I parametri della stringa di query passati all'endpoint del suggerimento sono i seguenti.
Parametro | Descrizione |
---|---|
setlang | Le impostazioni locali associate alla query. |
cc | Il codice paese ISO associato alla query. |
qry | La query fornita dall'utente. Se il parametro non ha alcun valore, ad esempio nella stringa di query viene visualizzato come qry= , la query utente è vuota. I provider di ricerca possono comunque fornire suggerimenti e pagine di anteprima in risposta a una query vuota. NOTA Il sistema operativo non esegue alcuna bonifica delle stringhe di query. I provider di ricerca possono implementare la propria bonifica quando viene ricevuta la query. |
Il provider di ricerca deve includere le intestazioni seguenti nella risposta dall'endpoint HTTPS del suggerimento.
L'endpoint HTTPS del provider di ricerca per i suggerimenti deve restituire un documento JSON con il formato seguente. I nomi delle chiavi devono corrispondere esattamente al formato.
Chiave | Descrizione |
---|---|
Suggerimenti | Contiene un elenco di oggetti JSON con chiave Attributes che rappresenta i suggerimenti associati alla query utente. |
Attributi | Contiene gli attributi di un suggerimento. |
URL. | URL del suggerimento di ricerca nel sito Web del provider. |
query | Query utente associata al suggerimento di ricerca. |
previewPaneUrl | URL dell'endpoint di anteprima da cui è possibile recuperare un'anteprima HTML del suggerimento. |
Testo | Descrizione testuale del suggerimento. |
{"Suggestions":
[{"Attributes":
{"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"},
{"Attributes":
{"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
]
}
I provider di ricerca restituiscono l'URL di un endpoint HTTPS che fornisce un'anteprima HTML della pagina associata a ogni suggerimento nei risultati della ricerca. La risposta dell'endpoint di anteprima deve restituire il codice HTML per una pagina funzionante.
La richiesta HTTPS all'endpoint di anteprima usa il formato seguente.
https://contoso.com?Darkschemeovr=1
I parametri della stringa di query passati all'endpoint del suggerimento sono i seguenti.
Parametro | Descrizione |
---|---|
Darkschemeovr | Specifica se il sistema Windows chiamante è abilitato per il tema scuro. Il valore è 1 se il tema scuro è abilitato e 0 se il tema scuro è disabilitato. |
I provider di ricerca devono supportare il metodo di richiesta OPTIONS e rispondere a questa richiesta con HTTP OK. Se l'endpoint del provider di ricerca usa CORS, il client di Windows search invierà una richiesta HTTP OPTIONS prima di ogni richiesta GET.
I provider di ricerca possono facoltativamente fornire icone a forma di stellina in modalità chiara e scura visualizzate nella barra di ricerca quando il provider di ricerca è attualmente abilitato. Quando l'elemento DynamicContentEndpoint viene fornito nel manifest dell'app, verrà inviata una richiesta all'URL specificato e il provider di ricerca risponderà con un file json nel formato definito di seguito, che include gli URL dei file di immagine dell'icona e di altri metadati. La richiesta di icona a forma di stellina verrà inviata periodicamente se il provider di ricerca è il provider attivo più recente in Windows Search. La cadenza per questa richiesta è ogni 6 ore. Una richiesta verrà inviata anche a ogni avvio di Search e al momento dello sblocco del dispositivo.
La richiesta HTTPS all'endpoint dell'icona a forma di stellina usa il formato seguente.
https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0
I parametri della stringa di query passati all'endpoint del suggerimento sono i seguenti.
Parametro | Descrizione |
---|---|
setlang | Le impostazioni locali associate alla query. |
cc | Il codice paese ISO associato alla query. |
dateTime | Data e ora correnti del dispositivo client con codifica URL. |
deviceOs | Il sistema operativo del dispositivo client. Il valore di questo parametro può essere "Windows10" o "Windows11". In Windows 10, la dimensione dell'icona a forma di stellina è 30x60. In Windows 11, la dimensione dell'icona a forma di stellina è 20x36 |
schemaversion | Versione dello schema a forma di stellina. |
L'endpoint HTTPS del provider di ricerca per le icone a forma di stellina deve restituire un documento JSON con il formato seguente. I nomi delle chiavi devono corrispondere esattamente al formato. La versione corrente dello schema è 1.0.0.
Chiave | Descrizione |
---|---|
schemaVersion | Versione dello schema a forma di stellina. Deve corrispondere al parametro di stringa della query schemaVersion nella richiesta. |
telemetryId | Identificatore univoco per l'icona a forma di stellina. Se il valore nella risposta è lo stesso dell'icona a forma di stellina corrente, il sistema operativo non aggiornerà l'icona. |
expirationTime | Ora di scadenza dell'icona a forma di stellina. Deve essere un'ora futura. |
content | La sezione del contenuto della risposta. |
taskbarSearchBox | Contiene le impostazioni della casella di ricerca. |
gleam | Contiene le impostazioni dell'icona a forma di stellina. |
altText | Testo alternativo per l'icona a forma di stellina. |
dimensionEnum | Valore "30x60" se la richiesta è stata inviata da un dispositivo Windows 10. Valore "20x36" se la richiesta è stata inviata da un dispositivo Windows 11. |
iconUrl | Contiene gli URL per i file di immagine dell'icona a forma di stellina chiara e scura. |
light | URL del file di immagine dell'icona a forma di stellina chiara. |
dark | URL per il file di immagine dell'icona a forma di stellina scura. |
{
"schemaVersion":"1.0.0",
"telemetryId":"<unique gleam Id>",
"expirationTime":"2025-12-09T20:37:13Z",
"content": {
"taskbarSearchBox": {
"gleam":{
"altText": "<alt text of the gleam>",
"dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
"iconUrl": {
"light":"<3p's light gleam url>",
"dark": "<3p's dark gleam url>"
}
}
}
}
}
La risposta deve specificare sia l'URL dell'asset chiaro che l'URL dell'asset scuro. I domini degli URL dell'immagine dell'icona devono usare HTTPS e il sottodominio deve corrispondere al sottodominio specificato nell'elemento DynamicContentEndpoint nel file manifest dell'app.
I file di immagine devono essere in formato SVG e la dimensione massima del file è 300 kB. La stellina deve essere all'interno di un frame di 240x120 pixel all'interno del SVG.
Se viene ricevuto un payload vuoto, verrà cancellata l'icona a forma di stellina attiva e non verrà visualizzata alcuna stellina.
Feedback su Windows developer
Windows developer è un progetto di open source. Selezionare un collegamento per fornire feedback:
Eventi
19 nov, 23 - 21 nov, 23
Ottenere il vantaggio competitivo necessario con potenti soluzioni di intelligenza artificiale e cloud partecipando a Microsoft Ignite online.
Iscriviti subito