Freigeben über


Aufrufen der Bildanalyse 3.2-API

In diesem Artikel wird veranschaulicht, wie Sie die Bildanalyse 3.2-API aufrufen, um Informationen zu den visuellen Features eines Bilds zurückzugeben. Außerdem wird gezeigt, wie Sie die zurückgegebenen Informationen mithilfe der Client-SDKs oder der REST-API analysieren.

In diesem Leitfaden wird davon ausgegangen, dass Sie bereits eine Vision-Ressource erstellt sowie einen Schlüssel und eine Endpunkt-URL abgerufen haben. Wenn Sie ein Client-SDK verwenden, müssen Sie außerdem ein Clientobjekt authentifizieren. Wenn Sie diese Schritte nicht ausgeführt haben, führen Sie die Schnellstartanleitung aus, um zu beginnen.

Übermitteln von Daten an den Dienst

Der Code in diesem Leitfaden verwendet Remotebilder, auf die über URL verwiesen wird. Möglicherweise möchten Sie selbst verschiedene Bilder ausprobieren, um das ganze Potenzial der Bildanalysefeatures zu erfahren.

Beim Analysieren eines Remotebilds geben Sie die URL des Bilds an, indem Sie den Anforderungstext wie folgt formatieren: {"url":"http://example.com/images/test.jpg"}.

Zur Analyse eines lokalen Bilds platzieren Sie die binären Bilddaten im HTTP-Anforderungstext.

Festlegen, wie die Daten verarbeitet werden sollen

Auswählen visueller Merkmale

Die Analyse-API bietet Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. In den Beispielen in den nachfolgenden Abschnitten werden alle verfügbaren visuellen Features hinzugefügt, aber in der Praxis benötigen Sie wahrscheinlich nur eins oder zwei.

Sie können angeben, welche Funktionen Sie verwenden möchten, indem Sie die URL-Abfrageparameter der Analyse-API festlegen. Ein Parameter kann mehrere, durch Kommas getrennte Werte enthalten. Für jedes von Ihnen angegebene Feature ist weitere Berechnungszeit erforderlich. Geben Sie daher nur die benötigten Features an.

URL-Parameter Wert BESCHREIBUNG
features Read Liest den sichtbaren Text auf dem Bild und gibt ihn als strukturierte JSON-Daten aus
features Description Beschreibt den Bildinhalt in unterstützten Sprachen mit einem vollständigen Satz.
features SmartCrops Findet die Rechteckkoordinaten, die das Bild in ein gewünschtes Seitenverhältnis zuschneiden würden, während der relevante Bereich beibehalten wird
features Objects Erkennt verschiedene Objekte in einem Bild, einschließlich der ungefähren Position. Das Objects-Argument ist nur für Englisch verfügbar.
features Tags Erstellt Tags für das Bild in einer detaillierten Liste aus Wörtern, die sich auf den Bildinhalt beziehen.

Eine aufgefüllte URL kann folgendermaßen aussehen:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags

Angeben von Sprachen

Sie können auch die Sprache der zurückgegebenen Daten angeben.

Die Sprache wird mit dem folgenden URL-Abfrageparameter angegeben. Standardwert: en.

URL-Parameter Wert Beschreibung
language en Englisch
language es Spanisch
language ja Japanisch
language pt Portugiesisch (Portugal)
language zh Chinesisch (vereinfacht)

Eine aufgefüllte URL kann folgendermaßen aussehen:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags&language=en

Abrufen von Ergebnissen aus dem Dienst

In diesem Abschnitt wird gezeigt, wie Sie die Ergebnisse des API-Aufrufs analysieren. Er enthält den eigentlichen API-Aufruf.

Hinweis

Bereichsbezogene API-Aufrufe

Einige der Funktionen in der Bildanalyse können sowohl direkt als auch über den Aufruf der Analyse-API aufgerufen werden. Sie können beispielsweise eine Bereichsanalyse nur von Bildtags durchführen, indem Sie eine Anforderung an <endpoint>/vision/v3.2/tag (oder an die entsprechende Methode im SDK) vornehmen. Informationen zu weiteren Funktionen, die separat aufgerufen werden können, finden Sie in der Referenzdokumentation.

Der Dienst gibt eine 200-HTTP-Antwort zurück, und der Text enthält die zurückgegebenen Daten in Form einer JSON-Zeichenfolge. Der folgende Text ist ein Beispiel für eine JSON-Antwort:

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

Fehlercodes

Die folgende Liste enthält mögliche Fehler und ihre Ursachen:

  • 400
    • InvalidImageUrl: Die Bild-URL ist falsch formatiert, oder es kann nicht darauf zugegriffen werden.
    • InvalidImageFormat: Bei den Eingabedaten handelt es sich nicht um ein gültiges Bild.
    • InvalidImageSize: Das Eingabebild ist zu groß.
    • NotSupportedVisualFeature: Der angegebene Merkmaltyp ist ungültig.
    • NotSupportedImage: Nicht unterstütztes Bild, z. B. Kinderpornografie.
    • InvalidDetails: Nicht unterstützter Wert des detail-Parameters.
    • NotSupportedLanguage: Der angeforderte Vorgang wird in der angegebenen Sprache nicht unterstützt.
    • BadArgument: Weitere Details werden in der Fehlermeldung bereitgestellt.
  • Fehler 415: Nicht unterstützter Medientyp. Für den Inhaltstyp ist kein zulässiger Typ angegeben:
    • Für eine Bild-URL sollte „Content-Type“ den Wert application/json haben.
    • Für binäre Bilddaten sollte „Content-Type“ den Wert application/octet-stream oder multipart/form-data haben.
  • 500
    • FailedToProcess
    • Timeout: Timeout bei der Bildverarbeitung.
    • InternalServerError

Tipp

Bei der Verwendung von Azure KI Vision kann es zu vorübergehenden Fehlern kommen. Diese können auf durch den Dienst erzwungene Ratengrenzwerte oder andere vorübergehende Probleme (etwa Netzwerkausfälle) zurückzuführen sein. Informationen zur Behandlung solcher Fehler finden Sie im Leitfaden für Cloudentwurfsmuster unter Wiederholungsmuster sowie unter dem dazugehörigen Trennschalter-Muster.

Nächste Schritte

  • Erkunden Sie die Konzeptartikel, um mehr über die einzelnen Features zu erfahren.
  • Weitere Informationen zur API-Funktionalität finden Sie in der API-Referenz.