Fournisseurs de recherche web Windows Search

La recherche Windows utilise actuellement la recherche web à partir de l’application Microsoft Bing pour retourner du contenu web et des résultats de recherche. Dans l’Espace économique européen (EEE), vous pouvez installer des applications qui implémentent un fournisseur de recherche web pour retourner du contenu web et des résultats de recherche dans Windows Search.

Les fournisseurs de recherche s’intègrent à l’expérience de recherche en créant un package MSIX avec un fichier manifeste de package qui fournit les informations nécessaires au système d’exploitation pour inscrire le fournisseur de recherche. Après l’installation, le fournisseur de recherche est activé par défaut dans les expériences Windows Search. Dans l’application Paramètres Windows, les utilisateurs peuvent activer et désactiver les fournisseurs de recherche installés et gérer l’ordre des fournisseurs dans les résultats de recherche. Les utilisateurs peuvent supprimer un fournisseur de recherche via la page Applications > installées dans > l’application Paramètres Windows.

Pour le développement et le test, lorsque le mode développeur est activé et que l’application du fournisseur de recherche a été chargée de manière indépendante sur l’appareil, elle apparaît dans la liste des fournisseurs de recherche disponibles. Pour plus d’informations, consultez fonctionnalités et débogage en mode développeur.

Une fois que le fournisseur de recherche est inscrit auprès du système d’exploitation, les requêtes utilisateur sont transmises au point de terminaison HTTP spécifié par le fournisseur dans son manifeste de package à l’aide d’une chaîne de requête standardisée. Le point de terminaison retourne des résultats suggérés dans un document JSON. Avec chaque URL suggérée dans le document de réponse, le fournisseur de recherche inclut l’URL du point de terminaison d’aperçu, qui retourne un document HTML affiché dans le volet d’aperçu dans l’interface utilisateur des résultats de la recherche.

Cet article fournit des conseils sur la création d’un package d’application de fournisseur de recherche et des détails sur les protocoles d’implémentation des points de terminaison HTTP du fournisseur de recherche.

Créer un package d’application d’extensibilité de recherche

Les fournisseurs de recherche s’inscrivent auprès du système d’exploitation en fournissant un package MSIX qui contient des informations requises sur le fournisseur, telles que le nom du fournisseur de recherche et les points de terminaison HTTP pour les suggestions et les aperçus.

Extension d’application du fournisseur de recherche

Le fichier manifeste du package d’application prend en charge de nombreuses extensions et fonctionnalités différentes pour les applications Windows. Le format du manifeste du package d’application est défini par un ensemble de schémas documentés dans les Informations de référence sur le schéma du manifeste de package. Les fournisseurs de recherche déclarent leurs informations d’inscription dans uap3 :AppExtension. L’attribut Name de l’extension doit être défini sur « com.microsoft.windows.websearchprovider ».

Les fournisseurs de recherche doivent inclure l’uap3 :Properties comme enfant d’uap3 :AppExtension. Le schéma du manifeste de package n’applique pas la structure de l’élément uap3 :Properties, à l'exception de l'exigence d'un XML bien formé. Le reste de cette section décrit le format XML attendu par le système d’exploitation pour inscrire correctement un fournisseur de recherche.

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

Hiérarchie d’éléments

uap3 :Propriétés

  Point de terminaison

  Protocole

Point de terminaison

URL du point de terminaison HTTPS auquel le système d’exploitation envoie des demandes de requête de recherche.

Protocole

Schéma de protocole qui sera utilisé lors du lancement des résultats de recherche web fournis. Si le protocole spécifié n’est pas inscrit par une application sur le système d’exploitation, le navigateur par défaut est lancé pour les résultats de la recherche. Pour plus d’informations sur l’inscription de schémas de protocole, consultez uap :Protocol.

Point de terminaison de contenu dynamique

Cette fonctionnalité n’est plus prise en charge. Pour en savoir plus, consultez Implémenter un point de terminaison pour l'icône de lueur. Le système d’exploitation enverra une demande à l'URL du point de terminaison HTTPS pour afficher l’icône de brillance dans la zone de recherche.

Exemple de fichier manifeste de package

Voici un exemple de appmanifest.xml fichier manifeste de package pour l’enregistrement d’un fournisseur 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>

Mettre en œuvre un point de terminaison pour les suggestions du fournisseur de recherche Windows

Les fournisseurs de recherche doivent exposer et inscrire un point de terminaison HTTPS appelé par le système d’exploitation lorsqu’un utilisateur tape dans la zone Recherche Windows. Ce point de terminaison doit retourner une chaîne au format JSON contenant les suggestions de recherche pour la requête utilisateur fournie. Le contenu doit être remis via HTTPS. L’intégration de la recherche ne prend pas en charge le contenu remis via HTTP.

Suggestion de format de requête HTTPS

La requête HTTPS adressée au point de terminaison de suggestion utilise le format suivant.

https://contoso.com?setlang=en-US&cc=US&qry=

Les paramètres de chaîne de requête passés au point de terminaison de suggestion sont les suivants.

Paramètre	Descriptif
setlang	Paramètres régionaux associés à la requête.
cc	Code de pays associé à la requête.
qry	Requête fournie par l’utilisateur. Si le paramètre n’a aucune valeur, c’est-à-dire qu’il apparaît dans la chaîne qry=de requête, la requête utilisateur est vide. Les fournisseurs de recherche peuvent toujours fournir des suggestions et afficher un aperçu des pages en réponse à une requête vide. NOTE Le système d’exploitation n’effectue aucune assainissement des chaînes de requête. Les fournisseurs de recherche peuvent implémenter leur propre assainissement lorsque la requête est reçue.

Suggestion d'en-têtes de réponse HTTPS

Le fournisseur de recherche doit inclure les en-têtes suivants dans la réponse de l'interface HTTPS de suggestions.

• 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
• Longueur du contenu : [Doit être la longueur exacte de la réponse]

Format JSON de réponse de suggestion

Le point de terminaison HTTPS du fournisseur de recherche pour les suggestions doit retourner un document JSON au format suivant. Les noms de clés doivent correspondre exactement au format.

Clé	Descriptif
Propositions	Contient une liste d’objets JSON avec clé Attributes représentant les suggestions associées à la requête utilisateur.
Attributs	Contient les attributs d’une suggestion.
URL	URL de la suggestion de recherche sur le site web du fournisseur.
requête	Requête utilisateur associée à la suggestion de recherche.
URL du volet d'aperçu	URL du point de terminaison d’aperçu à partir duquel un aperçu HTML de la suggestion peut être récupéré.
Texto	Description textuelle de la suggestion.

{"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"}
    ] 
} 

Mettre en œuvre un point de terminaison de prévisualisation pour le fournisseur Windows Search

Les fournisseurs de recherche retournent l’URL d’un point de terminaison HTTPS qui fournit un aperçu HTML de la page associée à chaque suggestion dans les résultats de la recherche. La réponse du point de terminaison d'aperçu doit retourner le code HTML d’une page fonctionnelle.

Format de demande HTTPS en préversion

La requête HTTPS adressée au point de terminaison d’aperçu utilise le format suivant.

https://contoso.com?Darkschemeovr=1

Les paramètres de chaîne de requête passés au point de terminaison de suggestion sont les suivants.

Paramètre	Descriptif
Darkschemeovr	Spécifie si le système Windows appelant a un thème sombre activé. La valeur est 1 si le thème foncé est activé et 0 si le thème foncé est désactivé.

Afficher un aperçu des en-têtes de réponse 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
• Longueur du contenu : [Doit être la longueur exacte de l’aperçu html]

Demande OPTIONS et partage de ressources Cross-Origin (CORS)

Les fournisseurs de recherche doivent prendre en charge la méthode de requête OPTIONS et répondre à cette requête avec HTTP OK. Si le point de terminaison du fournisseur de recherche utilise CORS, le client de recherche Windows envoie une requête HTTP OPTIONS avant chaque requête GET.

Implémenter un point de terminaison d’icône "gleam"

Remarque

Cette fonctionnalité de lueur n’est plus disponible. Les icônes de gleam ne sont plus affichées pour tous les fournisseurs web de l’EEE. Le contenu de cette section de la documentation est obsolète.

Les fournisseurs de recherche peuvent choisir de fournir des icônes brillantes pour les modes clair et sombre, qui sont affichées dans la barre de recherche lorsque le fournisseur de recherche est activé. Lorsque l’élément DynamicContentEndpoint est fourni dans le manifeste de l’application, une demande est envoyée à l’URL spécifiée et le fournisseur de recherche répond avec un fichier json au format défini ci-dessous qui inclut les URL des fichiers image d’icône et d’autres métadonnées. La demande d’icône de gleam est envoyée régulièrement pendant que le fournisseur de recherche est le fournisseur le plus récent actif dans Windows Search. La cadence de cette requête est toutes les 6 heures. Une demande sera également envoyée lors de chaque lancement de recherche et lors du déverrouillage de l’appareil.

Format de requête HTTPS de l’icône Gleam

La requête HTTPS adressée au point de terminaison de l'icône gleam utilise le format suivant.

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

Les paramètres de chaîne de requête passés au point de terminaison de suggestion sont les suivants.

Paramètre	Descriptif
setlang	Paramètres régionaux associés à la requête.
cc	Code de pays associé à la requête.
date et heure	Date et heure actuelles de l’appareil client, encodées par URL.
osAppareil	Système d’exploitation de l’appareil client. La valeur de ce paramètre peut être « Windows10 » ou « Windows11 ». Sur Windows 10, la taille de l'icône "gleam" est de 30 x 60. Sur Windows 11, la taille de l’icône brillante est de 20 x 36.
schemaversion	Version de schéma bascule.

Format JSON de l'icône de réponse de Gleam

Le point de terminaison HTTPS du fournisseur de recherche pour les icônes scintillantes doit retourner un document JSON au format suivant. Les noms de clés doivent correspondre exactement au format. La version actuelle du schéma est 1.0.0.

Clé	Descriptif
schemaVersion	Version de schéma bascule. Cela doit correspondre au paramètre de chaîne de requête schemaVersion dans la requête.
identifiant télémétrique	Identificateur unique de l'icône scintillante. Si la valeur de la réponse est identique à la valeur de l’icône de gleam actuelle, le système d’exploitation ne met pas à jour l’icône.
temps d'expiration	Heure d’expiration de l’icône scintillante. Doit être à une date ultérieure.
contenu	Section de contenu de la réponse.
boîte de recherche de la barre des tâches	Contient les paramètres du champ de recherche.
luire	Contient les paramètres de l'icône éclatante.
altText	Texte de remplacement de l’icône d'éclat.
dimensionEnum	Valeur « 30x60 » si la demande a été envoyée à partir d’un appareil Windows 10. Valeur « 20x36 » si la demande a été envoyée à partir d’un appareil Windows 11.
URL d'icône	Contient les URL des fichiers image d’icône à éclat clair et sombre.
léger	URL du fichier image de l’icône de reflet lumineux.
sombre	URL du fichier image de l’icône éclat sombre.

{
  "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>"
        }
      }
    }
  }
}

Validation de réponse de l'icône Gleam

La réponse doit spécifier à la fois l’URL de ressource claire et l’URL de ressource sombre. Les domaines des URL d’image d’icône doivent utiliser HTTPS et le sous-domaine doit correspondre au sous-domaine spécifié dans l’élément DynamicContentEndpoint dans le fichier manifeste de l’application.

Les fichiers image doivent être au format SVG et la taille maximale du fichier est de 300 kB. La lueur doit se trouver dans un cadre de 240 x 120px à l’intérieur du SVG.

Si une charge utile vide est reçue, cela efface l’icône de gleam active et aucune lueur ne s’affiche.

Articles connexes