Senden von Anforderungen an die Bing-Vorschlagssuche-APISending requests to the Bing Autosuggest API.

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.If your application sends queries to any of the Bing Search APIs, you can use the Bing Autosuggest API to improve your users' search experience. Die Bing-Vorschlagssuche-API gibt eine Liste vorgeschlagener Abfragen basierend auf der unvollständigen Abfragezeichenfolge im Suchfeld zurück.The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box. Bei der Eingabe von Zeichen in das Suchfeld Ihrer Anwendung können Sie Vorschläge in einer Dropdownliste anzeigen.As characters are entered into a search box in your application, you can display suggestions in a drop-down list. In diesem Artikel erfahren Sie mehr über das Senden von Anforderungen an diese API.Use this article to learn more about sending requests to this API.

Endpunkt der Bing-Vorschlagssuche-APIBing Autosuggest API Endpoint

Die Bing-Vorschlagssuche-API enthält einen Endpunkt, der für einen Teil des Suchbegriffs eine Liste mit vorgeschlagenen Abfragen zurückgibt.The Bing Autosuggest API includes one endpoint, which returns a list of suggested queries from a partial search term.

Um mithilfe der Bing-API vorgeschlagene Abfragen zu erhalten, senden Sie eine GET-Anforderung an den folgenden Endpunkt.To get suggested queries using the Bing API, send a GET request to the following endpoint. Verwenden Sie die Header und die URL-Parameter, um Spezifikationen genauer zu definieren.Use the headers and URL parameters to define further specifications.

Endpunkt: Gibt Suchvorschläge als JSON-Ergebnisse zurück, die für die mit ?q="" definierte Eingabe des Benutzers relevant sind.Endpoint: Returns search suggestions as JSON results that are relevant to the user's input defined by ?q="".

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.For details about headers, parameters, market codes, response objects, errors, etc., see the Bing Autosuggest API v7 reference.

Die Bing-APIs unterstützen Suchaktionen, die Ergebnisse gemäß ihrem Typ zurückgeben.The Bing APIs support search actions that return results according to their type. Alle Suchendpunkte geben Ergebnisse als JSON-Antwortobjekte zurück. All search endpoints return results as JSON response objects. Alle Endpunkte unterstützen Abfragen, die eine bestimmte Sprache und/oder einen bestimmten Ort nach Längengrad, Breitengrad und Suchradius zurückgeben.All endpoints support queries that return a specific language and/or location by longitude, latitude, and search radius.

Die umfassenden Informationen zu den Parametern, die von jedem Endpunkt unterstützt werden, finden Sie auf den Referenzseiten des jeweiligen Typs.For complete information about the parameters supported by each endpoint, see the reference pages for each type. Beispiele für grundlegende Anforderungen, die die Vorschlagssuche-API verwenden, finden Sie unter Schnellstarts für die Vorschlagssuche.For examples of basic requests using the Autosuggest API, see Autosuggest Quickstarts.

Anforderungen für die Bing-Vorschlagssuche-APIBing Autosuggest API requests

Hinweis

  • Bei Anforderungen für die Bing-Vorschlagssuche-API muss das HTTPS-Protokoll verwendet werden.Requests to the Bing Autosuggest API must use the HTTPS protocol.

Alle Anforderungen sollten von einem Server stammen.We recommend that all requests originate from a server. Wird der Schlüssel zusammen mit einer Clientanwendung verteilt, erhöht sich das Risiko, dass eine böswillige dritte Partei darauf zugreift.Distributing the key as part of a client application provides more opportunity malicious third-party access. Aufrufe über einen Server ermöglichen zudem die Verwendung eines einzelnen Upgradepunkts für zukünftige Updates.Additionally, making calls from a server provides a single upgrade point for future updates.

Die Anforderung muss den Abfrageparameter q angeben, der den partiellen Suchbegriff des Benutzers enthält.The request must specify the q query parameter, which contains the user's partial search term. Obwohl es optional ist, sollte die Anforderung auch den Abfrageparameter mkt angeben, wodurch der Markt identifiziert wird, von dem die Ergebnisse stammen sollen.Although it's optional, the request should also specify the mkt query parameter, which identifies the market where you want the results to come from. Unter Abfrageparameter finden Sie eine Liste optionaler Abfrageparameter.For a list of optional query parameters, see Query Parameters. Alle Abfrageparameter müssen URL-codiert sein.All query parameter values must be URL encoded.

Die Anforderung muss den Ocp-Apim-Subscription-Key-Header angeben.The request must specify the Ocp-Apim-Subscription-Key header. Auch wenn dies optional ist, sollten Sie die folgenden Header ebenfalls angeben:Although optional, you are encouraged to also specify the following headers:

Die Client-IP- und Adressheader sind für die Rückgabe von standortorientiertem Inhalt wichtig.The client IP and location headers are important for returning location aware content.

Eine Liste aller Anforderungs- und Antwortheader finden Sie unter Header.For a list of all request and response headers, see Headers.

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.When you call the Bing Autosuggest API from JavaScript, your browser's built-in security features might prevent you from accessing the values of these headers.

Um dieses Problem zu lösen, können Sie die Anforderung der Bing-Vorschlagssuche-API über einen CORS-Proxy senden.To resolve this, you can make the Bing Autosuggest API request through a CORS proxy. In der Antwort eines solchen Proxys befindet sich ein Access-Control-Expose-Headers-Header. Dieser enthält eine Whitelist mit Antwortheadern und stellt diese JavaScript zur Verfügung.The response from such a proxy has a Access-Control-Expose-Headers header that whitelists response headers and makes them available to JavaScript.

Die Installation eines CORS-Proxys, mit dem die Tutorial-App auf die optionalen Clientheader zugreifen kann, ist schnell und unkompliziert.It's easy to install a CORS proxy to allow our tutorial app to access the optional client headers. Installieren Sie Node.js, falls Sie dies noch nicht getan haben.First, if you don't already have it, install Node.js. Geben Sie dann an einer Eingabeaufforderung den folgenden Befehl ein.Then enter the following command at a command prompt.

npm install -g cors-proxy-server

Passen Sie den Endpunkt der Bing-Vorschlagssuche-API in der HTML-Datei wie folgt an:Next, change the Bing Autosuggest API endpoint in the HTML file to:

http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/Suggestions

Starten Sie abschließend den CORS-Proxy mit folgendem Befehl:Finally, start the CORS proxy with the following command:

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.Leave the command window open while you use the tutorial app; closing the window stops the proxy. 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.In the expandable HTTP Headers section below the search results, you can now see the X-MSEdge-ClientID header (among others) and verify that it is the same for each request.

Anforderungen sollten alle vorgeschlagenen Abfrageparameter und Header enthalten.Requests should include all suggested query parameters and headers.

Im folgenden Beispiel wird eine Anforderung gezeigt, die die vorgeschlagene Abfragezeichenfolgen für sail zurückgibt.The following example shows a request that returns the suggested query strings for sail.

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.If it's your first time calling any of the Bing APIs, don't include the client ID header. 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.Only include the client ID header if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

Die folgende Webvorschlagsgruppe ist eine Antwort auf die oben genannte Anforderung.The following web suggestion group is a response to the above request. Die Gruppe enthält eine Liste von Vorschlägen für Suchanfragen, wobei jeder Vorschlag ein displayText-, query- und url-Feld enthält.The group contains a list of search query suggestions, with each suggestion including a displayText, query, and url field.

Das displayText-Feld enthält die vorgeschlagene Abfrage, die Sie zum Auffüllen der Dropdownliste des Suchfelds verwenden.The displayText field contains the suggested query that you'd use to populate your search box's drop-down list. Sie müssen alle in der Antwort enthaltenen Vorschläge in der angegebenen Reihenfolge anzeigen.You must display all suggestions that the response includes, and in the given order.

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.If the user selects a query from the drop-down list, you can use it to call the one of the Bing Search APIs and display the results yourself, or send the user to the Bing results page using the returned url field.

Hinweis

Da sich URL-Formate und -Parameter ohne Vorankündigung ändern können, verwenden Sie alle URLs in der vorliegenden Form.Because URL formats and parameters are subject to change without notice, use all URLs as-is. Es sollten keine Abhängigkeiten von URL-Format oder -Parametern bestehen, außer wenn dies angegeben ist.You should not take dependencies on the URL format or parameters except where noted.

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

Nächste SchritteNext steps