Windows-Suchanbieter

  • Artikel

Hinweis

Einige Informationen beziehen sich auf Vorabversionen, die vor der kommerziellen Freigabe grundlegend geändert werden können. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Wichtig

Das in diesem Thema beschriebene Feature ist in den Vorschaubuilds von Windows ab Build 22631.2787 für Windows 11 und Build 19045.3758 für Windows 10 verfügbar, obwohl neuere Builds empfohlen werden, da sie Stabilitätsverbesserungen enthalten. Informationen zu Vorabversionen von Windows finden Sie unter Windows 10-Insider-Vorschau.

Standardmäßig verwendet Windows Search derzeit Web Search aus der Microsoft Bing-App, um Webinhalte und Suchergebnisse zurückzugeben. Im Europäischen Wirtschaftsraum (EWR) können Sie installierte Microsoft Store-Apps aktivieren, die einen Websuchanbieter implementieren, um Webinhalte und Suchergebnisse in Windows Search über Einstellungen zurückzugeben.

Screenshot der Windows Search-Benutzeroberfläche mit Integration der Such-Drittanbieter.

Suchanbieter sind in die Suchumgebung integriert, indem Sie ein MSIX-Paket mit einer Paketmanifestdatei erstellen, die die erforderlichen Informationen für das Betriebssystem zum Registrieren des Suchanbieters bereitstellt. Benutzer können Windows einen Suchanbieter hinzufügen, indem Sie das zugeordnete App-Paket über den Microsoft Store installieren und den Suchanbieter über die Seite Programme hinzufügen oder entfernen in der Windows-Einstellungs-App entfernen.

Wenn der Entwicklermodus aktiviert ist und die Suchanbieter-App auf dem Gerät quergeladen wurde, wird sie in der Liste der verfügbaren Suchanbieter für Entwicklungs- und Testzwecke angezeigt. Weitere Informationen finden Sie unter Features und Debugging für den Entwicklermodus.

Sobald der Suchanbieter beim Betriebssystem registriert ist, werden Benutzerabfragen mithilfe einer standardisierten Abfragezeichenfolge an den vom Anbieter im Paketmanifest angegebenen HTTP-Endpunkt übergeben. Der Endpunkt gibt vorgeschlagene Ergebnisse in einem JSON-Dokument zurück. Bei jeder vorgeschlagenen URL im Antwortdokument enthält der Suchanbieter die Vorschauendpunkt-URL, die ein HTML-Dokument zurückgibt, das im Vorschaubereich in der Benutzeroberfläche der Suchergebnisse angezeigt wird.

Dieser Artikel enthält Anleitungen zum Erstellen eines Suchanbieter-App-Pakets und Details zu den Protokollen für die Implementierung von HTTP-Endpunkten des Suchanbieters.

Erstellen eines Sucherweiterungs-App-Pakets

Suchanbieter registrieren sich beim Betriebssystem, indem sie ein MSIX-Paket bereitstellen, das erforderliche Informationen zum Anbieter enthält, z. B. den Namen des Suchanbieters und die HTTP-Endpunkte für Vorschläge und Vorschauen.

Suchanbieter-App-Erweiterung

Die App-Paketmanifestdatei unterstützt viele verschiedene Erweiterungen und Features für Windows-Apps. Das Format des App-Paketmanifests wird durch eine Reihe von Schemas definiert, die in der Paketmanifestschemareferenz dokumentiert sind. Suchanbieter deklarieren ihre Registrierungsinformationen in uap3:AppExtension. Das Name-Attribut der Erweiterung muss auf „com.microsoft.windows.websearchprovider“ festgelegt werden.

Suchanbieter sollten uap3:Properties als untergeordnetes Element von uap3:AppExtension einschließen. Das Paketmanifestschema erzwingt nicht die Struktur des uap3:Properties-Elements, außer dass wohlgeformte XML-Dateien erforderlich sind. Im weiteren Verlauf dieses Abschnitts wird das XML-Format beschrieben, das das Betriebssystem erwartet, um einen Suchanbieter erfolgreich zu registrieren.

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

Elementhierarchie

uap3:Properties

  EndPoint

  Protokoll

Endpunkt

Die URL des HTTPS-Endpunkts, an den das Betriebssystem Suchabfrageanforderungen sendet.

Protokoll

Das Protokollschema, das beim Starten der bereitgestellten Websuchergebnisse verwendet wird. Wenn das angegebene Protokoll nicht von einer App im Betriebssystem registriert wird, wird der Standardbrowser für Suchergebnisse gestartet. Weitere Informationen zum Registrieren von Protokollschemas finden Sie unter uap:Protocol.

DynamicContentEndpoint

Die URL des HTTPS-Endpunkts, an den das Betriebssystem eine Anforderung zum Anzeigen des Gleam-Symbols im Suchfeld sendet. Weitere Informationen finden Sie unter Implementieren eines Gleam-Symbolendpunkts. Dieses Feature wird ab Windows 10 Build 19045.4233 und Windows 11 Build 22621.3371 unterstützt.

Beispiel-Paketmanifestdatei

Im Folgenden finden Sie ein Beispiel appmanifest.xml für eine Paketmanifestdatei zum Registrieren eines Windows Search-Anbieters.

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

Implementieren eines Windows Search-Anbietervorschlagsendpunkts

Suchanbieter müssen einen HTTPS-Endpunkt bereitstellen und registrieren, der vom Betriebssystem aufgerufen wird, wenn ein Benutzer in das Windows Search-Feld eingibt. Dieser Endpunkt sollte eine JSON-formatierte Zeichenfolge zurückgeben, die die Suchvorschläge für die bereitgestellte Benutzerabfrage enthält. Inhalte müssen über HTTPS übermittelt werden. Die Suchintegration unterstützt keine Inhalte, die über HTTP bereitgestellt werden.

HTTPS-Anforderungsformat für Vorschläge

Die HTTPS-Anforderung an den Vorschlagsendpunkt verwendet das folgende Format.

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

Die an den Vorschlagsendpunkt übergebenen Abfragezeichenfolgenparameter lauten wie folgt.

Parameter Beschreibung
setlang Das Gebietsschema, das der Abfrage zugeordnet ist.
cc Die mit der Abfrage verknüpfte Landeskennzahl.
Abf Die vom Benutzer bereitgestellte Abfrage. Wenn der Parameter keinen Wert aufweist, d. h. in der Abfragezeichenfolge als qry= angezeigt wird, ist die Benutzerabfrage leer. Suchanbieter können weiterhin Vorschläge und Vorschauseiten als Reaktion auf eine leere Abfrage bereitstellen. HINWEIS Das Betriebssystem führt keine Bereinigung von Abfragezeichenfolgen durch. Suchanbieter können ihre eigene Bereinigung implementieren, wenn die Abfrage empfangen wird.

Vorschlags-HTTPS-Antwortheader

Der Suchanbieter muss die folgenden Header in die Antwort des HTTPS-Endpunkts für den Vorschlag aufnehmen.

  • 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
  • Inhaltslänge: [Muss die genaue Antwortlänge sein]

JSON-Format der Vorschlagsantwort

Der HTTPS-Endpunkt des Suchanbieters für Vorschläge muss ein JSON-Dokument mit dem folgenden Format zurückgeben. Die Schlüsselnamen müssen exakt mit dem Format übereinstimmen.

Schlüssel Beschreibung
Vorschläge Enthält eine Liste von JSON-Objekten mit Schlüssel Attributes, die den Vorschlägen entsprechen, die der Benutzerabfrage zugeordnet sind.
Attribute Enthält die Attribute eines Vorschlags.
url Die URL für den Suchvorschlag auf der Anbieterwebsite.
Abfrage Die Benutzerabfrage, die dem Suchvorschlag zugeordnet ist.
previewPaneUrl Die URL des Vorschauendpunkts, aus der eine HTML-Vorschau des Vorschlags abgerufen werden kann.
Text Die Textbeschreibung des Vorschlags. 
{"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"}
    ] 
}

Implementieren eines Windows Search-Anbietervorschauendpunkts

Suchanbieter geben die URL eines HTTPS-Endpunkts zurück, der eine HTML-Vorschau der Seite bereitstellt, die jedem Vorschlag in den Suchergebnissen zugeordnet ist. Die Vorschauendpunktantwort muss den HTML-Code für eine funktionierende Seite zurückgeben.

Vorschau des HTTPS-Anforderungsformats

Die HTTPS-Anforderung an den Vorschauendpunkt verwendet das folgende Format.

https://contoso.com?Darkschemeovr=1

Die an den Vorschlagsendpunkt übergebenen Abfragezeichenfolgenparameter lauten wie folgt.

Parameter Beschreibung
Darkschemeovr Gibt an, ob auf dem aufrufenden Windows-System das dunkle Design aktiviert ist. Der Wert ist 1, wenn das dunkle Design aktiviert ist, und 0, wenn das dunkle Design deaktiviert ist.

Vorschau von HTTPS-Antwortheadern

  • 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
  • Inhaltslänge: [Muss die genaue Länge der Vorschau-HTML sein]

OPTIONS-Anforderung und Ressourcenfreigabe zwischen verschiedenen Ursprüngen (CORS)

Suchanbieter müssen die OPTIONS-Anforderungsmethode unterstützen und auf diese Anforderung mit HTTP OK antworten. Wenn der Endpunkt des Suchanbieters CORS verwendet, sendet der Windows-Suchclient vor jeder GET-Anforderung eine HTTP-OPTIONS-Anforderung.

Implementieren eines Gleam-Symbolendpunkts

Suchanbieter können optional Gleam-Symbole für den Hell- und Dunkelmodus bereitstellen, die in der Suchleiste angezeigt werden, wenn der Suchanbieter derzeit aktiviert ist. Wenn das DynamicContentEndpoint-Element im App-Manifest bereitgestellt wird, wird eine Anforderung an die angegebene URL gesendet, und der Suchanbieter antwortet mit einer JSON-Datei im unten definierten Format, das die URLs der Symbolbilddateien und andere Metadaten enthält. Die Gleam-Symbolanforderung wird in regelmäßigen Abständen gesendet, während der Suchanbieter der neueste, in Windows Search aktive Anbieter ist. Die Sendehäufigkeit für diese Anforderung beträgt alle 6 Stunden. Eine Anforderung wird auch bei jedem Start der Suche und beim Entsperren des Geräts gesendet.

HTTPS-Anforderungsformat für das Gleam-Symbol

Die HTTPS-Anforderung an das Gleam-Symbol verwendet das folgende Format.

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

Die an den Vorschlagsendpunkt übergebenen Abfragezeichenfolgenparameter lauten wie folgt.

Parameter Beschreibung
setlang Das Gebietsschema, das der Abfrage zugeordnet ist.
cc Die mit der Abfrage verknüpfte Landeskennzahl.
dateTime Das aktuelle Datum und die aktuelle Uhrzeit vom Clientgerät, url-codiert.
deviceOs Das Betriebssystem des Clientgeräts. Der Wert dieses Parameters kann 'Windows10' oder 'Windows11' sein. Unter Windows 10 beträgt dieGleam-Symbolgröße 30x60. Unter Windows 11 beträgt die Gleam-Symbolgröße 20x36.
schemaversion Die Gleam-Schemaversion.

JSON-Format der Gleam-Symbolantwort

Der HTTPS-Endpunkt des Suchanbieters für Gleam-Symbols muss ein JSON-Dokument mit dem folgenden Format zurückgeben. Die Schlüsselnamen müssen exakt mit dem Format übereinstimmen. Die aktuelle Schemaversion lautet 1.0.0.

Schlüssel Beschreibung
schemaVersion Die Gleam-Schemaversion. Dies sollte mit dem schemaVersion-Abfragezeichenfolgenparameter in der Anforderung übereinstimmen.
telemetryId Der eindeutige Bezeichner für das Gleam-Symbol. Wenn der Wert in der Antwort mit dem Wert für das aktuelle Gleam-Symbol identisch ist, wird das Symbol vom Betriebssystem nicht aktualisiert.
expirationTime Die Ablaufzeit für das Gleam-Symbol. Dieser Wert muss in der Zukunft liegen.
content Der Inhaltsabschnitt der Antwort.
taskbarSearchBox Enthält Einstellungen für das Suchfeld.
Gleam Enthält Einstellungen für das Gleam-Symbol.
altText Alternativtext für das Gleam-Symbol.
dimensionEnum Wert '30x60', wenn die Anforderung von einem Windows 10-Gerät gesendet wurde. Wert '20x36', wenn die Anforderung von einem Windows 11-Gerät gesendet wurde.
iconUrl Enthält die URLs für die Dateien mit den hellen und dunklen Gleam-Symbolen.
Leicht Die URL für die Datei mit dem hellem Gleam-Symbol.
dark Die URL für die Datei mit dem dunklen Gleam-Symbol. 
{
  "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>"
        }
      }
    }
  }
}

Überprüfung der Gleam-Symbolantwort

Die Antwort muss sowohl die URL für das helle Objekt als auch die URL des dunklen Objekts angeben. Die Domänen für die Symbolbild-URLs müssen HTTPS verwenden, und die Subdomäne muss mit der Subdomäne übereinstimmen, die im Element DynamicContentEndpoint in der App-Manifestdatei angegeben ist.

Die Bilddateien müssen im SVG-Format vorliegen und die maximale Dateigröße beträgt 300 kB. Der Gleam muss sich innerhalb eines 240x120px-Frames in der SVG befinden.

Wenn eine leere Payload empfangen wird, wird das aktive Gleam-Symbol gelöscht, und es wird kein Gleam angezeigt.