Condividi tramite

Chiamare l'API Analyze di Analisi delle immagini 4.0

  • Articolo

Questo articolo descrive come chiamare l'API Analisi delle immagini 4.0 per restituire informazioni sulle funzionalità visive di un'immagine. Illustra anche come analizzare le informazioni restituite.

Prerequisiti

Questa guida presuppone che siano stati seguiti i passaggi indicati nella pagina di avvio rapido. Ciò significa:

  • È stata creata una risorsa Visione artificiale ottenendo una chiave e l'URL dell'endpoint.
  • Il pacchetto SDK appropriato è installato ed è disponibile un'applicazione di avvio rapido in esecuzione. È possibile modificare questa applicazione di avvio rapido in base a esempi di codice riportati qui.

Creare ed autenticare il client

Per eseguire l'autenticazione con il servizio Analisi immagini, è necessario disporre di una chiave Visione artificiale e di un URL dell'endpoint. Questa guida presuppone che siano state definite le variabili di ambiente VISION_KEY e VISION_ENDPOINT con la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

Per iniziare, creare un oggetto ImageAnalysisClient. Ad esempio:

string endpoint = Environment.GetEnvironmentVariable("VISION_ENDPOINT");
string key = Environment.GetEnvironmentVariable("VISION_KEY");

// Create an Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClient(
    new Uri(endpoint),
    new AzureKeyCredential(key));

Selezionare l'immagine che si desidera analizzare

È possibile selezionare un'immagine fornendo un URL di immagine accessibile pubblicamente o passando i dati binari all'SDK. Vedere Requisiti delle immagini per i formati di immagine supportati.

Image URL

Creare un oggetto Uri per l'immagine da analizzare.

Uri imageURL = new Uri("https://aka.ms/azsdk/image-analysis/sample.jpg");

Buffer delle immagini

In alternativa, è possibile passare i dati dell'immagine all'SDK tramite un oggetto BinaryData. Ad esempio, leggere da un file di immagine locale che si vuole analizzare.

using FileStream stream = new FileStream("sample.jpg", FileMode.Open);
BinaryData imageData = BinaryData.FromStream(stream);

Selezionare le funzionalità visive

L'API Analisi delle immagini 4.0 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à, fare riferimento alla panoramica. L'esempio in questa sezione aggiunge tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario un numero inferiore di funzionalità.

Importante

Le funzionalità visive Captions e DenseCaptions sono supportate solo in determinate aree di Azure: vedere Disponibilità dell'area

VisualFeatures visualFeatures =
    VisualFeatures.Caption |
    VisualFeatures.DenseCaptions |
    VisualFeatures.Objects |
    VisualFeatures.Read |
    VisualFeatures.Tags |
    VisualFeatures.People |
    VisualFeatures.SmartCrops;

Selezionare le opzioni di analisi

Usare un oggetto ImageAnalysisOptions per specificare varie opzioni per la chiamata all'API Analizza immagine.

  • Lingua: È possibile specificare la lingua dei dati restituiti. La lingua è facoltativa e per impostazione predefinita è impostata sull'inglese. Per un elenco dei codici delle lingue supportate e delle funzionalità visive supportate per ogni lingua, vedere Supporto delle lingue.
  • Sottotitoli di genere neutro: se si estraggono sottotitoli o sottotitoli densi (usando VisualFeatures.Caption o VisualFeatures.DenseCaptions), è possibile richiedere sottotitoli indipendenti dal genere. I sottotitoli neutri sono facoltativi; l'impostazione predefinita prevede sottotitoli con distinzione di genere. Ad esempio, in inglese, quando si selezionano le didascalie neutre, termini come woman (donna) o man (uomo) vengono sostituiti con person (persona), mentre boy (ragazzo) o girl (ragazza) vengono sostituiti con child.
  • Proporzioni del ritaglio: Le proporzioni sono calcolate dividendo la larghezza del ritaglio di destinazione per l'altezza. I valori supportati sono compresi tra 0,75 e 1,8 (inclusi). L'impostazione di questa proprietà è rilevante solo quando VisualFeatures.SmartCrops è stato selezionato come parte dell'elenco delle funzionalità visive. Se si seleziona VisualFeatures.SmartCrops ma non si specificano proporzioni, il servizio restituisce un suggerimento di ritaglio con le proporzioni ritenute più idonee. In questo caso, le proporzioni sono comprese tra 0,5 e 2,0 (inclusi).
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Chiamare l'API Analizza

Questa sezione illustra come effettuare una chiamata di analisi al servizio.

Chiamare il metodo Analyze sull'oggetto ImageAnalysisClient, come illustrato di seguito. La chiamata è sincrona e blocca l'esecuzione fino a quando il servizio non restituisce i risultati o si è verificato un errore. In alternativa, è possibile chiamare il metodo AnalyzeAsync non in modalità di blocco.

Usare gli oggetti di input creati nelle sezioni precedenti. Per analizzare da un buffer di immagini anziché da URL, sostituire imageURL nella chiamata al metodo con la variabile imageData.

ImageAnalysisResult result = client.Analyze(
    imageURL,
    visualFeatures,
    options);

Ottenere risultati dal servizio

Il codice seguente illustra come analizzare i risultati delle varie operazioni di analisi.

Console.WriteLine("Image analysis results:");

// Print caption results to the console
Console.WriteLine(" Caption:");
Console.WriteLine($"   '{result.Caption.Text}', Confidence {result.Caption.Confidence:F4}");

// Print dense caption results to the console
Console.WriteLine(" Dense Captions:");
foreach (DenseCaption denseCaption in result.DenseCaptions.Values)
{
    Console.WriteLine($"   '{denseCaption.Text}', Confidence {denseCaption.Confidence:F4}, Bounding box {denseCaption.BoundingBox}");
}

// Print object detection results to the console
Console.WriteLine(" Objects:");
foreach (DetectedObject detectedObject in result.Objects.Values)
{
    Console.WriteLine($"   '{detectedObject.Tags.First().Name}', Bounding box {detectedObject.BoundingBox.ToString()}");
}

// Print text (OCR) analysis results to the console
Console.WriteLine(" Read:");
foreach (DetectedTextBlock block in result.Read.Blocks)
    foreach (DetectedTextLine line in block.Lines)
    {
        Console.WriteLine($"   Line: '{line.Text}', Bounding Polygon: [{string.Join(" ", line.BoundingPolygon)}]");
        foreach (DetectedTextWord word in line.Words)
        {
            Console.WriteLine($"     Word: '{word.Text}', Confidence {word.Confidence.ToString("#.####")}, Bounding Polygon: [{string.Join(" ", word.BoundingPolygon)}]");
        }
    }

// Print tags results to the console
Console.WriteLine(" Tags:");
foreach (DetectedTag tag in result.Tags.Values)
{
    Console.WriteLine($"   '{tag.Name}', Confidence {tag.Confidence:F4}");
}

// Print people detection results to the console
Console.WriteLine(" People:");
foreach (DetectedPerson person in result.People.Values)
{
    Console.WriteLine($"   Person: Bounding box {person.BoundingBox.ToString()}, Confidence {person.Confidence:F4}");
}

// Print smart-crops analysis results to the console
Console.WriteLine(" SmartCrops:");
foreach (CropRegion cropRegion in result.SmartCrops.Values)
{
    Console.WriteLine($"   Aspect ratio: {cropRegion.AspectRatio}, Bounding box: {cropRegion.BoundingBox}");
}

// Print metadata
Console.WriteLine(" Metadata:");
Console.WriteLine($"   Model: {result.ModelVersion}");
Console.WriteLine($"   Image width: {result.Metadata.Width}");
Console.WriteLine($"   Image hight: {result.Metadata.Height}");

Risoluzione dei problemi

Gestione delle eccezioni

Quando si interagisce con l'analisi delle immagini con .NET SDK, qualsiasi risposta del servizio che non ha un codice di stato 200 (esito positivo) genera un'eccezione. Ad esempio, se si tenta di analizzare un'immagine non accessibile a causa di un URL interrotto, viene restituito uno stato 400, che indica una richiesta non valida e viene generata un'eccezione corrispondente.

Nel frammento di codice seguente, gli errori vengono gestiti normalmente rilevando l'eccezione e visualizzando informazioni aggiuntive sull'errore.

var imageUrl = new Uri("https://some-host-name.com/non-existing-image.jpg");

try
{
    var result = client.Analyze(imageUrl, VisualFeatures.Caption);
}
catch (RequestFailedException e)
{
    if (e.Status != 200)
    {
        Console.WriteLine("Error analyzing image.");
        Console.WriteLine($"HTTP status code {e.Status}: {e.Message}");
    }
    else
    {
        throw;
    }
}

Per altre informazioni su come abilitare la registrazione dell'SDK, vedere qui.

Prerequisiti

Questa guida presuppone che siano stati eseguiti i passaggi della guida introduttiva. Ciò significa:

  • È stata creata una risorsa Visione artificiale , ottenendo una chiave e l'URL dell'endpoint.
  • Il pacchetto SDK appropriato è stato installato e si dispone di un'applicazione di avvio rapido funzionante. È possibile modificare questa applicazione di avvio rapido in base a esempi di codice riportati qui.

Creare ed autenticare il client

Per eseguire l'autenticazione con il servizio Analisi immagini, è necessario disporre di una chiave Visione artificiale e di un URL dell'endpoint. Questa guida presuppone che siano state definite le variabili di ambiente VISION_KEY e VISION_ENDPOINT con la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

Per iniziare, creare un oggetto ImageAnalysisClient usando uno dei costruttori. Ad esempio:

client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key)
)

Selezionare l'immagine che si desidera analizzare

È possibile selezionare un'immagine fornendo un URL di immagine accessibile pubblicamente o leggendo i dati dell'immagine nel buffer di input dell'SDK. Vedere Requisiti delle immagini per i formati di immagine supportati.

Image URL

È possibile usare l'URL dell'immagine di esempio seguente.

# Define image URL
image_url = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"

Buffer delle immagini

In alternativa, è possibile passare l'immagine come oggetto byte. Ad esempio, leggere da un file di immagine locale che si vuole analizzare.

# Load image to analyze into a 'bytes' object
with open("sample.jpg", "rb") as f:
    image_data = f.read()

Selezionare le funzionalità visive

L'API Analisi delle immagini 4.0 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à, fare riferimento alla panoramica. L'esempio in questa sezione aggiunge tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario un numero inferiore di funzionalità.

Importante

Le funzionalità visive Sottotitoli e Sottotitoli densi sono supportate solo in determinate aree di Azure. Vedere Disponibilità a livello di area.

visual_features =[
        VisualFeatures.TAGS,
        VisualFeatures.OBJECTS,
        VisualFeatures.CAPTION,
        VisualFeatures.DENSE_CAPTIONS,
        VisualFeatures.READ,
        VisualFeatures.SMART_CROPS,
        VisualFeatures.PEOPLE,
    ]

Chiamare il metodo analyze_from_url con le opzioni

Il codice seguente chiama il metodo analyze_from_url sul client con le funzionalità selezionate in precedenza e altre opzioni, definite di seguito. Per analizzare da un buffer di immagini anziché da URL, chiamare invece il metodo analyze, con image_data=image_data come primo argomento.

# Analyze all visual features from an image stream. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url=image_url,
    visual_features=visual_features,
    smart_crops_aspect_ratios=[0.9, 1.33],
    gender_neutral_caption=True,
    language="en"
)

Selezionare proporzioni di ritaglio intelligente

Le proporzioni sono calcolate dividendo la larghezza del ritaglio di destinazione per l'altezza. I valori supportati sono compresi tra 0,75 e 1,8 (inclusi). L'impostazione di questa proprietà è rilevante solo quando VisualFeatures.SMART_CROPS è stato selezionato come parte dell'elenco delle funzionalità visive. Se si seleziona VisualFeatures.SMART_CROPS ma non si specificano proporzioni, il servizio restituisce un suggerimento di ritaglio con le proporzioni ritenute più idonee. In questo caso, le proporzioni sono comprese tra 0,5 e 2,0 (inclusi).

Selezionare didascalie neutre

Se si estraggono sottotitoli o sottotitoli densi (usando VisualFeatures.CAPTION o VisualFeatures.DENSE_CAPTIONS), è possibile richiedere sottotitoli indipendenti dal genere. I sottotitoli neutri sono facoltativi; l'impostazione predefinita prevede sottotitoli con distinzione di genere. Ad esempio, in inglese, quando si selezionano le didascalie neutre, termini come woman (donna) o man (uomo) vengono sostituiti con person (persona), mentre boy (ragazzo) o girl (ragazza) vengono sostituiti con child.

Specificare le lingue

È possibile specificare la lingua dei dati restituiti. La lingua è facoltativa e per impostazione predefinita è impostata sull'inglese. Per un elenco dei codici delle lingue supportate e delle funzionalità visive supportate per ogni lingua, vedere Supporto delle lingue.

Ottenere risultati dal servizio

Il codice seguente illustra come analizzare i risultati delle operazioni di analyze_from_url o analyze.

# Print all analysis results to the console
print("Image analysis results:")

if result.caption is not None:
    print(" Caption:")
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

if result.dense_captions is not None:
    print(" Dense Captions:")
    for caption in result.dense_captions.list:
        print(f"   '{caption.text}', {caption.bounding_box}, Confidence: {caption.confidence:.4f}")

if result.read is not None:
    print(" Read:")
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

if result.tags is not None:
    print(" Tags:")
    for tag in result.tags.list:
        print(f"   '{tag.name}', Confidence {tag.confidence:.4f}")

if result.objects is not None:
    print(" Objects:")
    for object in result.objects.list:
        print(f"   '{object.tags[0].name}', {object.bounding_box}, Confidence: {object.tags[0].confidence:.4f}")

if result.people is not None:
    print(" People:")
    for person in result.people.list:
        print(f"   {person.bounding_box}, Confidence {person.confidence:.4f}")

if result.smart_crops is not None:
    print(" Smart Cropping:")
    for smart_crop in result.smart_crops.list:
        print(f"   Aspect ratio {smart_crop.aspect_ratio}: Smart crop {smart_crop.bounding_box}")

print(f" Image height: {result.metadata.height}")
print(f" Image width: {result.metadata.width}")
print(f" Model version: {result.model_version}")

Risoluzione dei problemi

Eccezioni

I metodi analyze generano un'eccezione HttpResponseError per una risposta di codice di stato HTTP non riuscita dal servizio. Il status_code dell'eccezione è il codice di stato della risposta HTTP. Il error.message dell'eccezione contiene un messaggio dettagliato che consente di diagnosticare il problema:

try:
    result = client.analyze( ... )
except HttpResponseError as e:
    print(f"Status code: {e.status_code}")
    print(f"Reason: {e.reason}")
    print(f"Message: {e.error.message}")

Ad esempio, quando si specifica una chiave di autenticazione errata:

Status code: 401
Reason: PermissionDenied
Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.

In alternativa, quando si specifica un URL di immagine che non esiste o non è accessibile:

Status code: 400
Reason: Bad Request
Message: The provided image url is not accessible.

Registrazione

Il client usa la libreria di registrazione Python standard. L'SDK registra i dettagli della richiesta e della risposta HTTP, che possono essere utili per la risoluzione dei problemi. Per accedere a stdout, aggiungere quanto segue:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.vision.imageanalysis' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.INFO)

# Direct logging output to stdout (the default):
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename = 'sample.log')
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

Per impostazione predefinita, i log modificano i valori delle stringhe di query URL, i valori di alcune intestazioni di richiesta e risposta HTTP (inclusi Ocp-Apim-Subscription-Key, che contiene la chiave) e i payload di richiesta e risposta. Per creare log senza rollforward, impostare l'argomento del metodo logging_enable = True quando si crea ImageAnalysisClient o quando si chiama analyze sul client.

# Create an Image Analysis client with none redacted log
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
    logging_enable=True
)

I log non elaborati vengono generati solo a livello di log logging.DEBUG. Assicurarsi di proteggere i log non elaborati per evitare di compromettere la sicurezza. Per altre informazioni, vedere Configurare la registrazione nelle librerie di Azure per Python

Prerequisiti

Questa guida presuppone che siano stati seguiti i passaggi nella pagina della guida introduttiva. Ciò significa:

  • È stata creata una risorsa Visione artificiale ottenendo una chiave e l'URL dell'endpoint.
  • Il pacchetto SDK appropriato è installato ed è disponibile un'applicazione di avvio rapido in esecuzione. È possibile modificare questa applicazione di avvio rapido in base a esempi di codice riportati qui.

Creare ed autenticare il client

Per eseguire l'autenticazione con il servizio Analisi immagini, è necessario disporre di una chiave Visione artificiale e di un URL dell'endpoint. Questa guida presuppone che siano state definite le variabili di ambiente VISION_KEY e VISION_ENDPOINT con la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

Per iniziare, creare un oggetto ImageAnalysisClient. Ad esempio:

String endpoint = System.getenv("VISION_ENDPOINT");
String key = System.getenv("VISION_KEY");

if (endpoint == null || key == null) {
    System.out.println("Missing environment variable 'VISION_ENDPOINT' or 'VISION_KEY'.");
    System.out.println("Set them before running this sample.");
    System.exit(1);
}

// Create a synchronous Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .buildClient();

Selezionare l'immagine che si desidera analizzare

È possibile selezionare un'immagine fornendo un URL di immagine accessibile pubblicamente o leggendo i dati dell'immagine nel buffer di input dell'SDK. Vedere Requisiti delle immagini per i formati di immagine supportati.

Image URL

Creare una stringa imageUrl per contenere l'URL accessibile pubblicamente dell'immagine da analizzare.

String imageUrl = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png";

Buffer delle immagini

In alternativa, è possibile passare l'immagine come buffer di memoria usando un oggetto BinaryData. Ad esempio, leggere da un file di immagine locale che si vuole analizzare.

BinaryData imageData = BinaryData.fromFile(new File("sample.png").toPath());

Selezionare le funzionalità visive

L'API Analisi delle immagini 4.0 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à, fare riferimento alla panoramica. L'esempio in questa sezione aggiunge tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario un numero inferiore di funzionalità.

Importante

Le funzionalità visive Sottotitoli e Sottotitoli densi sono supportate solo in determinate aree di Azure. Vedere Disponibilità a livello di area.

// visualFeatures: Select one or more visual features to analyze.
List<VisualFeatures> visualFeatures = Arrays.asList(
            VisualFeatures.SMART_CROPS,
            VisualFeatures.CAPTION,
            VisualFeatures.DENSE_CAPTIONS,
            VisualFeatures.OBJECTS,
            VisualFeatures.PEOPLE,
            VisualFeatures.READ,
            VisualFeatures.TAGS);

Selezionare le opzioni di analisi

Usare un oggetto ImageAnalysisOptions per specificare varie opzioni per la chiamata API Analyze.

  • Lingua: È possibile specificare la lingua dei dati restituiti. La lingua è facoltativa e per impostazione predefinita è impostata sull'inglese. Per un elenco dei codici delle lingue supportate e delle funzionalità visive supportate per ogni lingua, vedere Supporto delle lingue.
  • Sottotitoli di genere neutro: se si estraggono sottotitoli o sottotitoli densi (usando VisualFeatures.CAPTION o VisualFeatures.DENSE_CAPTIONS), è possibile richiedere sottotitoli di genere neutro. I sottotitoli neutri sono facoltativi; l'impostazione predefinita prevede sottotitoli con distinzione di genere. Ad esempio, in inglese, quando si selezionano le didascalie neutre, termini come woman (donna) o man (uomo) vengono sostituiti con person (persona), mentre boy (ragazzo) o girl (ragazza) vengono sostituiti con child.
  • Proporzioni del ritaglio: Le proporzioni sono calcolate dividendo la larghezza del ritaglio di destinazione per l'altezza. I valori supportati sono compresi tra 0,75 e 1,8 (inclusi). L'impostazione di questa proprietà è rilevante solo quando VisualFeatures.SMART_CROPS è stato selezionato come parte dell'elenco delle funzionalità visive. Se si seleziona VisualFeatures.SMART_CROPS ma non si specificano proporzioni, il servizio restituisce un suggerimento di ritaglio con le proporzioni ritenute più idonee. In questo caso, le proporzioni sono comprese tra 0,5 e 2,0 (inclusi).
// Specify analysis options (or set `options` to null for defaults)
ImageAnalysisOptions options = new ImageAnalysisOptions()
    .setLanguage("en")
    .setGenderNeutralCaption(true)
    .setSmartCropsAspectRatios(Arrays.asList(0.9, 1.33, 1.78));

Chiamare il metodo analyzeFromUrl

Questa sezione illustra come effettuare una chiamata di analisi al servizio.

Chiamare il metodo analyzeFromUrl nell'oggetto ImageAnalysisClient, come illustrato di seguito. La chiamata è sincrona e bloccherà fino a quando il servizio non restituisce i risultati o si è verificato un errore. In alternativa, è possibile usare un oggetto ImageAnalysisAsyncClient e chiamarne il metodo analyzeFromUrl, che non blocca.

Per analizzare da un buffer di immagini anziché da URL, chiamare invece il metodo analyze e passare imageData come primo argomento.

try {
    // Analyze all visual features from an image URL. This is a synchronous (blocking) call.
    ImageAnalysisResult result = client.analyzeFromUrl(
        imageUrl,
        visualFeatures,
        options);

    printAnalysisResults(result);

} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

Ottenere risultati dal servizio

Il codice seguente illustra come analizzare i risultati delle operazioni analyzeFromUrl e analyze.

// Print all analysis results to the console
public static void printAnalysisResults(ImageAnalysisResult result) {

    System.out.println("Image analysis results:");

    if (result.getCaption() != null) {
        System.out.println(" Caption:");
        System.out.println("   \"" + result.getCaption().getText() + "\", Confidence "
            + String.format("%.4f", result.getCaption().getConfidence()));
    }

    if (result.getDenseCaptions() != null) {
        System.out.println(" Dense Captions:");
        for (DenseCaption denseCaption : result.getDenseCaptions().getValues()) {
            System.out.println("   \"" + denseCaption.getText() + "\", Bounding box "
                + denseCaption.getBoundingBox() + ", Confidence " + String.format("%.4f", denseCaption.getConfidence()));
        }
    }

    if (result.getRead() != null) {
        System.out.println(" Read:");
        for (DetectedTextLine line : result.getRead().getBlocks().get(0).getLines()) {
            System.out.println("   Line: '" + line.getText()
                + "', Bounding polygon " + line.getBoundingPolygon());
            for (DetectedTextWord word : line.getWords()) {
                System.out.println("     Word: '" + word.getText()
                    + "', Bounding polygon " + word.getBoundingPolygon()
                    + ", Confidence " + String.format("%.4f", word.getConfidence()));
            }
        }
    }

    if (result.getTags() != null) {
        System.out.println(" Tags:");
        for (DetectedTag tag : result.getTags().getValues()) {
            System.out.println("   \"" + tag.getName() + "\", Confidence " + String.format("%.4f", tag.getConfidence()));
        }
    }

    if (result.getObjects() != null) {
        System.out.println(" Objects:");
        for (DetectedObject detectedObject : result.getObjects().getValues()) {
            System.out.println("   \"" + detectedObject.getTags().get(0).getName() + "\", Bounding box "
                + detectedObject.getBoundingBox() + ", Confidence " + String.format("%.4f", detectedObject.getTags().get(0).getConfidence()));
        }
    }

    if (result.getPeople() != null) {
        System.out.println(" People:");
        for (DetectedPerson person : result.getPeople().getValues()) {
            System.out.println("   Bounding box "
                + person.getBoundingBox() + ", Confidence " + String.format("%.4f", person.getConfidence()));
        }
    }

    if (result.getSmartCrops() != null) {
        System.out.println(" Crop Suggestions:");
        for (CropRegion cropRegion : result.getSmartCrops().getValues()) {
            System.out.println("   Aspect ratio "
                + cropRegion.getAspectRatio() + ": Bounding box " + cropRegion.getBoundingBox());
        }
    }

    System.out.println(" Image height = " + result.getMetadata().getHeight());
    System.out.println(" Image width = " + result.getMetadata().getWidth());
    System.out.println(" Model version = " + result.getModelVersion());
}

Risoluzione dei problemi

Eccezioni

I metodi analyze generano HttpResponseException quando il servizio risponde con un codice di stato HTTP non riuscito. Il getResponse().getStatusCode() dell'eccezione contiene il codice di stato della risposta HTTP. Il getMessage() dell'eccezione contiene un messaggio dettagliato che consente di diagnosticare il problema:

try {
    ImageAnalysisResult result = client.analyze(...)
} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

Ad esempio, quando si specifica una chiave di autenticazione errata:

Exception: ClientAuthenticationException
Status code: 401
Message: Status code 401, "{"error":{"code":"401","message":"Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource."}}"

In alternativa, quando si specifica un'immagine in un formato non riconosciuto:

Exception: HttpResponseException
Status code: 400
Message: Status code 400, "{"error":{"code":"InvalidRequest","message":"Image format is not valid.","innererror":{"code":"InvalidImageFormat","message":"Input data is not a valid image."}}}"

Abilitare la registrazione di richieste/risposte HTTP

La revisione della richiesta HTTP inviata o della risposta ricevuta tramite rete al servizio Analisi immagini può essere utile per la risoluzione dei problemi. La libreria client di Analisi immagini supporta un framework di registrazione della console predefinito a scopo di debug temporaneo. Supporta anche la registrazione più avanzata usando l'interfaccia SLF4J. Per informazioni dettagliate, vedere Usare la registrazione in Azure SDK per Java.

Le sezioni seguenti illustrano me abilitare la registrazione della console usando il framework predefinito.

Impostando variabili di ambiente

È possibile abilitare la registrazione della console di richiesta e risposta HTTP per l'intera applicazione impostando le due variabili di ambiente seguenti. Questa modifica influisce su ogni client di Azure che supporta la registrazione di richieste e risposte HTTP.

  • Impostare la variabile di ambiente AZURE_LOG_LEVEL su debug
  • Impostare la variabile di ambiente AZURE_HTTP_LOG_DETAIL_LEVEL su uno dei valori seguenti:
Valore Livello di registrazione
none La registrazione delle richieste/risposte HTTP è disabilitata
basic Registra solo GLI URL, i metodi HTTP e il tempo necessario per completare la richiesta.
headers Registra tutti gli elementi in BASIC, oltre a tutte le intestazioni di richiesta e risposta.
body Registra tutti gli elementi in BASIC, oltre a tutto il corpo della richiesta e della risposta.
body_and_headers Registra tutti gli elementi in HEADERS e BODY.

Impostando httpLogOptions

Per abilitare la registrazione della console di richiesta e risposta HTTP per un singolo client

  • Impostare la variabile di ambiente AZURE_LOG_LEVEL su debug
  • Aggiungere una chiamata a httpLogOptions durante la compilazione di ImageAnalysisClient:
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

L'enumerazione HttpLogDetailLevel definisce i livelli di registrazione supportati.

Per impostazione predefinita, durante la registrazione, vengono elaborati determinati valori di intestazione HTTP e parametri di query. È possibile eseguire l'override di questa impostazione predefinita specificando quali intestazioni e parametri di query sono sicuri per registrare:

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("safe-to-log-header-name")
        .addAllowedQueryParamName("safe-to-log-query-parameter-name"))
    .buildClient();

Ad esempio, per ottenere un log completo non redatto della richiesta HTTP, applicare quanto segue:

    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("Ocp-Apim-Subscription-Key")
        .addAllowedQueryParamName("features")
        .addAllowedQueryParamName("language")
        .addAllowedQueryParamName("gender-neutral-caption")
        .addAllowedQueryParamName("smartcrops-aspect-ratios")
        .addAllowedQueryParamName("model-version"))

Aggiungere altro a quanto sopra per ottenere una risposta HTTP non redacted. Quando si condivide un log non modificato, assicurarsi che non contenga segreti come la chiave di sottoscrizione.

Prerequisiti

Questa guida presuppone che siano stati eseguiti correttamente i passaggi indicati nella pagina della guida introduttiva. Ciò significa:

  • È stata creata una risorsa Visione artificiale ottenendo una chiave e l'URL dell'endpoint.
  • Il pacchetto SDK appropriato è installato ed è disponibile un'applicazione di avvio rapido in esecuzione. È possibile modificare questa applicazione di avvio rapido in base a esempi di codice riportati qui.

Creare ed autenticare il client

Per eseguire l'autenticazione con il servizio Analisi immagini, è necessario disporre di una chiave Visione artificiale e di un URL dell'endpoint. Questa guida presuppone che siano state definite le variabili di ambiente VISION_KEY e VISION_ENDPOINT con la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

Per iniziare, creare un oggetto ImageAnalysisClient. Ad esempio:

// Load the .env file if it exists
require("dotenv").config();

const endpoint = process.env['VISION_ENDPOINT'] || '<your_endpoint>';
const key = process.env['VISION_KEY'] || '<your_key>';

const credential = new AzureKeyCredential(key);
const client = createClient(endpoint, credential);

Selezionare l'immagine che si desidera analizzare

È possibile selezionare un'immagine fornendo un URL di immagine accessibile pubblicamente o leggendo i dati dell'immagine nel buffer di input dell'SDK. Vedere Requisiti delle immagini per i formati di immagine supportati.

Image URL

È possibile usare l'URL dell'immagine di esempio seguente.

const imageUrl = 'https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png';

Buffer delle immagini

In alternativa, è possibile passare l'immagine come matrice di dati. Ad esempio, leggere da un file di immagine locale che si vuole analizzare.

const imagePath = '../sample.jpg';
const imageData = fs.readFileSync(imagePath);

Selezionare le funzionalità visive

L'API Analisi delle immagini 4.0 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à, fare riferimento alla panoramica. L'esempio in questa sezione aggiunge tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario un numero inferiore di funzionalità.

Importante

Le funzionalità visive Sottotitoli e Sottotitoli densi sono supportate solo in determinate aree di Azure. Vedere .

const features = [
  'Caption',
  'DenseCaptions',
  'Objects',
  'People',
  'Read',
  'SmartCrops',
  'Tags'
];

Chiamare l'API Analizza con le opzioni

Il codice seguente chiama l'API Analizza immagine con le funzionalità selezionate in precedenza e altre opzioni, definite successivamente. Per analizzare da un buffer di immagini anziché da URL, sostituire imageURL nella chiamata al metodo con imageData.

const result = await client.path('/imageanalysis:analyze').post({
  body: {
      url: imageUrl
  },
  queryParameters: {
      features: features,
      'language': 'en',
      'gender-neutral-captions': 'true',
      'smartCrops-aspect-ratios': [0.9, 1.33]
  },
  contentType: 'application/json'
});

Selezionare proporzioni di ritaglio intelligente

Le proporzioni sono calcolate dividendo la larghezza del ritaglio di destinazione per l'altezza. I valori supportati sono compresi tra 0,75 e 1,8 (inclusi). L'impostazione di questa proprietà è rilevante solo quando VisualFeatures.SmartCrops è stato selezionato come parte dell'elenco delle funzionalità visive. Se si seleziona VisualFeatures.SmartCrops ma non si specificano proporzioni, il servizio restituisce un suggerimento di ritaglio con le proporzioni ritenute più idonee. In questo caso, le proporzioni sono comprese tra 0,5 e 2,0 (inclusi).

Selezionare didascalie neutre

Se si estraggono sottotitoli o sottotitoli densi (usando VisualFeatures.Caption o VisualFeatures.DenseCaptions), è possibile richiedere sottotitoli di genere neutro. I sottotitoli neutri sono facoltativi; l'impostazione predefinita prevede sottotitoli con distinzione di genere. Ad esempio, in inglese, quando si selezionano le didascalie neutre, termini come woman (donna) o man (uomo) vengono sostituiti con person (persona), mentre boy (ragazzo) o girl (ragazza) vengono sostituiti con child.

Specificare le lingue

È possibile specificare la lingua dei dati restituiti. La lingua è facoltativa e per impostazione predefinita è impostata sull'inglese. Per un elenco dei codici delle lingue supportate e delle funzionalità visive supportate per ogni lingua, vedere Supporto delle lingue.

Ottenere risultati dal servizio

Il codice seguente illustra come analizzare i risultati delle varie operazioni di analisi.

const iaResult = result.body;

console.log(`Model Version: ${iaResult.modelVersion}`);
console.log(`Image Metadata: ${JSON.stringify(iaResult.metadata)}`);
if (iaResult.captionResult) {
  console.log(`Caption: ${iaResult.captionResult.text} (confidence: ${iaResult.captionResult.confidence})`);
}
if (iaResult.denseCaptionsResult) {
  iaResult.denseCaptionsResult.values.forEach(denseCaption => console.log(`Dense Caption: ${JSON.stringify(denseCaption)}`));
}
if (iaResult.objectsResult) {
  iaResult.objectsResult.values.forEach(object => console.log(`Object: ${JSON.stringify(object)}`));
}
if (iaResult.peopleResult) {
  iaResult.peopleResult.values.forEach(person => console.log(`Person: ${JSON.stringify(person)}`));
}
if (iaResult.readResult) {
  iaResult.readResult.blocks.forEach(block => console.log(`Text Block: ${JSON.stringify(block)}`));
}
if (iaResult.smartCropsResult) {
  iaResult.smartCropsResult.values.forEach(smartCrop => console.log(`Smart Crop: ${JSON.stringify(smartCrop)}`));
}
if (iaResult.tagsResult) {
  iaResult.tagsResult.values.forEach(tag => console.log(`Tag: ${JSON.stringify(tag)}`));
}

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione sul pacchetto @azure/logger.

Prerequisiti

Questa guida presuppone che siano stati eseguiti correttamente i passaggi indicati nella pagina di avvio rapido. Ciò significa:

  • È stata creata una risorsa Visione artificiale ottenendo una chiave e l'URL dell'endpoint.
  • È stata effettuata una chiamata curl.exe al servizio (o è stato usato uno strumento alternativo). Modificare la chiamata curl.exe in base agli esempi riportati qui.

Autenticazione per il servizio

Per eseguire l'autenticazione con il servizio Analisi immagini, è necessario disporre di una chiave Visione artificiale e di un URL dell'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

L'SDK di esempio presuppone che siano state definite le variabili di ambiente VISION_KEY e VISION_ENDPOINT con la chiave e l'endpoint.

L'autenticazione viene eseguita aggiungendo l'intestazione della richiesta HTTP Ocp-Apim-Subscription-Key e impostandola sulla chiave di Visione. La chiamata viene effettuata all'URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, dove <endpoint> è l'URL univoco dell'endpoint di Visione artificiale. È possibile aggiungere stringhe di query in base alle opzioni di analisi.

Selezionare l'immagine da analizzare

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

Image URL

Quando si analizza un'immagine remota, si specifica l'URL dell'immagine formattando il corpo della richiesta, nel modo seguente: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Content-Type deve essere application/json.

Image file

Per analizzare un'immagine locale, inserire i dati dell'immagine binaria nel corpo della richiesta HTTP. Il parametro Content-Type deve essere application/octet-stream o multipart/form-data.

Selezionare le opzioni di analisi

Selezionare le funzionalità visive quando si usa il modello standard

L'API Analisi delle immagini 4.0 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à, fare riferimento alla panoramica. L'esempio in questa sezione aggiunge tutte le funzionalità visive disponibili, ma per un utilizzo pratico è probabile che sia necessario un numero inferiore di funzionalità.

Le funzionalità visive "Sottotitoli" e "Sottotitoli densi" sono supportate solo in determinate aree di Azure: vedere Disponibilità dell'area.

Nota

Nell'API REST vengono usati i termini ritagli intelligenti e proporzioni dei ritagli intelligenti. Nell'SDK vengono usati i termini suggerimenti di ritaglio e proporzioni di ritaglio. Entrambi fanno riferimento alla stessa operazione del servizio. Analogamente, l'API REST usa il termine Read per rilevare il testo nell'immagine usando il riconoscimento ottico dei caratteri (OCR), mentre l'SDK usa il termine Text per la stessa operazione.

È possibile specificare le funzionalità da usare impostando i parametri di query URL dell'API di analisi 4.0. Un parametro può avere più valori, separati da virgole.

Parametro URL Valore Descrizione
features read Legge il testo visibile nell'immagine e lo restituisce come dati JSON strutturati.
features caption Descrive il contenuto dell'immagine con una frase completa nelle lingue supportate.
features denseCaptions Genera didascalie dettagliate per un massimo di 10 aree di immagine evidenti.
features smartCrops Trova le coordinate del rettangolo che ritaglierebbero l'immagine nelle proporzioni desiderate conservando 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 delle parole correlate con il contenuto dell'immagine.
features people Rileva le persone visualizzate nelle immagini, incluse le posizioni approssimative.

Un URL popolato potrebbe essere simile al seguente:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=tags,read,caption,denseCaptions,smartCrops,objects,people

Impostare il nome del modello quando si usa un modello personalizzato

È anche possibile eseguire l'analisi delle immagini con un modello personalizzato con training. Per creare ed eseguire il training di un modello, vedere Creare un modello personalizzato di analisi delle immagini. Dopo aver eseguito il training del modello, è sufficiente specificare il nome del modello. Non è necessario specificare le funzionalità visive se si usa un modello personalizzato.

Per usare un modello personalizzato, non usare il parametro di query della proprietà features. Impostare invece il parametro model-name sul nome del modello, come illustrato di seguito. Sostituire MyCustomModelName con il nome del modello personalizzato.

<endpoint>/computervision/imageanalysis:analyze?api-version=2023-02-01&model-name=MyCustomModelName

Specificare le lingue

È possibile specificare la lingua dei dati restituiti. La lingua è facoltativa e per impostazione predefinita è impostata sull'inglese. Per un elenco dei codici delle lingue supportate e delle funzionalità visive supportate per ogni lingua, vedere Supporto delle lingue.

L'opzione Language si applica solo quando si usa il modello standard.

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>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&language=en

Selezionare didascalie neutre

Se si estraggono didascalie o didascalie dense, è possibile richiedere didascalie neutre. I sottotitoli neutri sono facoltativi; l'impostazione predefinita prevede sottotitoli con distinzione di genere. Ad esempio, in inglese, quando si selezionano le didascalie neutre, termini come woman (donna) o man (uomo) vengono sostituiti con person (persona), mentre boy (ragazzo) o girl (ragazza) vengono sostituiti con child.

L'opzione relativa alla didascalia neutra (indipendente dal genere) si applica solo quando si usa il modello standard.

Aggiungere la stringa di query facoltativa gender-neutral-caption con valori true o false (impostazione predefinita).

Un URL popolato potrebbe essere simile al seguente:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&gender-neutral-caption=true

Selezionare proporzioni di ritaglio intelligente

Le proporzioni sono calcolate dividendo la larghezza del ritaglio di destinazione per l'altezza. I valori supportati sono compresi tra 0,75 e 1,8 (inclusi). L'impostazione di questa proprietà è rilevante solo quando VisualFeatures.SmartCrops è stato selezionato come parte dell'elenco delle funzionalità visive. Se si seleziona VisualFeatures.SmartCrops ma non si specificano proporzioni, il servizio restituisce un suggerimento di ritaglio con le proporzioni ritenute più idonee. In questo caso, le proporzioni sono comprese tra 0,5 e 2,0 (inclusi).

Le proporzioni di ritaglio intelligente si applicano solo quando si usa il modello standard.

Aggiungere la stringa di query facoltativa smartcrops-aspect-ratios, con una o più proporzioni separate da una virgola.

Un URL popolato potrebbe essere simile al seguente:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=smartCrops&smartcrops-aspect-ratios=0.8,1.2

Ottenere i risultati dal servizio

Ottenere risultati usando il modello standard

Questa sezione spiega come effettuare una chiamata di analisi al servizio usando il modello standard e ottenere i risultati.

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.

{
    "modelVersion": "string",
    "captionResult": {
      "text": "string",
      "confidence": 0.0
    },
    "denseCaptionsResult": {
      "values": [
        {
          "text": "string",
          "confidence": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "metadata": {
      "width": 0,
      "height": 0
    },
    "tagsResult": {
      "values": [
        {
          "name": "string",
          "confidence": 0.0
        }
      ]
    },
    "objectsResult": {
      "values": [
        {
          "id": "string",
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "tags": [
            {
              "name": "string",
              "confidence": 0.0
            }
          ]
        }
      ]
    },
    "readResult": {
      "blocks": [
        {
          "lines": [
            {
              "text": "string",
              "boundingPolygon": [
                {
                  "x": 0,
                  "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                }
              ],
              "words": [
                {
                  "text": "string",
                  "boundingPolygon": [
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    }
                  ],
                  "confidence": 0.0
                }
              ]
            }
          ]
        }
      ]
    },
    "smartCropsResult": {
      "values": [
        {
          "aspectRatio": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "peopleResult": {
      "values": [
        {
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "confidence": 0.0
        }
      ]
    }
  }

Codici di errore

In caso di errore, la risposta del servizio Analisi immagini contiene un payload JSON che include un codice di errore e un messaggio di errore. Potrebbe anche includere altri dettagli sotto forma di codice di errore interno e di messaggio. Ad esempio:

{
    "error":
    {
        "code": "InvalidRequest",
        "message": "Analyze query is invalid.",
        "innererror":
        {
            "code": "NotSupportedVisualFeature",
            "message": "Specified feature type is not valid"
        }
    }
}

Di seguito è riportato un elenco degli errori più comuni e delle relative cause. Gli elementi dell’elenco vengono presentati nel formato seguente:

  • Codice di risposta HTTP
    • Codice di errore e messaggio di errore nella risposta JSON
      • [Facoltativo] Codice di errore interno e messaggio di errore nella risposta JSON

Elenco degli errori più comuni:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. Assicurarsi che l'URL dell'immagine sia valido e accessibile pubblicamente.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Ridurre le dimensioni dell'immagine comprimendola e/o ridimensionandola, quindi inviare nuovamente la richiesta.
    • InvalidRequest - The feature 'Caption' is not supported in this region. La funzionalità è supportata solo in aree di Azure specifiche. Per l'elenco delle aree di Azure supportate, vedere Prerequisiti di avvio rapido.
    • InvalidRequest - The provided image content type ... is not supported. L'intestazione HTTP Content-Type nella richiesta non è un tipo consentito:
      • 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
    • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
    • InvalidRequest - Image format is not valid
      • InvalidImageFormat - Image format is not valid. Vedere la sezione Requisiti delle immagini per conoscere i formati immagine supportati.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Assicurarsi che la stringa di query features abbia un valore valido.
      • NotSupportedLanguage - The input language is not supported. Assicurarsi che la stringa di query language abbia un valore valido per la funzionalità visiva selezionata, in base alla tabella seguente.
      • BadArgument - 'smartcrops-aspect-ratios' aspect ratio is not in allowed range [0.75 to 1.8]
  • 401 PermissionDenied
    • 401 - Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.
  • 404 Resource Not Found
    • 404 - Resource not found. Il servizio non è riuscito a trovare il modello personalizzato in base al nome fornito dalla stringa di query model-name.

Passaggi successivi