Partager via

Fournisseurs Windows Search

  • Article

Remarque

Certaines informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Important

La fonctionnalité décrite dans cette rubrique est disponible dans les versions d'évaluation de Windows à partir de la version 22631.2787 pour Windows 11 et 19045.3758 pour Windows 10, bien que les versions plus récentes soient recommandées, car elles contiennent des améliorations de stabilité. Pour plus d’informations sur les versions d’évaluation de Windows, consultez Windows 10 Insider Préversion.

Windows Search utilise actuellement la recherche web 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 activer les applications installées qui implémentent un fournisseur de recherche web pour retourner du contenu web et des résultats de recherche dans Windows Search via paramètres.

Capture d'écran de l'interface utilisateur de Windows Search avec l'intégration d'un fournisseur de recherche tiers.

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. Les utilisateurs peuvent ajouter un fournisseur de recherche à Windows en installant le package d’application associé et peuvent supprimer le fournisseur de recherche via la page Ajouter ou supprimer des programmes dans l’application Paramètres Windows.

Pour le développement et les tests, lorsque le Mode Développeur est activé et que l’application fournisseur de recherche a été chargée indépendamment (sideloaded) sur l’appareil, elle apparaîtra dans la liste des fournisseurs de recherche disponibles. Pour plus d’informations, veuillez consulter la section Fonctionnalités du Mode Développeur et débogage.

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 widgets 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 le uap3:Properties en tant qu’enfant de uap3:AppExtension. Le schéma de manifeste du package n’applique pas la structure de l’élément uap3:Properties, hormis l’exigence relative au code XML correctement 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:Properties

  EndPoint

  Protocol

Point de terminaison

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

Protocol

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.

DynamicContentEndpoint

L'URL du point de terminaison HTTPS auquel le système d'exploitation enverra une requête pour que l'icône gleam s'affiche dans la boîte de recherche. Pour plus d'informations, consultez la section Mettre en œuvre un point de terminaison d'icône gleam. Cette fonctionnalité est prise en charge à partir de Windows 10 build 19045.4233 et Windows 11 build 22621.3371.

Exemple de fichier manifeste de package

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

Implémenter un point de terminaison de suggestion de fournisseur Windows Search

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

Format de requête HTTPS suggestion

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 Description
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 de requête comme qry=, 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. REMARQUE 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.

En-têtes de réponse HTTPS de suggestion

Le fournisseur de recherche doit inclure les en-têtes suivants dans la réponse du point de terminaison HTTPS de suggestion.

  • 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é Description
Suggestions Contient une liste d’objets JSON avec la 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.
query Requête utilisateur associée à la suggestion de recherche.
previewPaneUrl URL du point de terminaison d’aperçu à partir duquel un aperçu HTML de la suggestion peut être récupéré.
Texte 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"}
    ] 
}

Implémenter un point de terminaison d’aperçu du 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 en préversion 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 Description
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.

Mettre en œuvre un point de terminaison de l'icône gleam.

Les fournisseurs de recherche peuvent optionnellement fournir des icônes gleam en mode clair et foncé 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 requête sera envoyée à l'URL spécifiée et le fournisseur de recherche répondra avec un fichier json au format défini ci-dessous qui inclut les URL des fichiers d'images d'icônes et d'autres métadonnées. La requête d'icône gleam sera envoyée périodiquement tant que le fournisseur de recherche est le plus récent fournisseur actif dans Windows Search. Cette requête est envoyée toutes les 6 heures. Une requête sera également envoyée à chaque lancement de la recherche et au déverrouillage de l'appareil.

Format de la requête HTTPS pour l'icône Gleam

La requête HTTPS vers le 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 Description
setlang Paramètres régionaux associés à la requête.
cc Code de pays associé à la requête.
dateTime La date et l'heure actuelles de l'appareil client, encodées en url.
deviceOs Le système d'exploitation de l'appareil client. La valeur de ce paramètre peut être "Windows10" ou "Windows11". Sous Windows 10, la taille de l'icône gleam est de 30x60. Sous Windows 11, la taille de l'icône gleam est de 20x36.
schemaversion La version du schéma gleam.

Format JSON de la réponse à l'icône gleam

Le point de terminaison HTTPS du fournisseur de recherche pour les icônes gleam doit renvoyer 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é Description
schemaVersion La version du schéma gleam. Il doit correspondre au paramètre de la chaîne de requête schemaVersion dans la requête.
telemetryId Un identifiant unique pour l'icône gleam. Si la valeur de la réponse est la même que celle de l'icône gleam actuelle, le système d'exploitation ne mettra pas l'icône à jour.
expirationTime Le délai d'expiration de l'icône gleam. Il doit s'agir d'une date future.
content La section contenu de la réponse.
taskbarSearchBox Contient les paramètres de la boîte de recherche.
gleam Contient les paramètres de l'icône gleam.
altText Texte alternatif pour l'icône gleam.
dimensionEnum La valeur « 30x60 » si la requête a été envoyée depuis un appareil Windows 10. La valeur « 20x36 » si la requête a été envoyée à partir d'un appareil Windows 11.
iconUrl Contient les URL des fichiers d'images des icônes gleam claires et foncées.
léger L'URL du fichier d'image de l'icône lumineuse.
dark L'URL du fichier d'image de l'icône gleam foncé. 
{
  "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 la réponse à l'icône Gleam

La réponse doit spécifier à la fois l'URL de la ressource claire et l'URL de la ressource foncée. Les domaines pour les URL des images d'icônes doivent utiliser HTTPS et le sous-domaine doit correspondre au sous-domaine spécifié dans l'élément DynamicContentEndpoint du fichier manifeste de l'application.

Les fichiers d'image doivent être au format SVG et la taille maximale du fichier est de 300 kB. La lueur doit se trouver dans une trame de 240x120px à l'intérieur du SVG.

Si vous recevez une charge utile vide, l'icône de la lueur active sera effacée et aucune lueur ne sera affichée.