Senden von Suchabfragen an die API für die visuelle Bing-SucheSending search queries to the Bing Visual Search API

In diesem Artikel werden die Parameter und Attribute von Anforderungen beschrieben, die an die API für die visuelle Bing-Suche gesendet werden. Außerdem finden Sie hier Informationen zum Antwortobjekt.This article describes the parameters and attributes of requests sent to the Bing Visual Search API, as well as the response object.

Erkenntnisse zu Bildern können auf drei Arten gewonnen werden:You can get insights about an image in three ways:

  • Verwenden des Auswertungstokens zu einem Bild aus einem früheren Aufruf eines der Endpunkte der Bing-Bildersuche-APIUsing an insights token that you get from an image in a previous call to one of the Bing Image Search API endpoints.
  • Senden der URL eines BildsSending the URL of an image.
  • Hochladen eines Bilds (im Binärformat)Uploading an image (in binary format).

Anforderungen der visuellen Bing-SucheBing Visual Search requests

Wenn Sie der visuellen Bing-Suche ein Bildtoken oder eine URL senden, zeigt der folgende Codeausschnitt das JSON-Objekt an, das Sie in den Text der POST-Anforderung einbeziehen müssen:If you send Visual Search an image token or URL, the following snippet shows the JSON object that you must include in the body of the POST:

{
    "imageInfo" : {
        "url" : "",
        "imageInsightsToken" : "",
        "cropArea" : {
            "top" : 0.1,
            "left" : 0.5,
            "right" : 0.9,
            "bottom" : 0.9
        }
    },
    "knowledgeRequest" : {
      "filters" : {
        "site" : ""
      }
    }
}

Das imageInfo-Objekt muss entweder das url-Feld oder das imageInsightsToken-Feld beinhalten, jedoch nicht beide gleichzeitig.The imageInfo object must include either the url or imageInsightsToken field but not both. Legen Sie im url-Feld die URL eines Bildes fest, das über das Internet zugänglich ist.Set the url field to the URL of an Internet-accessible image. Die maximal unterstützte Bildgröße beträgt 1 MB.The maximum supported image size is 1 MB.

Legen Sie bei imageInsightsToken ein Auswertungstoken fest.The imageInsightsToken must be set to an insights token. Rufen Sie zum Abrufen eines Auswertungstokens die „Bing Images API (API für Bing-Bilder)“ auf.To get an insights token, call the Bing Image API. Die Antwort enthält eine Liste mit Image-Objekten.The response contains a list of Image objects. Jedes Image-Objekt enthält ein imageInsightsToken-Feld mit dem Token.Each Image object contains an imageInsightsToken field, which contains the token.

Das Feld cropArea ist optional.The cropArea field is optional. Mit dem Zuschneidebereich können Sie die linke obere Ecke und die rechte untere Ecke eines relevanten Bereichs angeben.The crop area specifies the top-left corner and bottom-right corner of a region of interest. Legen Sie dabei Werte zwischen 0,0 und 1,0 fest.Specify the values in the range 0.0 through 1.0. Damit geben Sie den Prozentsatz der gesamten Breite oder Höhe an.The values are a percentage of the overall width or height. Im vorherigen Beispiel wird etwa die rechte Hälfte des Bildes als relevanter Bereich markiert.For example, the above example marks the right half of the image as the region of interest. Soll die Anforderung auf den relevanten Bereich beschränkt sein, fügen Sie Werte in dieses Feld ein.Include it if you want to limit the insights request to the region of interest.

Das filters-Objekt enthält einen Sitefilter (das site-Feld). Damit können Sie die Ergebnisse für ähnliche Bilder und ähnliche Produkte auf eine bestimmte Domäne eingrenzen.The filters object contains a site filter (see the site field) that you can use to restrict the similar images and similar products results to a specific domain. Zeigt das Bild beispielsweise ein Surface Book, können Sie site auf www.microsoft.com festlegen.For example, if the image is of a Surface Book, you can set site to www.microsoft.com.

Wenn Sie Informationen zu der lokalen Kopie eines Bildes erhalten möchten, laden Sie das Bild in Binärform hoch.If you want to get insights about a local copy of an image, upload the image as binary data.

Einzelheiten zum Einfügen dieser Optionen in den Text einer POST-Anforderung finden Sie unter Inhaltsformulartypen.For details about including these options in the body of the POST, see Content form types.

Endpunkt für die SucheSearch endpoint

Der Endpunkt der visuellen Suche lautet: „https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch“.The Visual Search endpoint is: https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch.

Anforderungen müssen als HTTP-POST-Anforderungen gesendet werden.Requests must be sent as HTTP POST requests only.

AbfrageparameterQuery parameters

Die folgenden Abfrageparameter sollten in der Anforderung angegeben werden.The following are the query parameters your request should specify. Fügen Sie auf jeden Fall zumindest den mkt-Abfrageparameter ein:At a minimum, you should include the mkt query parameter:

NAMEName WertValue typeType ErforderlichRequired
cccc Ein zweistelliger Ländercode, der angibt, woher die Ergebnisse stammen.A two-character country code that represents where the results come from.

Wenn Sie diesen Parameter festlegen, müssen Sie auch den Header Accept-Language angeben.If you set this parameter, you must also specify the Accept-Language header. Bing verwendet die erste unterstützte Sprache aus der Liste der Sprachen und kombiniert sie mit dem Ländercode, den Sie für den Markt angeben, aus dem Ergebnisse zurückgegeben werden sollen.Bing uses the first supported language it finds from the list of languages, and combines the language with the country code that you specify to determine the market to return results from. Enthält die Liste der Sprachen keine unterstützte Sprache, sucht Bing die nächstgelegene Sprache und den nächstgelegenen Markt, die die Anforderung unterstützen.If the languages list does not include a supported language, Bing finds the closest language and market that supports the request. Alternativ dazu wird anstatt des angegebenen Marktes ein aggregierter oder Standardmarkt für die Ergebnisse verwendet.Or it may use an aggregated or default market for the results instead of the specified one.

Verwenden Sie diesen und den Accept-Language-Abfrageparameter nur, wenn Sie mehrere Sprachen angeben. Andernfalls sollten Sie die Abfrageparameter mkt und setLang verwenden.You should use this query parameter and the Accept-Language query parameter only if you specify multiple languages; otherwise, you should use the mkt and setLang query parameters.

Dieser Parameter und der Abfrageparameter mkt schließen sich gegenseitig aus. Geben Sie daher nicht beide an.This parameter and the mkt query parameter are mutually exclusive—do not specify both.
ZeichenfolgeString NeinNo
mktmkt Der Markt, aus dem die Ergebnisse stammen.The market where the results come from.

HINWEIS: Sie sollten immer den Markt angeben, falls bekannt.NOTE: You should always specify the market, if known. Die Angabe des Marktes ermöglicht Bing, die Anforderung weiterzuleiten und eine geeignete und optimale Antwort zurückzugeben.Specifying the market helps Bing route the request and return an appropriate and optimal response.

Dieser Parameter und der Abfrageparameter cc schließen sich gegenseitig aus. Geben Sie daher nicht beide an.This parameter and the cc query parameter are mutually exclusive—do not specify both.
ZeichenfolgeString JaYes
safeSearchsafeSearch Ein Filter für nicht jugendfreie Inhalte.A filter for adult content. Die folgenden Filterwerte (ohne Beachtung von Groß-/Kleinschreibung) sind möglich.The following are the possible case-insensitive filter values.
  • Off: Es werden Webseiten mit nicht jugendfreiem Text oder Bildern zurückgegeben.Off—Return webpages with adult text or images.

  • Moderate: Webseiten mit nicht jugendfreiem Text werden zurückgegeben, nicht jugendfreie Bilder jedoch nicht.Moderate—Return webpages with adult text, but not adult images.

  • Strict: Es werden keine Webseiten mit nicht jugendfreiem Text oder Bildern zurückgegeben.Strict—Do not return webpages with adult text or images.

Die Standardeinstellung ist „Moderate“.The default is Moderate.

HINWEIS: Stammt die Anforderung aus einem Markt, für den laut Bing-Richtlinien zu nicht jugendfreien Inhalten für safeSearch die Einstellung „Strict“ erforderlich ist, ignoriert Bing den safeSearch-Wert und verwendet stattdessen „Strict“.NOTE: If the request comes from a market that Bing's adult policy requires that safeSearch be set to Strict, Bing ignores the safeSearch value and uses Strict.

HINWEIS: Bei Verwendung des Abfrageoperators site: kann es vorkommen, dass die Antwort unabhängig von der Einstellung des safeSearch-Abfrageparameters nicht jugendfreie Inhalte enthält.NOTE: If you use the site: query operator, there is a chance that the response may contain adult content regardless of what the safeSearch query parameter is set to. Verwenden Sie site: nur, wenn Sie wissen, welche Inhalte die Website enthält, und wenn in Ihrem Szenario ggf. auch nicht jugendfreie Inhalte zulässig sind.Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.
ZeichenfolgeString NeinNo
setLangsetLang Die Sprache, die für Zeichenfolgen der Benutzeroberfläche verwendet werden soll.The language to use for user interface strings. Geben Sie die Sprache mithilfe des zweistelligen Sprachcodes nach ISO 639-1 an.Specify the language using the ISO 639-1 two-letter language code. Der Sprachcode für Englisch lautet z.B. „EN“.For example, the language code for English is EN. Der Standardwert ist „EN“ (Englisch).The default is EN (English).

Auch wenn dies optional ist, sollten Sie immer eine Sprache angeben.Although optional, you should always specify the language. In der Regel wird bei setLang dieselbe Sprache angegeben wie bei mkt, sofern der Benutzer die Zeichenfolgen der Benutzeroberfläche nicht in einer anderen Sprache anzeigen möchte.Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.

Dieser Parameter und der Header Accept-Language schließen sich gegenseitig aus. Geben Sie daher nicht beide an.This parameter and the Accept-Language header are mutually exclusive—do not specify both.

Eine Zeichenfolge der Benutzeroberfläche ist eine Zeichenfolge, die als Bezeichnung in einer Benutzeroberfläche verwendet wird.A user interface string is a string that's used as a label in a user interface. Die JSON-Antwortobjekte enthalten nur wenige Zeichenfolgen für Benutzeroberflächen.There are few user interface strings in the JSON response objects. Die angegebene Sprache wird auch in Links zu Eigenschaften von „bing.com“ in den Antwortobjekten verwendet.Also, any links to Bing.com properties in the response objects apply the specified language.
ZeichenfolgeString NeinNo

HeaderHeaders

Die folgenden Header sollten in der Anforderung angegeben werden.The following are the headers that your request should specify. Die Header Content-Type und Ocp-Apim-Subscription-Key sind die einzigen erforderlichen Header, aber Sie sollten auch User-Agent, X-MSEdge-ClientID, X-MSEdge-ClientIP und X-Search-Location hinzufügen.The Content-Type and Ocp-Apim-Subscription-Key headers are the only required headers, but you should also include User-Agent, X-MSEdge-ClientID, X-MSEdge-ClientIP, and X-Search-Location.

HeaderHeader BESCHREIBUNGDescription
Accept-LanguageAccept-Language Optionaler Anforderungsheader.Optional request header.

Eine durch Kommas getrennte Liste mit Sprachen, die für Zeichenfolgen der Benutzeroberfläche verwendet werden sollen.A comma-delimited list of languages to use for user interface strings. Die Liste ist absteigend nach Präferenz sortiert.The list is in decreasing order of preference. Weitere Informationen hierzu (sowie zum erwarteten Format) finden Sie unter RFC2616.For more information, including expected format, see RFC2616.

Dieser Header und der Abfrageparameter setLang schließen sich gegenseitig aus. Geben Sie daher nicht beide an.This header and the setLang query parameter are mutually exclusive—do not specify both.

Wenn Sie diesen Header festlegen, müssen Sie auch den Abfrageparameter cc angeben.If you set this header, you must also specify the cc query parameter. Bing verwendet die erste unterstützte Sprache aus der Liste, um den Markt zu bestimmen, für den Ergebnisse zurückgegeben werden sollen, und kombiniert sie mit dem Parameterwert cc.To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. Enthält die Liste keine unterstützte Sprache, sucht Bing die nächstgelegene Sprache und den nächstgelegenen Markt, die bzw. der die Anforderung unterstützt. Alternativ dazu wird für die Ergebnisse ein aggregierter oder Standardmarkt verwendet.If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. Wenn Sie sehen möchten, welchen Markt Bing verwendet hat, untersuchen Sie den Header BingAPIs-Market.To determine the market that Bing used, see the BingAPIs-Market header.

Verwenden Sie diesen Header und den cc-Abfrageparameter nur, wenn Sie mehrere Sprachen angeben.Use this header and the cc query parameter only if you specify multiple languages. Verwenden Sie andernfalls die Abfrageparameter mkt und setLang.Otherwise, use the mkt and setLang query parameters.

Eine Zeichenfolge der Benutzeroberfläche ist eine Zeichenfolge, die als Bezeichnung in einer Benutzeroberfläche verwendet wird.A user interface string is a string that's used as a label in a user interface. Die JSON-Antwortobjekte enthalten nur wenige Zeichenfolgen für Benutzeroberflächen.There are few user interface strings in the JSON response objects. Die Links zu Eigenschaften von „bing.com“ in den Antwortobjekten verwenden die angegebene Sprache.Any links to Bing.com properties in the response objects apply the specified language.
Content-TypeContent-Type
BingAPIs-MarketBingAPIs-Market Antwortheader.Response header.

Der von der Anforderung verwendete Markt.The market used by the request. Das Format lautet <Sprachcode>-<Ländercode>.The form is <languageCode>-<countryCode>. Beispiel: en-US.For example, en-US.
BingAPIs-TraceIdBingAPIs-TraceId Antwortheader.Response header.

Die ID des Protokolleintrags, der die Details der Anforderung enthält.The ID of the log entry that contains the details of the request. Erfassen Sie diese ID, wenn ein Fehler auftritt.When an error occurs, capture this ID. Wenn Sie das Problem nicht ermitteln und beheben können, übermitteln Sie diese ID und weitere Informationen an das Supportteam.If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Erforderlicher Anforderungsheader.Required request header.

Der Abonnementschlüssel, den Sie bei der Registrierung für diesen Dienst in Cognitive Services erhalten haben.The subscription key that you received when you signed up for this service in Cognitive Services.
PragmaPragma
User-AgentUser-Agent Optionaler Anforderungsheader.Optional request header.

Der Benutzer-Agent, von dem die Anforderung stammt.The user agent originating the request. Bing verwendet den Benutzer-Agent, um die Erfahrung mobiler Benutzer zu optimieren.Bing uses the user agent to provide mobile users with an optimized experience. Auch wenn dies optional ist, sollten Sie diesen Header immer angeben.Although optional, you are encouraged to always specify this header.

Der Benutzer-Agent sollte der Zeichenfolge entsprechen, die alle häufig verwendeten Browser senden.The user-agent should be the same string that any commonly used browser sends. Informationen zu Benutzer-Agents finden Sie in RFC 2616.For information about user-agents, see RFC 2616.

Nachfolgend einige Beispiele für Zeichenfolgen für Benutzer-Agents.The following are examples of user-agent strings.
  • Windows Phone—Mozilla/5.0 (kompatibel; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)Windows Phone—Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

  • Android—Mozilla/5.0 (Linux; U; Android 2.3.5; en-US; SCH-I500 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML; wie Gecko) Version/4.0 Mobile Safari/533.1Android—Mozilla/5.0 (Linux; U; Android 2.3.5; en-us; SCH-I500 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML; like Gecko) Version/4.0 Mobile Safari/533.1

  • iPhone—Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 wie Mac OS X) AppleWebKit/536.26 (KHTML; wie Gecko) Mobile/10B142 iPhone4;1 BingWeb/3.03.1428.20120423iPhone—Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/536.26 (KHTML; like Gecko) Mobile/10B142 iPhone4;1 BingWeb/3.03.1428.20120423

  • PC—Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; Touch; rv:11.0) wie GeckoPC—Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; Touch; rv:11.0) like Gecko

  • iPad—Mozilla/5.0 (iPad; CPU OS 7_0 wie Mac OS X) AppleWebKit/537.51.1 (KHTML, wie Gecko) Version/7.0 Mobile/11A465 Safari/9537.53iPad—Mozilla/5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53
X-MSEdge-ClientIDX-MSEdge-ClientID Optionaler Anforderungs- und Antwortheader.Optional request and response header.

Bing verwendet diesen Header, um Benutzern beim Aufrufen der Bing-API ein konsistentes Verhalten bereitzustellen.Bing uses this header to provide users with consistent behavior across Bing API calls. Bing testet häufig neue Funktionen und Verbesserungen und verwendet dabei die Client-ID als Schlüssel für die Zuweisung von Datenverkehr an verschiedene Flights.Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. Wenn Sie für einen Benutzer bei unterschiedlichen Anforderungen nicht dieselbe Client-ID verwenden, weist Bing den Benutzer möglicherweise mehreren widersprüchlichen Flights zu.If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. Die Zuweisung zu mehreren widersprüchlichen Flights kann zu einer inkonsistenten Benutzererfahrung führen.Being assigned to multiple conflicting flights can lead to an inconsistent user experience. Weist die zweite Anforderung beispielsweise eine andere Flight-Zuweisung als die erste auf, kann dies zu einer unerwarteten Benutzererfahrung führen.For example, if the second request has a different flight assignment than the first, the experience may be unexpected. Außerdem kann Bing die Client-ID zur Anpassung der Webergebnisse an den Suchverlauf dieser Client-ID verwenden. Dies führt zu einer noch besseren Benutzererfahrung.Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user.

Bing verwendet den Header auch, um die Rangfolge der Ergebnisse zu verbessern, indem es die Aktivität der Client-ID analysiert.Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. Durch die verbesserte Relevanz erhöht sich die Qualität der von Bing-APIs bereitgestellten Ergebnisse, was wiederum zu höheren Durchklickraten für den API-Consumer führt.The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer.

WICHTIG: Auch wenn er optional ist, sollten Sie diesen Header als erforderlich betrachten.IMPORTANT: Although optional, you should consider this header required. Das Beibehalten der Client-ID für dieselbe Kombination aus Benutzer und Gerät über mehrere Anforderungen hinweg ermöglicht 1) dem API-Consumer eine konsistente Benutzererfahrung sowie 2) höhere Durchklickraten durch eine bessere Qualität der Bing-API-Ergebnisse.Persisting the client ID across multiple requests for the same end user and device combination enables 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs.

Die folgenden Grundregeln gelten bei der Verwendung dieses Headers.The following are the basic usage rules that apply to this header.
  • Jeder Benutzer, der die Anwendung auf dem Gerät verwendet, muss über eine eindeutige, von Bing generierte Client-ID verfügen.Each user that uses your application on the device must have a unique, Bing generated client ID.

    Wenn Sie diesen Header nicht in die Anforderung einfügen, generiert Bing eine ID, die im Antwortheader „X-MSEdge-ClientID“ zurückgegeben wird.If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. Der einzige Zeitpunkt, zu dem dieser Header NICHT in eine Anforderung eingeschlossen werden sollte, ist bei der erstmaligen Verwendung der App auf dem Gerät.The only time that you should NOT include this header in a request is the first time the user uses your app on that device.

  • ACHTUNG: Vergewissern Sie sich, dass die Client-ID nicht mit authentifizierten Benutzerkontoinformationen verknüpft werden kann.ATTENTION: You must ensure that this Client ID is not linkable to any authenticated user account information.
  • Verwenden Sie die Client-ID für jede Anforderung der Bing-API, die die App für diesen Benutzer auf dem Gerät durchführt.Use the client ID for each Bing API request that your app makes for this user on the device.

  • Behalten Sie die Client-ID bei.Persist the client ID. Verwenden Sie ein permanentes HTTP-Cookie, um sicherzustellen, dass die ID in einer Browser-App bei allen Sitzungen verwendet wird.To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. Verwenden Sie kein Sitzungscookie.Do not use a session cookie. Verwenden Sie für andere Apps wie z.B. mobile Apps den permanenten Speicher des Geräts, um die ID beizubehalten.For other apps such as mobile apps, use the device's persistent storage to persist the ID.

    Rufen Sie bei der nächsten Verwendung der App auf dem Gerät durch den Benutzer die gespeicherte Client-ID ab.The next time the user uses your app on that device, get the client ID that you persisted.

HINWEIS: Bing-Antworten können diesen Header enthalten, müssen es aber nicht.NOTE: Bing responses may or may not include this header. Enthält die Antwort diesen Header, erfassen Sie die Client-ID, und verwenden Sie sie für alle nachfolgenden Bing-Anforderungen des Benutzers auf diesem Gerät.If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device.

HINWEIS: Wenn Sie den Header „X-MSEdge-ClientID“ einfügen, dürfen Sie in die Anforderung nicht gleichzeitig Cookies einschließen.NOTE: If you include the X-MSEdge-ClientID, you must not include cookies in the request.
X-MSEdge-ClientIPX-MSEdge-ClientIP Optionaler Anforderungsheader.Optional request header.

Die IPv4- oder IPv6-Adresse des Clientgeräts.The IPv4 or IPv6 address of the client device. Die IP-Adresse wird verwendet, um den Standort des Benutzers zu ermitteln.The IP address is used to discover the user's location. Bing verwendet die Standortinformationen für ein sicheres Suchverhalten.Bing uses the location information to determine safe search behavior.

HINWEIS: Auch wenn dies optional ist, sollten Sie diesen Header und den Header „X-Search-Location“ immer angeben.NOTE: Although optional, you are encouraged to always specify this header and the X-Search-Location header.

Verschleiern Sie nicht die Adresse (z.B. durch Ändern des letzten Oktetts in 0).Do not obfuscate the address (for example, by changing the last octet to 0). Durch Verschleiern der Adresse stimmen Ihr Standort und der tatsächliche Gerätestandort nicht überein, wodurch Bing möglicherweise fehlerhafte Ergebnisse anzeigt.Obfuscating the address results in the location not being anywhere near the device's actual location, which may result in Bing serving erroneous results.
X-Search-LocationX-Search-Location Optionaler Anforderungsheader.Optional request header.

Eine durch Semikolons getrennte Liste mit Schlüssel/Wert-Paaren, die den geografischen Standort des Clients beschreiben.A semicolon-delimited list of key/value pairs that describe the client's geographical location. Bing verwendet die Standortinformationen für ein sicheres Suchverhalten und zur Rückgabe von lokalen relevanten Inhalten.Bing uses the location information to determine safe search behavior and to return relevant local content. Geben Sie das Schlüssel-Wert-Paar im Format <Schlüssel>:<Wert> an.Specify the key/value pair as <key>:<value>. Verwenden Sie die folgenden Schlüssel zur Angabe des Benutzerstandorts:The following are the keys that you use to specify the user's location.

  • lat (erforderlich):lat—Required. Der Breitengrad des Clientstandorts (in Grad).The latitude of the client's location, in degrees. Der Breitengrad muss größer als oder gleich -90,0 und kleiner als oder gleich +90,0 sein.The latitude must be greater than or equal to -90.0 and less than or equal to +90.0. Negative Werte geben südliche Breitengrade und positive Werte nördliche Breitengrade an.Negative values indicate southern latitudes and positive values indicate northern latitudes.

  • long (erforderlich):long—Required. Der Längengrad des Clientstandorts (in Grad).The longitude of the client's location, in degrees. Der Längengrad muss größer als oder gleich -180,0 und kleiner als oder gleich +180,0 sein.The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. Negative Werte geben westliche Längengrade und positive Werte östliche Längengrade an.Negative values indicate western longitudes and positive values indicate eastern longitudes.

  • re (erforderlich):re—Required. Der Radius (in Metern), der die horizontale Genauigkeit der Koordinaten angibt.The radius, in meters, which specifies the horizontal accuracy of the coordinates. Übergeben Sie den Wert, der vom Standortdienst des Geräts zurückgegeben wird.Pass the value returned by the device's location service. Typische Werte sind 22 m für GPS/WLAN, 380 m für die Funkmasttriangulation und 18.000 m für die umgekehrte IP-Suche.Typical values might be 22 m for GPS/Wi-Fi, 380 m for cell tower triangulation, and 18,000 m for reverse IP lookup.

  • ts (optional):ts—Optional. Der UTC-Unixzeitstempel des Zeitpunkts, zu dem sich der Client am Standort befand.The UTC UNIX timestamp of when the client was at the location. (Der Unixzeitstempel gibt die Anzahl der Sekunden seit dem 1. Januar 1970 an.)(The UNIX timestamp is the number of seconds since January 1, 1970.)

  • head: Optional.head—Optional. Relatives Ziel oder Reiserichtung des Clients.The client's relative heading or direction of travel. Geben Sie die Reiserichtung von 0 bis 360 (in Grad) im Uhrzeigersinn ausgehend vom geografischen Norden an.Specify the direction of travel as degrees from 0 through 360, counting clockwise relative to true north. Geben Sie diesen Schlüssel nur an, wenn der sp-Schlüssel ungleich 0 ist.Specify this key only if the sp key is nonzero.

  • sp (optional):sp—Optional. Die horizontale Geschwindigkeit (in Metern pro Sekunde), mit der das Clientgerät unterwegs ist.The horizontal velocity (speed), in meters per second, that the client device is traveling.

  • alt (optional):alt—Optional. Die Höhe des Clientgeräts (in Metern).The altitude of the client device, in meters.

  • are (optional):are—Optional. Der Radius (in Metern), der die vertikale Genauigkeit der Koordinaten angibt.The radius, in meters, that specifies the vertical accuracy of the coordinates. Geben Sie diesen Schlüssel nur an, wenn Sie auch den alt-Schlüssel angeben.Specify this key only if you specify the alt key.

HINWEIS: Auch wenn viele der Schlüssel optional sind, werden die Standortergebnisse immer genauer, je mehr Informationen Sie bereitstellen.NOTE: Although many of the keys are optional, the more information that you provide, the more accurate the location results are.

HINWEIS: Auch wenn dies optional ist, sollten Sie den geografischen Standort des Benutzers immer angeben.NOTE: Although optional, you are encouraged to always specify the user's geographical location. Besonders wichtig ist die Standortangabe dann, wenn die IP-Adresse des Clients den physischen Standort des Benutzers nicht exakt wiedergibt (wenn der Client beispielsweise VPN verwendet).Providing the location is especially important if the client's IP address does not accurately reflect the user's physical location (for example, if the client uses VPN). Für optimale Ergebnisse sollten Sie diesen Header und den Header X-MSEdge-ClientIP einfügen. Auf jeden Fall sollten Sie aber zumindest diesen Header verwenden.For optimal results, you should include this header and the X-MSEdge-ClientIP header, but at a minimum, you should include this header.

Hinweis

Beachten Sie, dass die Anforderungen an die Verwendung und Anzeige der Bing-Suche-API die Einhaltung aller geltenden Gesetze erfordern. Dies gilt auch für die Verwendung dieses Headers.Remember that the Bing Search API use and display requirements require compliance with all applicable laws, including regarding use of these headers. Die Rechtsprechung in bestimmten Ländern (z.B. in Europa) erfordert etwa die Zustimmung des Benutzers, um bestimmte Tracking-Geräte auf Benutzergeräten platzieren zu dürfen.For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.

InhaltsformulartypenContent form types

Jede Anforderung muss den Header Content-Type enthalten.Each request must include the Content-Type header. Der Header muss festgelegt sein auf: multipart/form-data; boundary=\<boundary string\>, wobei <boundary string> eine eindeutige, nicht transparente Zeichenfolge darstellt, die die Grenze der Formulardaten angibt.The header must be set to: multipart/form-data; boundary=\<boundary string\>, where <boundary string> is a unique, opaque string that identifies the boundary of the form data. Beispiel: boundary=boundary_1234-abcd.For example, boundary=boundary_1234-abcd.

Wenn Sie der visuellen Bing-Suche ein Bildtoken oder eine URL senden, zeigt der folgende Codeausschnitt die Formulardaten an, die Sie in den Text der POST-Anforderung einfügen müssen.If you send Visual Search an image token or URL, the following snippet shows the form data you must include in the body of the POST. Die Formulardaten müssen den Content-Disposition-Header enthalten. Außerdem müssen Sie den Parameter name auf „knowledgeRequest“ festlegen.The form data must include the Content-Disposition header and you must set its name parameter to "knowledgeRequest". Einzelheiten zum imageInfo-Objekt finden Sie unter der Anforderung.For details about the imageInfo object, see the request.

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "url" : "https://contoso.com/2018/05/fashion/red.jpg"
    }
}

--boundary_1234-abcd--

Wenn Sie ein lokales Bild hochladen, zeigt der folgende Codeausschnitt die Formulardaten an, die Sie in den Text der POST-Anforderung einfügen müssen.If you upload a local image, the following snippet shows the form data you must include in the body of the POST. Die Formulardaten müssen den Header Content-Disposition enthalten.The form data must include the Content-Disposition header. Der name-Parameter muss auf „image“ festgelegt werden. Der filename-Parameter kann auf eine beliebige Zeichenfolge festgelegt werden.Its name parameter must be set to "image" and the filename parameter may be set to any string. Der Header Content-Type kann auf einen beliebigen gängigen Bild-MIME-Typ festgelegt werden.The Content-Type header may be set to any commonly used image mime type. Der Inhalt des Formulars sind die Binärdaten des Bilds.The contents of the form is the binary data of the image. Sie können eine maximale Bildgröße von 1 MB hochladen.The maximum image size you may upload is 1 MB. Die Breite oder Höhe darf maximal 1.500 Pixel betragen.The largest of the width or height should be 1,500 pixels or less.

--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="myimagefile.jpg"
Content-Type: image/jpeg

ÿØÿà JFIF ÖÆ68g-¤CWŸþ29ÌÄøÖ‘º«™æ±èuZiÀ)"óÓß°Î= ØJ9á+*G¦...

--boundary_1234-abcd--

Der folgende Codeausschnitt zeigt, wie der relevante Bereich eines hochgeladenen Bildes angegeben wird:The following snippet shows how to specify the region of interest of an uploaded image:

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "cropArea" : {
            "top" : 0.2,
            "left" : 0.3,
            "bottom" : 0.7,
            "right" : 0.6
        }
    }
}

--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: image/jpeg


ÿØÿà JFIF ÖÆ68g-¤CWŸþ29ÌÄøÖ‘º«™æ±èuZiÀ)"óÓß°Î= ØJ9á+*G¦...

--boundary_1234-abcd--

BeispielanforderungExample request

Der folgende Codeausschnitt zeigt eine vollständige Anforderung für Bildauswertungen, bei der ein Bildtoken und ein relevanter Bereich übergeben werden.The following snippet shows a complete image insights request that passes an image token and region of interest. Das Auswertungstoken stammt aus einem früheren Aufruf von „/images/search“:You get the insights token from a previous call to /images/search:

POST https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch?mkt=en-us HTTP/1.1  
Content-Type: multipart/form-data; boundary=boundary_1234-abcd
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 

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "imageInsightsToken" : "mid_D6426898706EC7..."
        "cropArea" : {
            "top" : 0.1,
            "left" : 0.2,
            "bottom" : 0.7,
            "right" : 0.5
        }
    }
}

--boundary_1234-abcd--

Antworten der visuellen Bing-SucheBing Visual Search responses

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.

Sind Informationen zu dem Bild verfügbar, enthält die Antwort ein oder mehrere tags mit den Informationen.If there are insights available for the image, the response contains one or more tags that contain the insights. Das image-Feld enthält das Auswertungstoken für das Eingabebild.The image field contains the insights token for the input image:

{
  "_type" : "ImageKnowledge",
  "tags" : [
    {...},
    {...},
    {...},
    {...},
    {...}
  ],
  "image" : {
    "imageInsightsToken" : "bcid_AF8C9CA409421B..."
  }
}

Das tags-Feld enthält einen Anzeigenamen und eine Liste mit Aktionen (Informationen).The tags field contains a display name and list of actions (insights). Eines der Tags enthält ein displayName-Feld, das auf eine leere Zeichenfolge festgelegt ist.One of the tags contains a displayName field that is set to an empty string. Dieses Tag enthält die Standardinformationen, wie z.B. Webseiten mit dem Bild, visuell ähnliche Bilder und Einkaufsquellen für abgebildete Elemente.This tag contains the default insights such as webpages that include the image, visually similar images, and shopping sources for items found in the image. Da das gesamte Bild relevant ist, enthält das Standardinformationstag keine Begrenzungsrahmen für relevante Bereiche:Because the entire image is of interest, the default insights tag doesn't include bounding boxes for the regions of interest:

{
  "_type" : "ImageKnowledge",
  "tags" : [
    {
      "displayName" : "",
      "actions" : [
        {...},
        {...},
        {...},
        {...}
      ]
    },
    {...},
    {...},
    {...},
    {...}
  ],
  "image" : {
    "imageInsightsToken" : "bcid_AF8C9CA409421B..."
  }
}

Eine Liste mit den Standardinformationen finden Sie unter Standardinformationstag.For a list of the default insights, see Default insights tag.

Die verbleibenden Tags enthalten weitere Informationen, die für den Benutzer möglicherweise relevant sind.The remaining tags contain other insights that may be of interest to the user. Enthält ein Bild beispielsweise Text, kann ein Tag etwa eine „TextResults“-Information mit dem erkannten Text beinhalten.For example, if the image contains text, one of the tags may include a TextResults insight, which contains the recognized text. Anderes Beispiel: Wenn Bing auf dem Bild eine Entität (also eine bekannte/beliebte Person oder einen entsprechenden Ort oder Gegenstand) erkennt, kann eines der Tags etwa die Entität identifizieren.Or, if Bing recognizes an entity (that is, a culturally well-known/popular person, place, or thing) in the image, one of the tags may identify the entity. Bei der visuellen Suche werden zudem verschiedene Begriffe (Tags) zurückgegeben, die vom Eingabebild abgeleitet werden.Visual Search also returns a diverse set of terms (tags) derived from the input image. Anhand dieser Tags können Benutzer Konzepte erkunden, die in dem Bild gefunden wurden.These tags enable users to explore concepts found in the image. Zeigt das Bild beispielsweise einen bekannten Sportler, kann eines der Tags etwa „Sport“ lauten und Links zu Sportbildern enthalten.For example, if the input image is of a famous athlete, one of the tags might be Sports, which contains links to images of sports.

Jedes Tag enthält einen Anzeigenamen, mit dem Sie die Information kategorisieren können, einen Begrenzungsrahmen für den relevanten Bereich, auf den sich die Information bezieht, die Informationen selbst sowie eine Miniaturansicht des Bildes.Each tag includes a display name that you can use to categorize the insight, bounding box that identifies the region of interest that the insight applies to, the insights themselves, and a thumbnail of the image. Zeigt das Bild beispielsweise eine Person in einem Sporttrikot, könnte eines der Tags etwa einen Begrenzungsrahmen um das Trikot sowie die Informationen „VisualSearch“ und „ProductVisualSearch“ enthalten.For example, if the image is of a person wearing a sports jersey, one of the tags might include a bounding box that bounds the jersey and includes VisualSearch and ProductVisualSearch insights. Ein weiteres Tag enthält möglicherweise eine „ImageResults“-Information, die eine URL für eine API-Anforderung zu „/images/search“ beinhaltet, um thematisch verknüpfte Bilder abzurufen. Oder die Information enthält eine URL zu den Ergebnissen einer Bildersuche auf „bing.com“.And another tag might include an ImageResults insight that contains a URL for an /images/search API request to get images that are topically related or a Bing.com search URL that takes the user to the Bing.com image search results.

Alle weiteren Tags, die nicht das Standardinformationstag darstellen, enthalten Begrenzungsrahmen für relevante Bereiche auf dem Bild.All tags other than the default insights tag include bounding boxes that identify regions of interest in the image. Zeigt das Bild beispielsweise mehrere erkannte Personen, können die Tags Begrenzungsrahmen für jede einzelne Person enthalten. Bei einem Bild mit erkannten Kleidungsstücken können die Tags wiederum Begrenzungsrahmen für jedes erkannte Kleidungsstück enthalten.For example, if the image includes multiple recognized people, tags could include bounding boxes for each of the people, or if the image contains recognized clothing items, tags could include bounding boxes for each recognized clothing item. Sie können die Begrenzungsrahmen zum Erstellen von Hotspots auf dem Bild verwenden, die beim Klicken Einzelheiten zu den Inhalten in diesem Bildbereich bereitstellen.You can use the bounding boxes to create hot spots over the image that when clicked, provide details about the contents in that region of the image. Sie sollten in einem Bild jedoch keine Hotspots für Begrenzungsrahmen einfügen, die das gesamte Bild identifizieren.You should not include hot spots in an image for bounding boxes that identify the entire image.

TexterkennungText recognition

Enthält das Bild Text, der vom Dienst erkannt wird, beinhaltet eines der Tags eine „TextResults“-Information (Aktion).If the image contains text that the service recognizes, one of the tags will contain a TextResults insight (action). Der displayName der Information enthält den erkannten Text.The insight's displayName contains the recognized text:

    {
        "image" : {
            "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23Text..."
        },
        "displayName" : "##TextRecognition",
        "boundingBox" : {
            "queryRectangle" : {
                "topLeft" : {"x" : 0, "y" : 0},
                "topRight" : {"x" : 1, "y" : 0},
                "bottomRight" : {"x" : 1, "y" : 1},
                "bottomLeft" : {"x" : 0, "y" : 1}
            },
            "displayRectangle" : {
                "topLeft" : {"x" : 0, "y" : 0},
                "topRight" : {"x" : 1, "y" : 0},
                "bottomRight" : {"x" : 1, "y" : 1},
                "bottomLeft" : {"x" : 0, "y" : 1}
            }
        },
        "actions" : [{
            "displayName" : "WALK BIKE ACROSS BRIDGE",
            "actionType" : "TextResults"
        }],
        "sources" : ["OCR"]
    }

Da das displayName-Feld des Tags den Inhalt „##TextRecognition“ enthält, verwenden Sie den Begriff nicht als Kategorietitel in der Benutzeroberfläche.Because the tag's displayName field contains ##TextRecognition, do not use it as a category title in the UX. Dasselbe gilt für alle Anzeigenamen, die mit „##“ beginnen.That goes for any display name that starts with ##. Verwenden Sie stattdessen den Anzeigenamen der Aktion.Instead, use the action's display name.

Mit der Texterkennung können auch die Kontaktinformationen auf Visitenkarten wie etwa Telefonnummern und E-Mail-Adressen erkannt werden.Text recognition can also recognize the contact information on business cards, such as phone numbers and email addresses. Der Begrenzungsrahmen identifiziert den Ort der Kontaktinformationen auf der Karte.The bounding box identifies the location of the contact information on the card.

    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.635, "y" : 0},
          "topRight" : {"x" : 0.77, "y" : 0},
          "bottomRight" : {"x" : 0.77, "y" : 0.4873333},
          "bottomLeft" : {"x" : 0.635, "y" : 0.4873333}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.635, "y" : 0},
          "topRight" : {"x" : 0.77, "y" : 0},
          "bottomRight" : {"x" : 0.77, "y" : 0.4873333},
          "bottomLeft" : {"x" : 0.635, "y" : 0.4873333}
        }
      },
      "actions" : [
        {
          "url" : "tel:888%20555%201212",
          "actionType" : "Uri"
        }
      ],
      "sources" : ["OCR"]
    },
    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.63, "y" : 0},
          "topRight" : {"x" : 0.866, "y" : 0},
          "bottomRight" : {"x" : 0.866, "y" : 0.5553334},
          "bottomLeft" : {"x" : 0.63, "y" : 0.5553334}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.63, "y" : 0},
          "topRight" : {"x" : 0.866, "y" : 0},
          "bottomRight" : {"x" : 0.866, "y" : 0.5553334},
          "bottomLeft" : {"x" : 0.63, "y" : 0.5553334}
        }
      },
      "actions" : [
        {
          "url" : "mailto:someone@outlook.com",
          "actionType" : "Uri"
        }
      ],
      "sources" : ["OCR"]
    },
    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0, "y" : 0},
          "topRight" : {"x" : 1, "y" : 0},
          "bottomRight" : {"x" : 1, "y" : 1},
          "bottomLeft" : {"x" : 0, "y" : 1}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0, "y" : 0},
          "topRight" : {"x" : 1, "y" : 0},
          "bottomRight" : {"x" : 1, "y" : 1},
          "bottomLeft" : {"x" : 0, "y" : 1}
        }
      },
      "actions" : [
        {
          "displayName" : "CHARLENE WHITNEY Graphic Designer 888 555 1212 someone@outlook.com www.contoso.com",
          "actionType" : "TextResults"
        }
      ],
      "sources" : ["OCR"]
    }

Enthält das Bild eine erkannte Entität (beispielsweise eine bekannte/beliebte Person oder einen entsprechenden Ort oder Gegenstand), kann eines der Tags eine Entitätsinformation beinhalten.If the image contains a recognized entity such as a culturally well-known/popular person, place, or thing, one of the tags may include an Entity insight.

    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Statue+of+Liberty..."
      },
      "displayName" : "Statue of Liberty",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.40625, "y" : 0.1757813},
          "topRight" : {"x" : 0.6171875, "y" : 0.1757813},
          "bottomRight" : {"x" : 0.6171875, "y" : 0.3867188},
          "bottomLeft" : {"x" : 0.40625, "y" : 0.3867188}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.40625, "y" : 0.1757813},
          "topRight" : {"x" : 0.6171875, "y" : 0.1757813},
          "bottomRight" : {"x" : 0.6171875, "y" : 0.3867188},
          "bottomLeft" : {"x" : 0.40625, "y" : 0.3867188}
        }
      },
      "actions" : [
        {
          "_type" : "ImageEntityAction",
          "webSearchUrl" : "https:\/\/www.bing.com\/search?q=Statue+of+Liberty",
          "displayName" : "Statue of Liberty",
          "actionType" : "Entity",
        }
      ]
    }

Weitere InformationenSee also