Image Analysis 4.0 Analyze API を呼び出す

[アーティクル]
09/04/2024

このアーティクルでは、Image Analysis 4.0 API を呼び出して画像の視覚的特徴に関する情報を返す方法について説明します。また、返された情報を解析する方法も示します。

前提条件

このガイドは、クイックスタートページで説明されている手順に従っていることを前提としています。これは、以下を意味します。

このガイドでは、既に Computer Vision リソースを作成し、キーとエンドポイント URL を取得していることを前提としています。
適切な SDK パッケージがインストールされており、実行中のクイックスタートアプリケーションがあります。ここでのコード例に基づいて、このクイックスタートアプリケーションを変更できます。

クライアントを作成して認証する

Image Analysis サービスに対して認証するには、Computer Vision キーとエンドポイント URL が必要です。このガイドは、キーとエンドポイントを使用して環境変数 VISION_KEY と VISION_ENDPOINT を定義していることを前提としています。

重要

API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

まず、ImageAnalysisClient オブジェクトを作成します。次に例を示します。

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));

分析する画像を選択する

一般にアクセス可能な画像 URL を選択するか、SDK にバイナリデータを渡すことで画像を選択できます。サポートされている画像形式については、「画像の要件」セクションを参照してください。

画像 URL

分析する画像の Uri オブジェクトを作成します。

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

イメージバッファー

または、BinaryData オブジェクトを介して画像データを SDK に渡すことができます。たとえば、分析するローカル画像ファイルから読み取るとします。

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

視覚的特徴を選択する

Analysis 4.0 API を使用すると、サービスの画像分析の特徴すべてにアクセスできます。独自のユースケースに基づいて、行う操作を選択します。各機能の説明については、概要のページを参照してください。このセクションの例では、使用可能なビジュアル機能をすべて追加しますが、実際に使用する場合、必要なものはこれより少ない可能性があります。

重要

ビジュアル機能 Captions および DenseCaptions は、特定の Azure リージョンでのみサポートされています。「Azure リージョンの可用性」を参照してください

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

分析オプションを選択する

ImageAnalysisOptions オブジェクトを使用して、Analyze Image API 呼び出しのさまざまなオプションを指定します。

言語: 返されるデータの言語を指定できます。この言語は省略可能で、既定値は英語です。サポートされている言語コードのリストと、各言語でサポートされているビジュアルフィーチャーのリストについては、「言語のサポート」を参照してください。
性別に依存しないキャプション: キャプションまたは密なキャプションを抽出する場合 (VisualFeatures.Caption または VisualFeatures.DenseCaptions を使用)、性別に依存しないキャプションを要求できます。性別に依存しないキャプションは省略可能で、既定では性別の区別があるキャプションになっています。たとえば、英語では、性別に依存しないキャプションを選択すると、woman や man などの用語は person に置き換えられ、boy や girl は child に置き換えられます。
トリミングの縦横比: 縦横比は、ターゲットのトリミング幅を高さで割ることによって計算されます。サポートされる値は 0.75 から 1.8 (値を含む) までです。このプロパティの設定は、VisualFeatures.SmartCrops がビジュアル機能リストの一部として選択されている場合にのみ該当します。 VisualFeatures.SmartCrops を選択したが、縦横比を指定していない場合、サービスは、適切と思われる縦横比のトリミング候補を 1 つ返します。この場合、縦横比は 0.5 から 2.0 (値を含む) までです。

ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Analyze API を呼び出す

このセクションでは、サービスに対して分析の呼び出しを行う方法について説明します。

次に示すように、ImageAnalysisClient オブジェクトで Analyze メソッドを呼び出します。この呼び出しは同期的であり、サービスによって結果が返されるか、またはエラーが発生するまでブロックされます。または、非ブロッキング AnalyzeAsync メソッドを呼び出すこともできます。

上記のセクションで作成した入力オブジェクトを使用します。 URL ではなくイメージバッファーから分析するには、メソッド呼び出しの imageURL を imageData 変数に置換します。

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

サービスから結果を取得する

次のコードは、さまざまな分析操作の結果を解析する方法を示しています。

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}");

トラブルシューティング

例外処理

.NET SDK を使用して Image Analysis を操作すると、200 (成功) 状態コードを持たないサービスからの応答はすべて、例外としてスローされます。たとえば、URL が壊れたためにアクセスできない画像を分析しようとすると、不正な要求を示す 400 状態が返され、対応する例外がスローされます。

次のスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが適切に処理されます。

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;
    }
}

SDK ログ記録を有効にする方法の詳細については、こちらを参照してください。

前提条件

このガイドは、読者がクイックスタートの手順を実行済みであることを前提としています。これは、以下のようなことを意味します。

Computer Vision リソースを作成し、キーとエンドポイントの URL を取得した。
適切な SDK パッケージをインストールし、動作するクイックスタートアプリケーションを用意した。このクイックスタートアプリケーションは、ここで示すコード例に基づいて変更できます。

クライアントを作成して認証する

重要

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

まず、いずれかのコンストラクターを使用して ImageAnalysisClient オブジェクトを作成します。次に例を示します。

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

分析する画像を選択する

画像を選択するには、一般にアクセス可能な画像 URLを指定するか、SDK の入力バッファーに画像を読み取ることで画像を選択できます。サポートされている画像形式については、「画像の要件」セクションを参照してください。

画像 URL

次のサンプル画像 URL を使用できます。

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

イメージバッファー

または、画像を bytes オブジェクトとして渡すこともできます。たとえば、分析するローカル画像ファイルから読み取るとします。

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

視覚的特徴を選択する

重要

ビジュアル機能 Captions および DenseCaptions は、特定の Azure リージョンでのみサポートされています。利用可能なリージョンに関するページを参照してください。

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

オプションを指定して analyze_from_url メソッドを呼び出します

次のコードは、先ほど選択した特徴量と以下で定義される追加のオプションを指定して、クライアント上の analyze_from_url メソッドを呼び出しています。 URL ではなく画像バッファーから分析するには、代わりにメソッド analyze を呼び出します。その際に 1 つ目の引数として image_data=image_data を指定します。

# 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"
)

スマートトリミング縦横比を選択する

縦横比は、ターゲットのトリミング幅を高さで割ることによって計算されます。サポートされる値は 0.75 から 1.8 (値を含む) までです。このプロパティの設定は、VisualFeatures.SMART_CROPS がビジュアル機能リストの一部として選択されている場合にのみ該当します。 VisualFeatures.SMART_CROPS を選択したが、縦横比を指定していない場合、サービスは、適切と思われる縦横比のトリミング候補を 1 つ返します。この場合、縦横比は 0.5 から 2.0 (値を含む) までです。

性別に依存しないキャプションを選択する

キャプションまたは密なキャプションを抽出する場合 (VisualFeatures.CAPTION または VisualFeatures.DENSE_CAPTIONS を使用)、性別に依存しないキャプションを要求できます。性別に依存しないキャプションは省略可能で、既定では性別の区別があるキャプションになっています。たとえば、英語では、性別に依存しないキャプションを選択すると、woman や man などの用語は person に置き換えられ、boy や girl は child に置き換えられます。

言語を指定する

返されるデータの言語を指定できます。この言語は省略可能で、既定値は英語です。サポートされている言語コードのリストと、各言語でサポートされているビジュアルフィーチャーのリストについては、「言語のサポート」を参照してください。

サービスから結果を取得する

次のコードは、analyze_from_url または 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}")

トラブルシューティング

例外

analyze メソッドは、サービスからの成功以外の HTTP 状態コード応答に対して、 HttpResponseError 例外を発生させます。例外の status_code は、HTTP 応答状態コードです。例外の error.message には、問題の診断に役立つ次のような詳細なメッセージが含まれています。

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}")

たとえば、間違った認証キーを指定した場合は、次のようになります。

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.

また、存在しないまたはアクセスできない画像 URL を指定した場合は、以下のようになります。

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

ログ機能

クライアントは、標準の Python ログ記録ライブラリを使用します。 SDK は HTTP 要求と応答の詳細をログに記録します。これはトラブルシューティングに役立つ場合があります。標準出力にログを記録するには、次を追加します。

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)

既定では、ログは URL クエリ文字列の値、(キーを保持する Ocp-Apim-Subscription-Key を含む) 一部の HTTP 要求と応答ヘッダーの値、要求と応答のペイロードをリダクトします。添削せずにログを作成するには、ImageAnalysisClientを作成するとき、またはクライアントでanalyzeを呼び出すときにメソッド引数 logging_enable = True を設定します。

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

ログレベル logging.DEBUG に対してのみ、添削済みのログは一切生成されません。セキュリティを損なわないように、添削済みのログは必ず保護してください。詳細については、「Azure ライブラリまたは Python でログ記録を構成する」を参照してください。

前提条件

このガイドは、クイックスタートページの手順に従っていることを前提としています。これは、以下を意味します。

このガイドでは、既に Computer Vision リソースを作成し、キーとエンドポイント URL を取得していることを前提としています。
適切な SDK パッケージがインストールされており、実行中のクイックスタートアプリケーションがあります。ここでのコード例に基づいて、このクイックスタートアプリケーションを変更できます。

クライアントを作成して認証する

Image Analysis サービスを使用して認証するには、Computer Vision キーとエンドポイント URL が必要です。このガイドは、キーとエンドポイントを使用して環境変数 VISION_KEY と VISION_ENDPOINT を定義していることを前提としています。

重要

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

まず、ImageAnalysisClient オブジェクトを作成します。次に例を示します。

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();

分析する画像を選択する

画像 URL

分析する画像のパブリックにアクセスできる URL を保持するために、imageUrl 文字列を作成します。

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

イメージバッファー

または、BinaryData オブジェクトを使って、画像をメモリバッファーとして渡すことができます。たとえば、分析するローカル画像ファイルから読み取るとします。

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

視覚的特徴を選択する

重要

// 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);

分析オプションを選択する

ImageAnalysisOptions オブジェクトを使用して、Analyze API 呼び出しのさまざまなオプションを指定します。

言語: 返されるデータの言語を指定できます。この言語は省略可能で、既定値は英語です。サポートされている言語コードのリストと、各言語でサポートされているビジュアルフィーチャーのリストについては、「言語のサポート」を参照してください。
性別に依存しないキャプション: キャプションまたは密なキャプションを抽出する場合 (VisualFeatures.CAPTION または VisualFeatures.DENSE_CAPTIONS を使用)、性別に依存しないキャプションを要求できます。性別に依存しないキャプションは省略可能で、既定では性別の区別があるキャプションになっています。たとえば、英語では、性別に依存しないキャプションを選択すると、woman や man などの用語は person に置き換えられ、boy や girl は child に置き換えられます。
トリミングの縦横比: 縦横比は、ターゲットのトリミング幅を高さで割ることによって計算されます。サポートされる値は 0.75 から 1.8 (値を含む) までです。このプロパティの設定は、VisualFeatures.SMART_CROPS がビジュアル機能リストの一部として選択されている場合にのみ該当します。 VisualFeatures.SMART_CROPS を選択したが、縦横比を指定していない場合、サービスは、適切と思われる縦横比のトリミング候補を 1 つ返します。この場合、縦横比は 0.5 から 2.0 (値を含む) までです。

// 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));

analyzeFromUrl メソッドを呼び出す

このセクションでは、サービスに対して分析の呼び出しを行う方法について説明します。

次に示すように、ImageAnalysisClient オブジェクトに対して analyzeFromUrl メソッドを呼び出します。この呼び出しは同期的であり、サービスが結果を返すかエラーが発生するまでブロックされます。または、代わりに ImageAnalysisAsyncClient オブジェクトを使用し、非ブロッキングの analyzeFromUrl メソッドを呼び出すことができます。

URL ではなく画像バッファーから分析するには、代わりに analyze メソッドを呼び出し、1 つ目の引数として imageData を渡します。

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());
}

サービスから結果を取得する

次のコードは、analyzeFromUrl または 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());
}

トラブルシューティング

例外

analyze メソッドは、サービスが成功以外の HTTP 状態コードで応答したときに、httpResponseException をスローします。例外の getResponse().getStatusCode() は、HTTP 応答状態コードを保持します。例外の getMessage() には、問題の診断に役立つ次のような詳細なメッセージが含まれています。

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());
}

たとえば、間違った認証キーを指定した場合は、次のようになります。

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."}}"

または、認識されない形式で画像を指定した場合は、次のようになります。

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."}}}"

HTTP 要求/応答ログを有効にする

ネットワーク経由で送信または受信した Image Analysis サービスへの HTTP 要求を確認することは、トラブルシューティングに役立ちます。 Image Analysis クライアントライブラリは、一時的なデバッグを目的とした組み込みのコンソールログ記録フレームワークをサポートしています。また、 SLF4J インターフェイスを使用した、より高度なログ記録もサポートしています。詳細については、「Azure SDK for Java でログ記録を使用する」を参照してください。

以下のセクションでは、組み込みのフレームワークを使用してコンソールログ記録を有効にする方法について説明します。

環境変数を設定して有効にする

次の 2 つの環境変数を設定することで、アプリケーション全体の HTTP 要求と応答のコンソールログ記録を有効化できます。この変更は、HTTP 要求と応答のログ記録をサポートするすべての Azure クライアントに影響します。

環境変数 AZURE_LOG_LEVEL を debug に設定する
環境変数 AZURE_HTTP_LOG_DETAIL_LEVEL を次のいずれかの値に設定します。

Value	ログ記録レベル
`none`	HTTP 要求/応答のログ記録が無効になっている
`basic`	URL、HTTP メソッド、および要求の完了までの時間のみをログに記録します。
`headers`	BASIC 内のすべてと、すべての要求および応答ヘッダーをログに記録します。
`body`	BASIC 内のすべてと、すべての要求および応答本文をログに記録します。
`body_and_headers`	ヘッダーと本文内のすべてをログに記録します。

httpLogOptions を設定して有効にする

1 つのクライアントに対して HTTP 要求と応答のコンソールログ記録を有効にするには

環境変数 AZURE_LOG_LEVEL を debug に設定する
ImageAnalysisClient をビルドするときに、 httpLogOptionsへの呼び出しを追加します。

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

HttpLogDetailLevel 列挙型は、サポートされているログ記録レベルを定義します。

既定では、ログ記録時に、特定の HTTP ヘッダーとクエリパラメーターの値が添削されます。安全にログできるヘッダーやクエリパラメーターを指定すると、この既定値をオーバーライドできます。

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();

たとえば、添削されていない完全なHTTP 要求のログを取得するには、次を適用します。

    .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"))

上記にさらに追加して、添削されていない HTTP 応答を取得します。添削されていないログを共有するときは、サブスクリプションキーなどのシークレットが含まれていないことを確認します。

前提条件

このガイドは、クイックスタートで説明されている手順に従っていることを前提としています。これは、以下を意味します。

このガイドでは、既に Computer Vision リソースを作成し、キーとエンドポイント URL を取得していることを前提としています。
適切な SDK パッケージがインストールされており、実行中のクイックスタートアプリケーションがあります。このクイックスタートアプリケーションは、ここで示すコード例に基づいて変更できます。

クライアントを作成して認証する

重要

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

まず、ImageAnalysisClient オブジェクトを作成します。次に例を示します。

// 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);

分析する画像を選択する

画像 URL

次のサンプル画像 URL を使用できます。

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

イメージバッファー

または、画像をデータ配列として渡すことができます。たとえば、分析するローカル画像ファイルから読み取るとします。

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

視覚的特徴を選択する

Analysis 4.0 API を使用すると、サービスの画像分析の特徴すべてにアクセスできます。独自のユースケースに基づいて、行う操作を選択します。各機能の説明については、「概要」を参照してください。このセクションの例では、使用可能なビジュアル機能をすべて追加しますが、実際に使用する場合、必要なものはこれより少ない可能性があります。

重要

ビジュアル機能 Captions および DenseCaptions は、特定の Azure リージョンでのみサポートされています。以下を参照してください。

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

オプションを使用して Analyze API を呼び出す

次のコードでは、先ほど選択した機能と、以下に定義されている追加オプションを使用して、Analyze Image API を呼び出します。 URL ではなくイメージバッファーから分析するには、メソッド呼び出しの imageURL を 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'
});

スマートトリミング縦横比を選択する

縦横比は、ターゲットのトリミング幅を高さで割ることによって計算されます。サポートされる値は 0.75 から 1.8 (値を含む) までです。このプロパティの設定は、VisualFeatures.SmartCrops がビジュアル機能リストの一部として選択されている場合にのみ該当します。 VisualFeatures.SmartCrops を選択したが、縦横比を指定していない場合、サービスは、適切と思われる縦横比のトリミング候補を 1 つ返します。この場合、縦横比は 0.5 から 2.0 (値を含む) までです。

性別に依存しないキャプションを選択する

キャプションまたは密なキャプションを抽出する場合 (VisualFeatures.Caption または VisualFeatures.DenseCaptions を使用)、性別に依存しないキャプションを要求できます。性別に依存しないキャプションは省略可能で、既定では性別の区別があるキャプションになっています。たとえば、英語では、性別に依存しないキャプションを選択すると、woman や man などの用語は person に置き換えられ、boy や girl は child に置き換えられます。

言語を指定する

サービスから結果を取得する

次のコードは、さまざまな分析操作の結果を解析する方法を示しています。

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)}`));
}

トラブルシューティング

ログ機能

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

前提条件

このガイドは、クイックスタートページで説明されている手順に正しく従っていることを前提としています。これは、以下を意味します。

このガイドでは、既に Computer Vision リソースを作成し、キーとエンドポイント URL を取得していることを前提としています。
サービスへの curl.exe 呼び出しが正常に行われています (または別のツールが使用されています)。ここでの例に基づいて、curl.exe 呼び出しを変更します。

サービスに対する認証

Image Analysis サービスに対して認証するには、Computer Vision キーとエンドポイント URL が必要です。

重要

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

SDK の例では、キーとエンドポイントを使用して環境変数 VISION_KEY と VISION_ENDPOINT を定義していることを前提としています。

認証は、HTTP 要求ヘッダー Ocp-Apim-Subscription-Key を追加し、それを Vision キーに設定することで行われます。呼び出しは URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01 に対して行われます。ここで、<endpoint> は一意の Computer Vision エンドポイント URL です。分析オプションに基づいてクエリ文字列を追加します。

分析する画像を選択する

このガイドにあるコードでは、URL によって参照されるリモートの画像を使用します。画像解析機能の全機能を確認するには、さまざまな画像を自分で試してみることをお勧めします。

画像 URL

リモートの画像を分析する場合、要求本文を {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"} のような形式にして、画像の URL を指定します。 Content-Typeは application/json である必要があります。

イメージファイル

ローカルの画像を分析するには、バイナリ画像データを HTTP 要求本文に配置します。 Content-Typeは application/octet-stream または multipart/form-data である必要があります。

分析オプションを選択する

標準モデルを使用するときに視覚機能を選択する

ビジュアル機能 'Captions' および 'DenseCaptions' は、特定の Azure リージョンでのみサポートされています。「Azure リージョンの可用性」を参照してください。

Note

REST API では、スマートトリミングとスマートトリミング縦横比という用語が使用されます。 SDK では、トリミング候補とトリミング縦横比という用語が使用されます。これらはどちらも同じサービス操作を指します。同様に、REST API では、光学式文字認識 (OCR) を使用する画像内のテキストの検出に対して読み取りという用語が使用され、SDK では同じ操作に対してテキストという用語が使用されます。

Analysis 4.0 API の URL クエリパラメーターを設定して、使用する特徴を指定できます。パラメーターには、複数の値をコンマで区切って指定できます。

URL パラメーター	値	説明
`features`	`read`	画像の中に表示されるテキストを読み取り、構造化された JSON データとして出力します。
`features`	`caption`	サポートされる言語を使った完全な文章で画像のコンテンツを説明します。
`features`	`denseCaptions`	最大 10 個までの顕著な画像領域の詳細なキャプションを生成します。
`features`	`smartCrops`	関心領域を維持しながら目的の縦横比に画像を切り取るための四角形の座標を検出します。
`features`	`objects`	おおよその位置など、画像内のさまざまなオブジェクトを検出します。 Objects 引数は、英語でのみ使用できます。
`features`	`tags`	画像のコンテンツに関連した単語の詳細な一覧を使用して画像にタグを付けます。
`features`	`people`	おおよその位置など、画像に表示される人物を検出します。

値が指定された URL は、このようになります。

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

カスタムモデルを使用するときにモデル名を設定する

カスタムトレーニング済みモデルを使用して画像解析を行うこともできます。モデルを作成してトレーニングするには、「カスタムImage Analysisモデルを作成する」を参照してください。モデルがトレーニングされたら、必要なのはモデルの名前だけです。カスタムモデルを使用する場合は、視覚機能を指定する必要はありません。

カスタムモデルを使用するには、機能クエリパラメーターを使用しないでください。代わりに、次に示すように、model-name パラメーターをモデルの名前に設定します。 MyCustomModelName をカスタムモデル名に置き換えます。

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

言語を指定する

言語オプションは、標準モデルを使用している場合にのみ適用されます。

次の URL クエリパラメーターで言語を指定します。既定値は en です。

URL パラメーター	値	説明
`language`	`en`	英語
`language`	`es`	スペイン語
`language`	`ja`	日本語
`language`	`pt`	ポルトガル語
`language`	`zh`	簡体中国語

値が指定された URL は、このようになります。

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&language=en

性別に依存しないキャプションを選択する

キャプションまたは高密度キャプションを抽出する場合は、性別に依存しないキャプションを求めることができます。性別に依存しないキャプションは省略可能で、既定では性別の区別があるキャプションになっています。たとえば、英語では、性別に依存しないキャプションを選択すると、woman や man などの用語は person に置き換えられ、boy や girl は child に置き換えられます。

性別に依存しないキャプションのオプションは、標準モデルを使用している場合にのみ適用されます。

値 true または false (既定値) を使用して、オプションのクエリ文字列 gender-neutral-caption を追加します。

値が指定された URL は、このようになります。

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

スマートトリミング縦横比を選択する

スマートトリミング縦横比は、標準モデルを使用している場合にのみ適用されます。

1 つ以上の縦横比をコンマで区切って、オプションのクエリ文字列 smartcrops-aspect-ratios を追加します。

値が指定された URL は、このようになります。

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

サービスから結果を取得する

標準モデルを使用して結果を取得する

このセクションでは、標準モデルを使用してサービスに対して分析呼び出しを行い、結果を取得する方法について説明します。

サービスから 200 HTTP 応答が返され、その本文には、返されたデータが JSON 文字列の形式で含まれています。次のテキストは、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
        }
      ]
    }
  }

エラーコード

エラーが発生した場合、Image Analysis サービスの応答には、エラーコードとエラーメッセージを含む JSON ペイロードが含まれています。また、内部エラーコードとメッセージの形式で他の詳細を含めることもできます。次に例を示します。

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

一般的なエラーとその原因の一覧を次に示します。リストアイテムは次の形式で表示されます。

HTTP 応答コード
- JSON 応答内のエラーコードとメッセージ
  - [省略可能] JSON 応答内のエラーコードとメッセージ

一般的なエラーの一覧:

400 Bad Request
- InvalidRequest - Image URL is badly formatted or not accessible 画像の URL が有効でパブリックにアクセスできることを確認します。
- InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes 圧縮したり、サイズを変更したりして、画像のサイズを小さくし、要求を再送信します。
- InvalidRequest - The feature 'Caption' is not supported in this region この機能は、特定の Azure リージョンでのみサポートされています。サポートされている Azure リージョンの一覧については、「クイックスタートの前提条件」を参照してください。
- InvalidRequest - The provided image content type ... is not supported 次の要求中の HTTP ヘッダー Content-Type は、許可される型ではありません。
  - 画像の URL の場合、Content-Type は application/json である必要があります
  - バイナリ画像データの場合、Content-Type は application/octet-stream または 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 サポートされている画像形式については、「画像の要件」セクションを参照してください。
- InvalidRequest - Analyze query is invalid
  - NotSupportedVisualFeature - Specified feature type is not valid features クエリ文字列に有効な値が含まれることを確認します。
  - NotSupportedLanguage - The input language is not supported 次の表に基づいて、language クエリ文字列に、選択した視覚機能に対する有効な値が含まれることを確認します。
  - 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 サービスは、model-name クエリ文字列によって指定された名前に基づくカスタムモデルを見つけることができませんでした。

次のステップ

各機能の詳細については、概念に関する記事を参照してください。
GitHub で SDK コードサンプルを調べます。
- C#
- Python
- Java
- JavaScript
API の機能の詳細については、REST API リファレンスを参照してください。

次の方法で共有

Image Analysis 4.0 Analyze API を呼び出す

前提条件

クライアントを作成して認証する

分析する画像を選択する

画像 URL

イメージ バッファー

視覚的特徴を選択する

分析オプションを選択する

Analyze API を呼び出す

サービスから結果を取得する

トラブルシューティング

例外処理

前提条件

クライアントを作成して認証する

分析する画像を選択する

画像 URL

イメージ バッファー

視覚的特徴を選択する

オプションを指定して analyze_from_url メソッドを呼び出します

スマート トリミング縦横比を選択する

性別に依存しないキャプションを選択する

言語を指定する

サービスから結果を取得する

トラブルシューティング

例外

ログ機能

前提条件

クライアントを作成して認証する

分析する画像を選択する

画像 URL

イメージ バッファー

視覚的特徴を選択する

分析オプションを選択する

analyzeFromUrl メソッドを呼び出す

サービスから結果を取得する

トラブルシューティング

例外

HTTP 要求/応答ログを有効にする

環境変数を設定して有効にする

httpLogOptions を設定して有効にする

前提条件

クライアントを作成して認証する

分析する画像を選択する

画像 URL

イメージ バッファー

視覚的特徴を選択する

オプションを使用して Analyze API を呼び出す

スマート トリミング縦横比を選択する

性別に依存しないキャプションを選択する

言語を指定する

サービスから結果を取得する

トラブルシューティング

ログ機能

前提条件

サービスに対する認証

分析する画像を選択する

画像 URL

イメージ ファイル

分析オプションを選択する

標準モデルを使用するときに視覚機能を選択する

カスタム モデルを使用するときにモデル名を設定する

言語を指定する

性別に依存しないキャプションを選択する

スマート トリミング縦横比を選択する

サービスから結果を取得する

標準モデルを使用して結果を取得する

エラー コード

次のステップ

フィードバック

その他のリソース

イメージバッファー

イメージバッファー

スマートトリミング縦横比を選択する

イメージバッファー

イメージバッファー

スマートトリミング縦横比を選択する

イメージファイル

カスタムモデルを使用するときにモデル名を設定する

スマートトリミング縦横比を選択する

エラーコード