Windows Search-Websuchanbieter

2025-05-10

Windows Search verwendet derzeit die Websuche aus der Microsoft Bing-App, um Webinhalte und Suchergebnisse zurückzugeben. Im Europäischen Wirtschaftsraum (EWR) können Sie Apps installieren, die einen Websuchanbieter implementieren, um Webinhalte und Suchergebnisse in Windows Search zurückzugeben.

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. Nach der Installation ist der Suchanbieter standardmäßig in Windows Search-Umgebungen aktiviert. In der Windows-Einstellungs-App können Benutzer installierte Suchanbieter aktivieren und deaktivieren und die Reihenfolge der Anbieter in suchergebnissen verwalten. Benutzer können einen Suchanbieter über die Seite ">Installierte Einstellungen-Apps>" in der Windows-Einstellungs-App entfernen.

Wenn der Entwicklermodus aktiviert ist und die Suchanbieter-App auf dem Gerät quergeladen wurde, wird sie zu Entwicklungs- und Testzwecken in der Liste der verfügbaren Suchanbieter 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 Manifestdatei des App-Pakets 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 innerhalb der uap3:AppExtension. Das Name-Attribut der Erweiterung muss auf "com.microsoft.windows.websearchprovider" festgelegt werden.

Suchanbieter sollten die uap3:Properties als untergeordnetes Element von uap3:AppExtension enthalten. Das Paketmanifestschema erzwingt nicht die Struktur des uap3:Properties--Elements, außer der Anforderung, dass es sich um wohlgeformtes XML handelt. Der Rest dieses Abschnitts beschreibt das XML-Format, 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:Eigenschaften

Endpunkt

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

Dynamischer Inhalte-Endpunkt

Dieses Feature wird nicht mehr unterstützt. Weitere Informationen finden Sie unter Implementierung eines Gleam-Symbolendpunkts. Die URL des HTTPS-Endpunkts, an den das Betriebssystem eine Anforderung für dasGleam-Symbol sendet, das im Suchfeld angezeigt werden soll.

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 verfügbar machen und registrieren, der vom Betriebssystem aufgerufen wird, wenn ein Benutzer in das Windows-Suchfeld 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.

Format-Vorschläge für HTTPS-Anforderungen

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.
cm³	Der mit der Abfrage verknüpfte Ländercode.
qry	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. ANMERKUNG Das Betriebssystem führt keine Bereinigung von Abfragezeichenfolgen durch. Suchanbieter können ihre eigene Bereinigung implementieren, wenn die Abfrage empfangen wird.

Vorschlags-HTTPS-Antwort-Header

Der Suchanbieter muss die folgenden Header in der Antwort vom Vorschlags-HTTPS-Endpunkt enthalten.

Zugriffskontrolle-Allow-Origin: https://www.bing.com
Zugriffssteuerung-Erlaube-Anmeldedaten: 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
Anregungen	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.
Anfrage	Die Benutzerabfrage, die dem Suchvorschlag zugeordnet ist.
previewPaneUrl	Die URL des Vorschauendpunkts, aus dem 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 Vorschau-Endpunkts für den Windows Search-Anbieter

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 das aufrufende Windows-System das dunkle Design aktiviert hat. Der Wert ist 1, wenn das dunkle Design aktiviert ist, und 0, wenn das dunkle Design deaktiviert ist.

Vorschau von HTTPS-Antwortheadern

Zugriffskontrolle-Allow-Origin: https://www.bing.com
Zugriffssteuerung-Erlaube-Anmeldedaten: true
Access-Control-Allow-Methods: GET
Inhaltstyp: Text/HTML; charset=utf-8
Inhaltslänge: [Muss die genaue Länge der Vorschau-HTML sein]

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.

Implementierung eines Gleam-Symbolendpunkts

Hinweis

Dieses Gleam-Feature ist nicht mehr aktiviert. Gleam-Symbole werden nicht mehr für alle Webanbieter im EWR angezeigt. Der Inhalt in diesem Abschnitt der Dokumentation ist veraltet.

Suchanbieter können optional Glanzsymbole für den Hell- und Dunkelmodus bereitstellen, die in der Suchleiste angezeigt werden, wenn der Suchanbieter im Moment 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 Anforderung für das Gleam-Symbol wird regelmäßig gesendet, solange der Suchanbieter der aktuellste Anbieter ist, der in der Windows-Suche aktiv ist. Die Hä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.

Gleam-Icon-HTTPS, Anforderungsformat

Die HTTPS-Anforderung an den Gleam-Symbolendpunkt 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.
cm³	Der mit der Abfrage verknüpfte Ländercode.
Datum und Uhrzeit	Das aktuelle Datum und die aktuelle Uhrzeit vom Clientgerät, URL-kodiert.
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 Version des Gleam-Schemas.

JSON-Format der Gleam-Symbolantwort

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

Schlüssel	BESCHREIBUNG
schemaVersion	Die Version des Gleam-Schemas. Dies sollte mit dem Abfragezeichenfolgenparameter schemaVersion in der Anforderung übereinstimmen.
Telemetrie-Id	Ein eindeutiger Bezeichner für das Gleam-Symbol. Wenn der Wert in der Antwort mit dem Wert für das aktuelleGleam-Symbol identisch ist, wird das Symbol vom Betriebssystem nicht aktualisiert.
Ablaufzeit	Die Ablaufzeit für das Gleam-Symbol. Muss eine Zeit in der Zukunft sein.
Inhalt	Der Inhaltsabschnitt der Antwort.
taskbarSearchBox	Enthält Einstellungen für das Suchfeld.
schimmern	Enthält Einstellungen für das Gleam-Symbol.
altText	Alternativtext für das Gleam-Symbol.
dimensionEnum	Der Wert "30x60", wenn die Anforderung von einem Windows 10-Gerät gesendet wurde. Der Wert "20x36", wenn die Anforderung von einem Windows 11-Gerät gesendet wurde.
Icon-URL	Enthält die URLs für die hellen und dunklen Symboldateien.
Leicht	Die URL für das Bilddatei-Symbol mit hellem Glanz.
dunkel	Die URL für die Symbolbilddatei des dunklen Gleam.

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

Validierung der Gleam-Symbol-Antwort

Die Antwort muss sowohl die URL der hellen Ressource als auch die dunkle Objekt-URL angeben. Die Domänen für die Symbolbild-URLs müssen HTTPS verwenden, und die Unterdomäne muss mit der Unterdomäne übereinstimmen, die im DynamicContentEndpoint-Element 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-Rahmens im SVG befinden.

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

Freigeben über

Windows Search-Websuchanbieter

Erstellen eines Sucherweiterungs-App-Pakets

Suchanbieter-App-Erweiterung

Elementhierarchie

Endpunkt

Protokoll

Dynamischer Inhalte-Endpunkt

Beispiel-Paketmanifestdatei

Implementieren eines Windows Search-Anbietervorschlagsendpunkts

Format-Vorschläge für HTTPS-Anforderungen

Vorschlags-HTTPS-Antwort-Header

JSON-Format der Vorschlagsantwort

Implementieren eines Vorschau-Endpunkts für den Windows Search-Anbieter

Vorschau des HTTPS-Anforderungsformats

Vorschau von HTTPS-Antwortheadern

OPTIONS-Anfrage und Cross-Origin-Ressourcenfreigabe (CORS)

Implementierung eines Gleam-Symbolendpunkts

Gleam-Icon-HTTPS, Anforderungsformat

JSON-Format der Gleam-Symbolantwort

Validierung der Gleam-Symbol-Antwort

Verwandte Artikel

Feedback

Zusätzliche Ressourcen