De Afbeeldingsanalyse 3.2-API aanroepen

In dit artikel wordt gedemonstreerde hoe u de API voor afbeeldingsanalyse 3.2 aanroept om informatie te retourneren over de visuele functies van een afbeelding. U ziet ook hoe u de geretourneerde informatie kunt parseren met behulp van de client-SDK's of REST API.

In deze handleiding wordt ervan uitgegaan dat u al een Vision-resource hebt gemaakt en een sleutel- en eindpunt-URL hebt verkregen. Als u een client-SDK gebruikt, moet u ook een clientobject verifiëren. Als u deze stappen nog niet hebt uitgevoerd, volgt u de quickstart om aan de slag te gaan.

Gegevens verzenden naar de service

De code in deze handleiding maakt gebruik van externe afbeeldingen waarnaar wordt verwezen door de URL. U kunt zelf verschillende afbeeldingen proberen om de volledige mogelijkheden van de functies voor afbeeldingsanalyse te bekijken.

Bij het analyseren van een externe afbeelding geeft u de URL van de afbeelding op door de hoofdtekst van de aanvraag als volgt op te maken: {"url":"http://example.com/images/test.jpg"}

Als u een lokale afbeelding wilt analyseren, plaatst u de binaire afbeeldingsgegevens in de hoofdtekst van de HTTP-aanvraag.

Bepalen hoe de gegevens moeten worden verwerkt

Visuele functies selecteren

De Analyze-API biedt u toegang tot alle functies van de afbeeldingsanalyse van de service. Kies welke bewerkingen u wilt uitvoeren op basis van uw eigen use-case. Zie het overzicht voor een beschrijving van elke functie. In de voorbeelden in de onderstaande secties worden alle beschikbare visuele functies toegevoegd, maar voor praktisch gebruik hebt u waarschijnlijk slechts één of twee nodig.

U kunt opgeven welke functies u wilt gebruiken door de URL-queryparameters van de Analyse-API in te stellen. Een parameter kan meerdere waarden hebben, gescheiden door komma's. Elke functie die u opgeeft, vereist meer rekentijd, dus geef alleen op wat u nodig hebt.

URL-parameter Weergegeven als Beschrijving
features Read leest de zichtbare tekst in de afbeelding en voert deze uit als gestructureerde JSON-gegevens.
features Description beschrijft de inhoud van de afbeelding met een volledige zin in ondersteunde talen.
features SmartCrops zoekt de rechthoekcoördinaten die de afbeelding bijsnijden tot een gewenste hoogte-breedteverhouding, terwijl het interessegebied behouden blijft.
features Objects detecteert verschillende objecten in een afbeelding, inclusief de geschatte locatie. Het argument Objecten is alleen beschikbaar in het Engels.
features Tags tagt de afbeelding met een gedetailleerde lijst met woorden die betrekking hebben op de inhoud van de afbeelding.

Een ingevulde URL kan er als volgt uitzien:

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

Talen opgeven

U kunt ook de taal van de geretourneerde gegevens opgeven.

Met de volgende URL-queryparameter wordt de taal opgegeven. De standaardwaarde is en.

URL-parameter Weergegeven als Beschrijving
language en Engels
language es Spaans
language ja Japans
language pt Portugees
language zh Vereenvoudigd Chinees

Een ingevulde URL kan er als volgt uitzien:

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

Resultaten ophalen van de service

In deze sectie ziet u hoe u de resultaten van de API-aanroep kunt parseren. Het bevat de API-aanroep zelf.

Notitie

Scoped API-aanroepen

Sommige van de functies in Afbeeldingsanalyse kunnen rechtstreeks worden aangeroepen en via de Analyse-API-aanroep. U kunt bijvoorbeeld een scoped analyse uitvoeren van alleen afbeeldingstags door een aanvraag naar (of naar de bijbehorende methode in de SDK) te <endpoint>/vision/v3.2/tag doen. Raadpleeg de referentiedocumentatie voor andere functies die afzonderlijk kunnen worden aangeroepen.

De service retourneert een 200 HTTP-antwoord en de hoofdtekst bevat de geretourneerde gegevens in de vorm van een JSON-tekenreeks. De volgende tekst is een voorbeeld van een JSON-antwoord.

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

Foutcodes

Bekijk de volgende lijst met mogelijke fouten en de oorzaken ervan:

  • 400
    • InvalidImageUrl - Afbeeldings-URL is onjuist opgemaakt of niet toegankelijk.
    • InvalidImageFormat - Invoergegevens zijn geen geldige afbeelding.
    • InvalidImageSize - Invoerafbeelding is te groot.
    • NotSupportedVisualFeature - Het opgegeven functietype is niet geldig.
    • NotSupportedImage - Niet-ondersteunde afbeelding, bijvoorbeeld kinderporno.
    • InvalidDetails - Niet-ondersteunde detail parameterwaarde.
    • NotSupportedLanguage - De aangevraagde bewerking wordt niet ondersteund in de opgegeven taal.
    • BadArgument - Meer informatie vindt u in het foutbericht.
  • 415 - Fout bij niet-ondersteund mediatype. Het inhoudstype bevindt zich niet in de toegestane typen:
    • Voor een afbeeldings-URL moet inhoudstype zijn application/json
    • Voor binaire afbeeldingsgegevens moet inhoudstype zijn application/octet-stream of multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - Er is een time-out opgetreden voor de verwerking van afbeeldingen.
    • InternalServerError

Tip

Tijdens het werken met Azure AI Vision kunnen tijdelijke fouten optreden die worden veroorzaakt door frequentielimieten die door de service worden afgedwongen of andere tijdelijke problemen, zoals netwerkstoringen. Raadpleeg voor meer informatie over het verwerken van dit soort fouten Patroon voor opnieuw proberen in de handleiding Cloudontwerppatronen en de verwante Patroon Circuitonderbreker.

Volgende stappen