Image Analysis 3.2 API の呼び出し

この記事では、Image Analysis 3.2 API を呼び出して画像の視覚的特徴に関する情報を返す方法について説明します。 また、クライアント SDK または REST API を使用して、返された情報を解析する方法も示します。

このガイドでは、既に Vision リソースを作成し、キーとエンドポイント URL を取得していることを前提としています。 クライアント SDK を使用している場合は、クライアント オブジェクトを認証する必要もあります。 これらの手順を実行していない場合は、クイックスタートに従って作業を開始してください。

サービスにデータを送信する

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

リモートの画像を分析する場合、要求本文を {"url":"http://example.com/images/test.jpg"} のような形式にして、画像の URL を指定します。

ローカルの画像を分析するには、バイナリ画像データを HTTP 要求本文に配置します。

データの処理方法を決定する

視覚的特徴を選択する

Analyze API を使用すると、サービスの画像分析の特徴すべてにアクセスできます。 独自のユース ケースに基づいて、行う操作を選択します。 各機能の説明については、概要のページを参照してください。 下のセクションの例では、使用可能なすべての視覚的特徴を追加していますが、実際に使用するために必要なものは 1 つか 2 つのみです。

Analyze API の URL クエリ パラメーターを設定して、使用する特徴を指定できます。 パラメーターには、複数の値をコンマで区切って指定できます。 特徴を指定するごとに、より多くの処理時間が必要になるため、必要なものだけを指定してください。

URL パラメーター 説明
features Read 画像の中に現れるテキストを読み取り、構造化された JSON データとして出力します。
features Description サポートされる言語の完全な文章を使用して画像のコンテンツを説明します。
features SmartCrops 関心領域を維持しながら、目的のアスペクト比に画像を切り取る長方形の座標を見つけます。
features Objects おおよその場所など、画像内のさまざまなオブジェクトを検出します。 Objects 引数は、英語でのみ使用できます。
features Tags 画像のコンテンツに関連した単語の詳細な一覧を使用して画像にタグを付けます。

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

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

言語を指定する

返されるデータの言語を指定することもできます。

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

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

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

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

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

このセクションでは、API 呼び出しの結果を解析する方法について説明します。 これには、API 呼び出し自体が含まれます。

Note

スコープが指定された API 呼び出し

画像分析における特徴の一部は、Analyze API 呼び出しを使用した方法だけでなく、直接呼び出すこともできます。 たとえば、<endpoint>/vision/v3.2/tag に (または SDK の対応するメソッドに) 要求を行うことで、画像タグのみのスコープ分析を行うことができます。 個別に呼び出すことができる他の特徴については、リファレンス ドキュメントを参照してください。

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

エラー コード

考えられるエラーとその原因を次の一覧に示します。

  • 400
    • InvalidImageUrl - イメージの URL の形式が不適切か、アクセスできません。
    • InvalidImageFormat - I入力データが有効なイメージではありません。
    • InvalidImageSize - 入力イメージが大きすぎます。
    • NotSupportedVisualFeature - 指定された特徴の種類が有効ではありません。
    • NotSupportedImage - サポートされていないイメージ、たとえば、子供のポルノ イメージです。
    • InvalidDetails - ポートされていない detail パラメーター値。
    • NotSupportedLanguage - 要求された操作が指定された言語でサポートされていません。
    • BadArgument - 追加の詳細情報がエラー メッセージに記載されています。
  • 415 - サポートされていないメディアの種類エラー。 Content-Type が使用できる種類に含まれていません。
    • 画像の URL の場合、Content-Type は application/json である必要があります。
    • バイナリ画像データの場合、Content-Type は application/octet-stream または multipart/form-data である必要があります。
  • 500
    • FailedToProcess
    • Timeout - 画像処理がタイムアウトしました。
    • InternalServerError

ヒント

Azure AI Vision の操作中に、このサービスによって適用されたレート制限によって一時的な障害が発生したり、ネットワークの停止など、他の一時的な問題が発生したりする可能性があります。 これらの種類の障害の処理については、クラウド設計パターン ガイドの「再試行パターン」および「サーキット ブレーカー パターン」を参照してください。

次のステップ