Chiamare l'API Image Analysis 3.2

Questo articolo illustra come chiamare l'API Image Analysis 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. Se questi passaggi non sono stati eseguiti, seguire la guida introduttiva per iniziare.

Inviare dati al servizio

Il codice in questa guida usa 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 come segue: {"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 Analizza consente di accedere a tutte le funzionalità di analisi delle immagini del servizio. Scegliere le operazioni da eseguire in base al proprio caso d'uso. Per una descrizione di ogni funzionalità, vedere la panoramica . Gli esempi nelle sezioni seguenti aggiungono tutte le funzionalità visive disponibili, ma per un utilizzo pratico sarà probabilmente necessario solo uno o due.

È possibile specificare le funzionalità da usare impostando i parametri di query URL dell'API Analyze. Un parametro può avere più valori, separati da virgole. Ogni funzionalità specificata richiederà 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 il linguaggio. Il valore predefinito è en.

Parametro URL Valore Descrizione
language en italiano
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 e 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 200 risposta HTTP 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 - Sono disponibili altri dettagli nel messaggio di errore.
  • 415 - Errore del 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 dell'immagine.
    • InternalServerError

Suggerimento

Durante l'uso di Visione artificiale di Azure, è possibile che si verifichino errori temporanei causati dai limiti di frequenza applicati dal servizio o da altri problemi temporanei, ad esempio interruzioni di rete. Per informazioni sulla gestione di questi tipi di errori, vedere Modello di ripetizione dei tentativi nella guida Modelli di progettazione cloud e l'articolo correlato Modello a interruttore.

Passaggi successivi

  • Per altre informazioni su ogni funzionalità, vedere gli articoli sul concetto.
  • Per altre informazioni sulle funzionalità dell'API, vedere le informazioni di riferimento sulle API.