Condividi tramite

Provider di Windows Search

  • Articolo

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.

Screenshot dell'interfaccia utente di Windows Search con integrazione del provider di ricerca di terze parti.

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.

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 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>

Gerarchia elementi

uap3:Properties

  EndPoint

  Protocollo

Endpoint

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

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.

File manifesto del pacchetto di esempio

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>

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 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.

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 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.

Intestazioni di risposta HTTPS di suggerimento

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

  • 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.
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"}
    ] 
}

Implementare un endpoint di anteprima del provider di Windows Search

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 è abilitato per il tema scuro. 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
  • Tipo di contenuto: text/html; charset=utf-8
  • Content-Length: [Deve essere la lunghezza esatta dell'html di anteprima]

Richiesta OPTIONS e Condivisione di risorse tra le origini (Cross-Origin Resource Sharing - 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 Windows search invierà una richiesta HTTP OPTIONS prima di ogni richiesta GET.

Implementare un endpoint dell'icona a forma di stellina

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.

Formato di richiesta HTTPS dell'icona a forma di stellina

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.

Formato JSON della risposta dell'icona 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>"
        }
      }
    }
  }
}

Convalida della risposta dell'icona a forma di stellina

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.