Senden von Anforderungen an die Bing-Vorschlagssuche-API
Warnung
Am 30. Oktober 2020 wurden die Bing-Suche-APIs aus den Azure KI Services in die Bing-Suchdienste verschoben. Diese Dokumentation wird nur zu Referenzzwecken bereitgestellt. Eine aktualisierte Dokumentation finden Sie in der Dokumentation zu den Bing-Suche-APIs. Anweisungen zum Erstellen neuer Azure-Ressourcen für die Bing-Suche finden Sie unter Erstellen einer Ressource für die Bing-Suche über Azure Marketplace.
Wenn Ihre Anwendung Abfragen an eine der Bing-Suche-APIs senden, können Sie die Bing-Vorschlagssuche-API verwenden, um die Suchumgebung des Benutzers zu verbessern. Die Bing-Vorschlagssuche-API gibt eine Liste vorgeschlagener Abfragen basierend auf der unvollständigen Abfragezeichenfolge im Suchfeld zurück. Bei der Eingabe von Zeichen in das Suchfeld Ihrer Anwendung können Sie Vorschläge in einer Dropdownliste anzeigen. In diesem Artikel erfahren Sie mehr über das Senden von Anforderungen an diese API.
Endpunkt der Bing-Vorschlagssuche-API
Die Bing-Vorschlagssuche-API enthält einen Endpunkt, der für einen Teil des Suchbegriffs eine Liste mit vorgeschlagenen Abfragen zurückgibt.
Um mithilfe der Bing-API vorgeschlagene Abfragen zu erhalten, senden Sie eine GET-Anforderung an den folgenden Endpunkt. Verwenden Sie die Header und die URL-Parameter, um Spezifikationen genauer zu definieren.
Endpunkt: Gibt Suchvorschläge als JSON-Ergebnisse zurück, die für die mit ?q="" definierte Eingabe des Benutzers relevant sind.
GET https://api.cognitive.microsoft.com/bing/v7.0/Suggestions
Weitere Informationen zu Headern, Parametern, Marktcodes, Antwortobjekten, Fehlern usw. finden Sie in der Referenz Bing-Vorschlagssuche-API V7.
Die Bing-APIs unterstützen Suchaktionen, die Ergebnisse gemäß ihrem Typ zurückgeben. Alle Suchendpunkte geben Ergebnisse als JSON-Antwortobjekte zurück. Alle Endpunkte unterstützen Abfragen, die eine bestimmte Sprache und/oder einen bestimmten Ort nach Längengrad, Breitengrad und Suchradius zurückgeben.
Die umfassenden Informationen zu den Parametern, die von jedem Endpunkt unterstützt werden, finden Sie auf den Referenzseiten des jeweiligen Typs. Beispiele für grundlegende Anforderungen, die die Vorschlagssuche-API verwenden, finden Sie unter Schnellstarts für die Vorschlagssuche.
Anforderungen für die Bing-Vorschlagssuche-API
Hinweis
- Bei Anforderungen für die Bing-Vorschlagssuche-API muss das HTTPS-Protokoll verwendet werden.
Alle Anforderungen sollten von einem Server stammen. Wird der Schlüssel zusammen mit einer Clientanwendung verteilt, erhöht sich das Risiko, dass eine böswillige dritte Partei darauf zugreift. Aufrufe über einen Server ermöglichen zudem die Verwendung eines einzelnen Upgradepunkts für zukünftige Updates.
Die Anforderung muss den Abfrageparameter q angeben, der den partiellen Suchbegriff des Benutzers enthält. Obwohl er optional ist, sollte die Anforderung auch den Abfrageparameter mkt angeben, wodurch der Markt identifiziert wird, von dem die Ergebnisse stammen sollen. Unter Abfrageparameter finden Sie eine Liste optionaler Abfrageparameter. Alle Abfrageparameterwerte müssen URL-codiert sein.
Die Anforderung muss den Ocp-Apim-Subscription-Key-Header angeben. Auch wenn dies optional ist, sollten Sie die folgenden Header ebenfalls angeben:
Die Client-IP- und Adressheader sind für die Rückgabe von standortorientiertem Inhalt wichtig.
Eine Liste aller Anforderungs- und Antwortheader finden Sie unter Header.
Hinweis
Wenn Sie die Bing-Vorschlagssuche-API über JavaScript aufrufen, verhindern die integrierten Sicherheitsfunktionen Ihres Browsers möglicherweise den Zugriff auf die Werte dieser Header.
Um dieses Problem zu lösen, können Sie die Anforderung der Bing-Vorschlagssuche-API über einen CORS-Proxy senden. In der Antwort eines solchen Proxys befindet sich ein Access-Control-Expose-Headers-Header, mit dem die Antwortheader gefiltert und für JavaScript verfügbar gemacht werden.
Die Installation eines CORS-Proxys, mit dem die Tutorial-App auf die optionalen Clientheader zugreifen kann, ist schnell und unkompliziert. Installieren Sie Node.js, falls Sie dies noch nicht getan haben. Geben Sie dann an einer Eingabeaufforderung den folgenden Befehl ein.
npm install -g cors-proxy-server
Passen Sie den Endpunkt der Bing-Vorschlagssuche-API in der HTML-Datei wie folgt an:
http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/Suggestions
Starten Sie abschließend den CORS-Proxy mit folgendem Befehl:
cors-proxy-server
Lassen Sie das Fenster während der Nutzung der Tutorial-App geöffnet. Wenn Sie das Fenster schließen, wird auch die Ausführung des Proxys beendet. Im Bereich mit den erweiterbaren HTTP-Headern unter den Suchergebnissen wird nun u.a. der X-MSEdge-ClientID-Header angezeigt. Hier können Sie überprüfen, ob dieser für alle Anforderungen identisch ist.
Anforderungen sollten alle vorgeschlagenen Abfrageparameter und Header enthalten.
Im folgenden Beispiel wird eine Anforderung gezeigt, die die vorgeschlagene Abfragezeichenfolgen für sail zurückgibt.
GET https://api.cognitive.microsoft.com/bing/v7.0/suggestions?q=sail&mkt=en-us HTTP/1.1 Ocp-Apim-Subscription-Key: 123456789ABCDE X-MSEdge-ClientIP: 999.999.999.999 X-Search-Location: lat:47.60357;long:-122.3295;re:100 X-MSEdge-ClientID: <blobFromPriorResponseGoesHere> Host: api.cognitive.microsoft.com
Wenn Sie zuvor noch keine der Bing-APIs aufgerufen haben, lassen Sie den Client-ID-Header weg. Schließen Sie den Client-ID-Header nur ein, wenn Sie bereits eine Bing-API aufgerufen haben und Bing eine Client-ID für die Kombination aus Benutzer und Gerät zurückgegeben hat.
Die folgende Webvorschlagsgruppe ist eine Antwort auf die oben genannte Anforderung. Die Gruppe enthält eine Liste von Vorschlägen für Suchanfragen, wobei jeder Vorschlag ein displayText-, query- und url-Feld enthält.
Das displayText-Feld enthält die vorgeschlagene Abfrage, die Sie zum Auffüllen der Dropdownliste des Suchfelds verwenden. Sie müssen alle in der Antwort enthaltenen Vorschläge in der angegebenen Reihenfolge anzeigen.
Wenn der Benutzer eine Abfrage aus der Dropdownliste auswählt, können Sie damit eine der Bing-Suche-API aufrufen und die Ergebnisse selbst anzeigen oder den Benutzer unter Verwendung des zurückgegebenen Felds url zur Bing-Ergebnisseite weiterleiten.
Hinweis
Da sich URL-Formate und -Parameter ohne Vorankündigung ändern können, sollten Sie alle URLs in der vorliegenden Form verwenden. Es sollten keine Abhängigkeiten von URL-Formaten oder -Parametern bestehen, außer wenn dies angegeben ist.
BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US
{
"_type" : "Suggestions",
"queryContext" : {
"originalQuery" : "sail"
},
"suggestionGroups" : [{
"name" : "Web",
"searchSuggestions" : [{
"url" : "https:\/\/www.bing.com\/search?q=sailing+lessons+seattle&FORM=USBAPI",
"displayText" : "sailing lessons seattle",
"query" : "sailing lessons seattle",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailor+moon+news&FORM=USBAPI",
"displayText" : "sailor moon news",
"query" : "sailor moon news",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailor+jack%27s+lincoln+city&FORM=USBAPI",
"displayText" : "sailor jack's lincoln city",
"query" : "sailor jack's lincoln city",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailing+anarchy&FORM=USBAPI",
"displayText" : "sailing anarchy",
"query" : "sailing anarchy",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale&FORM=USBAPI",
"displayText" : "sailboats for sale",
"query" : "sailboats for sale",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailstn.mylabsplus.com&FORM=USBAPI",
"displayText" : "sailstn.mylabsplus.com",
"query" : "sailstn.mylabsplus.com",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailusfood&FORM=USBAPI",
"displayText" : "sailusfood",
"query" : "sailusfood",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale+seattle&FORM=USBAPI",
"displayText" : "sailboats for sale seattle",
"query" : "sailboats for sale seattle",
"searchKind" : "WebSearch"
}]
}]
}