Schnellstart: Gewinnen von Erkenntnissen zu Bildern mit der REST-API für die visuelle Bing-Suche und C#

Artikel
05/22/2020

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.

In dieser Schnellstartanleitung erfahren Sie, wie Sie ein Bild an die API für die visuelle Bing-Suche hochladen und die zurückgegebenen Erkenntnisse anzeigen.

Voraussetzungen

Eine beliebige Edition von Visual Studio 2019.
Json.NET-Framework (verfügbar als NuGet-Paket).
Unter Linux/macOS können Sie diese Anwendung mit Mono ausführen.

Erstellen einer Azure-Ressource

Beginnen Sie mit der Verwendung der API für die visuelle Bing-Suche, indem Sie eine der folgenden Azure-Ressourcen erstellen:

Ressource für Bing-Suche v7

Verfügbar über das Azure-Portal, bis Sie die Ressource löschen.
Wählen Sie den S9-Tarif aus.

Ressource für mehrere Dienste

Verfügbar über das Azure-Portal, bis Sie die Ressource löschen.
Verwenden Sie in allen Azure KI Services-Instanzen denselben Schlüssel und Endpunkt für Ihre Anwendungen.

Erstellen und Initialisieren eines Projekts

Erstellen Sie in Visual Studio eine neue Konsolenprojektmappe namens „BingSearchApisQuickStart“. Fügen Sie der Hauptcodedatei die folgenden Namespaces hinzu:
```
using System;
using System.Text;
using System.Net;
using System.IO;
using System.Collections.Generic;
```
Fügen Sie Variablen für Ihren Abonnementschlüssel, für den Endpunkt und für den Pfad des hochzuladenden Bilds hinzu. Für den uriBase-Wert können Sie den globalen Endpunkt im folgenden Code oder den Endpunkt der benutzerdefinierten Unterdomäne verwenden, der im Azure-Portal für Ihre Ressource angezeigt wird.
```
    const string accessKey = "<my_subscription_key>";
    const string uriBase = "https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch";
    static string imagePath = @"<path_to_image>";
```

Erstellen Sie eine Methode namens GetImageFileName(), um den Pfad für Ihr Bild abzurufen.

static string GetImageFileName(string path)
        {
            return new FileInfo(path).Name;
        }

Erstellen Sie eine Methode, um die Binärdaten des Bilds abzurufen.

static byte[] GetImageBinary(string path)
{
    return File.ReadAllBytes(path);
}

Erstellen der Formulardaten

Wenn Sie ein lokales Bild hochladen möchten, erstellen Sie zunächst die Formulardaten für die Übermittlung an die API. Die Formulardaten enthalten den Content-Disposition-Header, den name-Parameter, der auf „image“ festgelegt ist, und den filename-Parameter, der auf den Dateinamen des Bilds festgelegt ist. Der Inhalt des Formulars umfasst die Binärdaten des Bilds. Das hochzuladende Bild darf maximal 1 MB groß sein.
```
--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="myimagefile.jpg"

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

--boundary_1234-abcd--
```

Fügen Sie Begrenzungszeichenfolgen hinzu, um die POST-Formulardaten zu formatieren. Begrenzungszeichenfolgen dienen zum Definieren der Start-, End- und Zeilenumbruch-Zeichen für die Daten.

// Boundary strings for form data in body of POST.
const string CRLF = "\r\n";
static string BoundaryTemplate = "batch_{0}";
static string StartBoundaryTemplate = "--{0}";
static string EndBoundaryTemplate = "--{0}--";

Verwenden Sie die folgenden Variablen, um den Formulardaten Parameter hinzuzufügen:

const string CONTENT_TYPE_HEADER_PARAMS = "multipart/form-data; boundary={0}";
const string POST_BODY_DISPOSITION_HEADER = "Content-Disposition: form-data; name=\"image\"; filename=\"{0}\"" + CRLF +CRLF;

Erstellen Sie eine Funktion namens BuildFormDataStart(), um den Beginn der Formulardaten zu erstellen. Verwenden Sie dabei die Begrenzungszeichenfolgen und den Bildpfad.

    static string BuildFormDataStart(string boundary, string filename)
    {
        var startBoundary = string.Format(StartBoundaryTemplate, boundary);

        var requestBody = startBoundary + CRLF;
        requestBody += string.Format(POST_BODY_DISPOSITION_HEADER, filename);

        return requestBody;
    }

Erstellen Sie eine Funktion namens BuildFormDataEnd(), um das Ende der Formulardaten zu erstellen. Verwenden Sie dabei die Begrenzungszeichenfolgen.

    static string BuildFormDataEnd(string boundary)
    {
        return CRLF + CRLF + string.Format(EndBoundaryTemplate, boundary) + CRLF;
    }

Aufrufen der API für die visuelle Bing-Suche

Erstellen Sie eine Funktion, um den Endpunkt für die visuelle Bing-Suche aufzurufen und die JSON-Antwort zurückzugeben. Die Funktion verwendet den Beginn und das Ende der Formulardaten, ein Bytearray mit den Bilddaten und einen Wert vom Typ contentType.
Verwenden Sie ein WebRequest-Objekt zum Speichern von URI, ContentType-Wert und Headern.

Verwenden Sie request.GetRequestStream(), um Ihre Formular- und Bilddaten zu schreiben, und rufen Sie anschließend die Antwort ab. Ihre Funktion sollte in etwa wie der folgende Code aussehen:

    static string BingImageSearch(string startFormData, string endFormData, byte[] image, string contentTypeValue)
    {
        WebRequest request = HttpWebRequest.Create(uriBase);
        request.ContentType = contentTypeValue;
        request.Headers["Ocp-Apim-Subscription-Key"] = accessKey;
        request.Method = "POST";

        // Writes the boundary and Content-Disposition header, then writes
        // the image binary, and finishes by writing the closing boundary.
        using (Stream requestStream = request.GetRequestStream())
        {
            StreamWriter writer = new StreamWriter(requestStream);
            writer.Write(startFormData);
            writer.Flush();
            requestStream.Write(image, 0, image.Length);
            writer.Write(endFormData);
            writer.Flush();
            writer.Close();
        }

        HttpWebResponse response = (HttpWebResponse)request.GetResponseAsync().Result;
        string json = new StreamReader(response.GetResponseStream()).ReadToEnd();

        return json;
    }

Erstellen der Methode „Main“

Rufen Sie in der Methode Main() Ihrer Anwendung den Dateinamen und die Binärdaten Ihres Bilds ab.
```
var filename = GetImageFileName(imagePath);
var imageBinary = GetImageBinary(imagePath);
```

Richten Sie den POST-Text ein, indem Sie seine Begrenzung formatieren. Rufen Sie dann BuildFormDataStart() und BuildFormDataEnd() auf, um die Formulardaten zu erstellen.

// Set up POST body.
var boundary = string.Format(BoundaryTemplate, Guid.NewGuid());
var startFormData = BuildFormDataStart(boundary, filename);
var endFormData = BuildFormDataEnd(boundary);

Erstellen Sie den Wert vom Typ ContentType, indem Sie CONTENT_TYPE_HEADER_PARAMS und die Begrenzung für Formulardaten formatieren.
```
var contentTypeHdrValue = string.Format(CONTENT_TYPE_HEADER_PARAMS, boundary);
```

Rufen Sie BingImageSearch() auf, um die API-Antwort abzurufen, und geben Sie dann die Antwort aus.

var json = BingImageSearch(startFormData, endFormData, imageBinary, contentTypeHdrValue);
Console.WriteLine(json);
Console.WriteLine("enter any key to continue");
Console.readKey();

Verwenden von HTTPClient

Bei Verwendung von HttpClient können die Formulardaten mithilfe der Klasse MultipartFormDataContent erstellt werden. Verwenden Sie die folgenden Codeabschnitte, um die entsprechenden Methoden aus dem vorherigen Beispiel zu ersetzen:

Ersetzen Sie die Main()-Methode durch den folgenden Code:

        static void Main()
        {
            try
            {
                Console.OutputEncoding = System.Text.Encoding.UTF8;

                if (accessKey.Length == 32)
                {
                    if (IsImagePathSet(imagePath))
                    {
                        var filename = GetImageFileName(imagePath);
                        Console.WriteLine("Getting image insights for image: " + filename);
                        var imageBinary = GetImageBinary(imagePath);

                        var boundary = string.Format(BoundaryTemplate, Guid.NewGuid());
                        var json = BingImageSearch(imageBinary, boundary, uriBase, accessKey);

                        Console.WriteLine("\nJSON Response:\n");
                        Console.WriteLine(JsonPrettyPrint(json));
                    }
                }
                else
                {
                    Console.WriteLine("Invalid Bing Visual Search API subscription key!");
                    Console.WriteLine("Please paste yours into the source code.");
                }

                Console.Write("\nPress Enter to exit ");
                Console.ReadLine();
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }

Ersetzen Sie die BingImageSearch()-Methode durch den folgenden Code:

        /// <summary>
        /// Calls the Bing visual search endpoint and returns the JSON response.
        /// </summary>
        static string BingImageSearch(byte[] image, string boundary, string uri, string subscriptionKey)
        {
            var requestMessage = new HttpRequestMessage(HttpMethod.Post, uri);
            requestMessage.Headers.Add("Ocp-Apim-Subscription-Key", accessKey);

            var content = new MultipartFormDataContent(boundary);
            content.Add(new ByteArrayContent(image), "image", "myimage");
            requestMessage.Content = content;

            var httpClient = new HttpClient();

            Task<HttpResponseMessage> httpRequest = httpClient.SendAsync(requestMessage, HttpCompletionOption.ResponseContentRead, CancellationToken.None);
            HttpResponseMessage httpResponse = httpRequest.Result;
            HttpStatusCode statusCode = httpResponse.StatusCode;
            HttpContent responseContent = httpResponse.Content;

            string json = null;

            if (responseContent != null)
            {
                Task<String> stringContentsTask = responseContent.ReadAsStringAsync();
                json = stringContentsTask.Result;
            }

            return json;
        }

Nächste Schritte

Erstellen einer Single-Page-Web-App für die Visuelle Suche

Freigeben über