Provider di ricerca Web di Windows Search

Windows Search usa attualmente la ricerca Web dell'app Microsoft Bing per restituire contenuto Web e risultati della ricerca. Nell'Area economica europea (SEE) è possibile installare app che implementano un provider di ricerca Web per restituire contenuti Web e risultati di ricerca in Windows Search.

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. Dopo l'installazione, il provider di ricerca è abilitato per impostazione predefinita nelle esperienze di Windows Search. In Impostazioni di Windows gli utenti possono abilitare e disabilitare i provider di ricerca installati e gestire l'ordine dei provider nei risultati della ricerca. Gli utenti possono rimuovere un provider di ricerca tramite la pagina Impostazioni > App > installate in Impostazioni di Windows.

Per lo sviluppo e il test, quando la modalità sviluppatore è 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à sviluppatore 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.

Creare un pacchetto di app di estendibilità della 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.

Estensione dell'app del provider di ricerca

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 Name 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, se non per richiedere che sia XML ben formato. 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>

Gerarchia degli elementi

uap3:Properties

  Punto finale

  Protocollo

Punto finale

URL dell'endpoint HTTPS a cui il sistema operativo invierà richieste di query di ricerca.

Protocollo

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.

DynamicContentEndpoint

Questa funzionalità non è più supportata. Per ulteriori informazioni, vedere Implementare un endpoint di icona luccichio. URL dell'endpoint HTTPS a cui il sistema operativo invierà una richiesta per visualizzare l'icona scintillante nella casella di ricerca.

File manifest del pacchetto di esempio

Di seguito è 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>

Implementare un endpoint di suggerimento del provider di Windows Search

I provider di ricerca devono esporre e registrare un endpoint HTTPS chiamato dal sistema operativo quando un utente digita nella casella Di ricerca di Windows. 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.

Formato di richiesta HTTPS di suggerimento

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	Il contesto locale associato alla query.
Cc	Codice paese associato alla richiesta.
qry	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 purificazione delle stringhe di query. I provider di ricerca possono implementare la propria purificazione quando viene ricevuta la query.

Intestazioni di risposta HTTPS suggerite

Il provider di ricerca deve includere le seguenti intestazioni nella risposta dall'endpoint HTTPS dei suggerimenti.

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: true
• Access-Control-Allow-Methods: GET
• Content-Type: application/json; charset=utf-8
• Content-Length: [Deve essere la lunghezza esatta della risposta]

Formato JSON della risposta di 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.
quesito	Query utente associata al suggerimento di ricerca.
previewPaneUrl	URL dell'endpoint di anteprima da cui è possibile recuperare un'anteprima HTML del suggerimento.
Testo	Descrizione 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"}
    ] 
} 

Implementare un endpoint di anteprima per il provider di ricerca di Windows

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.

Anteprima del formato di richiesta HTTPS

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 ha il tema scuro attivato. Il valore è 1 se il tema scuro è abilitato e 0 se il tema scuro è disabilitato.

Anteprima delle intestazioni di risposta HTTPS

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: true
• Access-Control-Allow-Methods: GET
• Content-Type: text/html; charset=utf-8
• Content-Length: [Deve essere la lunghezza esatta dell'html di anteprima]

Richiesta OPTIONS e Condivisione delle risorse tra origini diverse (CORS)

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 ricerca di Windows invierà una richiesta HTTP OPTIONS prima di ogni richiesta GET.

Implementare un endpoint icona scintillante

Annotazioni

Questa funzionalità scintillante non è più abilitata. Le icone di gleam non vengono più visualizzate per tutti i provider Web nel SEE. Il contenuto di questa sezione della documentazione è obsoleto.

I provider di ricerca possono opzionalmente fornire icone "gleam" per la modalità chiara e scura, visualizzate nella barra di ricerca quando il provider di ricerca è abilitato. Quando l'elemento DynamicContentEndpoint viene fornito nel manifesto dell'app, una richiesta verrà inviata all'URL specificato e il provider di ricerca risponde con un file JSON nel formato definito di seguito che include gli URL dei file di immagine icona e altri metadati. La richiesta di icona scintillante verrà inviata periodicamente mentre il provider di ricerca è il provider più recente attivo in Windows Search. La frequenza per questa richiesta è ogni 6 ore. Una richiesta verrà inviata anche all'avvio di ogni ricerca e al momento dello sblocco del dispositivo.

Icona Gleam Formato di richiesta HTTPS

La richiesta HTTPS all'endpoint dell'icona scintillante 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	Il contesto locale associato alla query.
Cc	Codice paese associato alla richiesta.
data e ora	Data e ora correnti dal dispositivo client, con codifica URL.
DispositivoOS	Sistema operativo del dispositivo client. Il valore di questo parametro può essere "Windows10" o "Windows11". In Windows 10, la dimensione dell'icona scintillante è 30x60. In Windows 11, la dimensione dell'icona scintillante è 20x36
versione dello schema	Versione dello schema lucente.

Formato JSON della risposta dell'icona Gleam

L'endpoint HTTPS del provider di ricerca per le icone scintillanti 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
versione dello schema	Versione dello schema lucente. Deve corrispondere al parametro della stringa di query schemaVersion nella richiesta.
telemetryId	Identificatore univoco per l'icona scintillante. Se il valore nella risposta corrisponde al valore per l'icona di scintilla corrente, il sistema operativo non aggiornerà l'icona.
tempo di scadenza	Ora di scadenza per l'icona scintillante. Deve essere un momento in futuro.
contenuto	Sezione contenuto della risposta.
casella di ricerca della barra delle applicazioni	Contiene le impostazioni per la casella di ricerca.
brillare	Contiene le impostazioni per l'icona scintillante.
altText	Testo alternativo per l'icona scintillante.
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 chiara e scintillante scura.
Leggero	URL del file di immagine dell'icona del bagliore di luce.
oscuro	URL per il file immagine dell'icona con lucentezza 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>"
        }
      }
    }
  }
}

Convalida della risposta dell'icona Gleam

La risposta deve specificare sia l'URL dell'asset chiaro che l'URL dell'asset scuro. I domini per gli URL dell'immagine dell'icona devono usare HTTPS e il sottodominio deve corrispondere al sottodominio specificato nell'elemento DynamicContentEndpoint nel file manifesto dell'app.

I file di immagine devono essere in formato SVG e la dimensione massima del file è 300 kB. Il bagliore deve essere all'interno di una cornice 240x120px all'interno dell'SVG.

Se viene ricevuto un payload vuoto, verrà cancellata l'icona a forma di scintilla attiva e non verrà visualizzata alcuna scintilla.

Articoli correlati