Condividi tramite


Chiamare l'API di analisi immagini 3.2

Questo articolo illustra come chiamare l'API Image Analysis versione 3.2 per restituire informazioni sulle funzionalità visive di un'immagine. Illustra anche come analizzare le informazioni restituite usando gli SDK client o l'API REST.

Questa guida presuppone che sia già stata creata una risorsa di Visione e ottenuta una chiave e un URL dell'endpoint. Se si usa un SDK client, è anche necessario autenticare un oggetto client. Per altre informazioni su questi passaggi, vedere l'argomento di avvio rapido sull'analisi delle immagini.

Inviare dati al servizio

Il codice riportato in questa guida si avvale di immagini remote a cui fa riferimento l'URL. È possibile provare immagini diverse autonomamente per visualizzare la funzionalità completa delle funzionalità di analisi delle immagini.

Quando si analizza un'immagine remota, si specifica l'URL dell'immagine formattando il corpo della richiesta, nel modo seguente: {"url":"http://example.com/images/test.jpg"}.

Per analizzare un'immagine locale, inserire i dati dell'immagine binaria nel corpo della richiesta HTTP.

Determinare come elaborare i dati

Selezionare le funzionalità visive

L'API Analisi consente di accedere a tutte le funzionalità di analisi delle immagini del servizio. Scegliere le operazioni da eseguire in base al caso d'uso specifico. Per una descrizione di ogni funzionalità, vedere Panoramica di Visione artificiale di Azure. Gli esempi nelle sezioni seguenti aggiungono tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario solo uno o due.

È possibile specificare le funzionalità da usare impostando i parametri di query URL dell'API Analisi. Un parametro può avere più valori, separati da virgole. Ogni funzionalità specificata richiede più tempo di calcolo, quindi specificare solo gli elementi necessari.

Parametro URL Valore Descrizione
features Read legge il testo visibile nell'immagine e lo restituisce come dati JSON strutturati
features Description descrive il contenuto dell'immagine con una frase completa nelle lingue supportate
features SmartCrops trova le coordinate del rettangolo che ritaglierebbero l'immagine in proporzioni desiderate mantenendo l'area di interesse
features Objects rileva vari oggetti all'interno di un'immagine, inclusa la posizione approssimativa. L'argomento Objects è disponibile solo in inglese
features Tags contrassegna l'immagine con un elenco dettagliato di parole correlate al contenuto dell'immagine

Un URL popolato potrebbe essere simile al seguente:

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

Specificare le lingue

È anche possibile specificare la lingua dei dati restituiti.

Il parametro di query URL seguente specifica la lingua. Il valore predefinito è en.

Parametro URL Valore Descrizione
language en Inglese
language es Spagnolo
language ja Giapponese
language pt Portoghese
language zh Cinese semplificato

Un URL popolato potrebbe essere simile al seguente:

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

Ottenere risultati dal servizio

Questa sezione illustra come analizzare i risultati della chiamata API. Include la chiamata API stessa.

Nota

Chiamate API con ambito

Alcune delle funzionalità di Analisi immagini possono essere chiamate direttamente o tramite la chiamata API Analyze. Ad esempio, è possibile eseguire un'analisi con ambito solo dei tag immagine effettuando una richiesta a <endpoint>/vision/v3.2/tag (o al metodo corrispondente nell'SDK). Vedere la documentazione di riferimento per altre funzionalità che è possibile chiamare separatamente.

Il servizio restituisce una risposta HTTP 200 e il corpo contiene i dati restituiti sotto forma di stringa JSON. Il testo seguente è un esempio di risposta JSON.

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

Codici di errore

Vedere l'elenco seguente di possibili errori e delle relative cause:

  • 400
    • InvalidImageUrl - L'URL dell'immagine non è formattato o non è accessibile
    • InvalidImageFormat - I dati di input non sono un'immagine valida
    • InvalidImageSize - L'immagine di input è troppo grande
    • NotSupportedVisualFeature - Il tipo di funzionalità specificato non è valido
    • NotSupportedImage - Immagine non supportata, ad esempio pornografia infantile
    • InvalidDetails- Valore del parametro non supportato detail
    • NotSupportedLanguage - L'operazione richiesta non è supportata nella lingua specificata
    • BadArgument - Altri dettagli sono disponibili nel messaggio di errore
  • 415 - Errore tipo di supporto non supportato. Content-Type non è nei tipi consentiti:
    • Per un URL di immagine, Content-Type deve essere application/json
    • Per i dati di un'immagine binaria, Content-Type deve essere application/octet-stream o multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - Timeout dell'elaborazione delle immagini
    • InternalServerError

Suggerimento

Durante l'uso di Visione di Azure AI, potrebbero verificarsi errori temporanei causati dai limiti di velocità applicati dal servizio, o altri problemi temporanei come interruzioni della rete. Per informazioni sulla gestione di questi tipi di errori, vedere il modello Di ripetizione dei tentativi nella guida Modelli di progettazione cloud e il modello di interruttore correlato.