チュートリアル: person ディレクトリを作成する (プレビュー)

person ディレクトリは、認識タスク用の顔データを格納するための構造化されたアプローチを提供します。個々の顔を追加したり、視覚的に似た顔を検索したり、人物プロファイルを作成したりできます。顔をこれらのプロファイルに関連付け、新しい顔の画像を既知の個人に一致させることができます。このセットアップでは、柔軟な顔照合と画像とビデオ全体の ID 認識の両方がサポートされます。

データストレージに関する推奨事項

セキュリティで保護されたスケーラブルなアクセスを実現するために、すべての顔イメージを Azure Blob Storage に格納することをお勧めします。 API 呼び出しを行うときは、顔の URL が Blob Storage に格納されているこれらのイメージを参照していることを確認します。

登録

登録には、次の手順が含まれます。

空のユーザーディレクトリを作成する
ユーザーを追加する
顔を追加してユーザーに関連付ける

空のユーザーディレクトリを作成する

新しいユーザーディレクトリを作成するには、API エンドポイントに PUT 要求を送信します。このディレクトリは、顔と関連人物を格納するためのコンテナーとして機能します。

PUT {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}?api-version=2025-05-01-preview
Content-Type: application/json

{
  "description": "A brief description of the directory",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  }
}

personDirectoryId: リソース内のディレクトリの一意のユーザー定義識別子。
description: (省略可能) ディレクトリの目的の簡単な説明。
tags: (省略可能) ディレクトリの整理と管理に役立つキーと値のペア。

API によってディレクトリが作成され、確認応答が返されます。

200 OK

{
  "personDirectoryId": "{personDirectoryId}",
  "description": "A brief description of the directory",
  "createdAt": "2025-05-01T18:46:36.051Z",
  "lastModifiedAt": "2025-05-01T18:46:36.051Z",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  },
  "personCount": 0,
  "faceCount": 0
}

ユーザーを追加する

個人を認識または管理するには、個人プロファイルを作成する必要があります。作成したら、顔をこのユーザーに関連付けることができます。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/persons?api-version=2025-05-01-preview
Content-Type: application/json

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}

personDirectoryId: 手順 1 で作成されたディレクトリのユニークID。
tags: 名前や年齢など、人物を表すキーと値のペア。

API は、作成されたユーザーを一意に識別する personId を返します。

200 OK

{
  "personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}

顔を追加してユーザーに関連付ける

ディレクトリに顔を追加し、必要に応じて既存のユーザーに関連付けることができます。 API では、イメージ URL と base64 でエンコードされた画像データの両方がサポートされます。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/face.jpg",
    // "data": "<base64 data>",
    "imageReferenceId": "face.jpg",
    "targetBoundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "qualityThreshold": "medium",
  "personId": "{personId}"
}

personDirectoryId: 手順 1 で作成した人物ディレクトリの一意識別子。
faceSource: 顔の画像を指定します。
- url: Azure Blob Storage に格納されているイメージのファイルパス。
- data: urlの代替手段として Base64 でエンコードされた画像データ。
- imageReferenceId: (省略可能) イメージのユーザー定義識別子。この識別子は、画像の原点を追跡したり、他のデータにマッピングしたりするのに役立ちます。
- targetBoundingBox: (省略可能) 画像内の顔のおおよその位置。省略すると、API は最大の顔を検出して使用します。
qualityThreshold: (省略可能) 顔の品質 (low、medium、またはhigh) をフィルタリングします。既定値は medium です。つまり、中または高品質の顔のみが格納されます。低品質の顔は拒否されます。
personId: (オプション) 顔を関連付ける対象である既存ユーザーの personId。

APIは、検出された顔のfaceIdを用いて作成された顔を一意に識別するboundingBoxを返します。

{
  "faceId": "{faceId}",
  "personId": "{personId}",
  "imageReferenceId": "face.jpg",
  "boundingBox": {
    "left": 30,
    "top": 78,
    "width": 251,
    "height": 309
  }
}

人物ディレクトリを使用する

人物ディレクトリを作成し、オプションの人物の関連付けを使用して顔画像を追加した後、次の 2 つの主要なタスクを実行できます。

人物を識別する: 顔の画像をディレクトリ内の登録済みユーザーと照合し、最も可能性の高い ID を決定します。
似た顔を検索する: ディレクトリに格納されているすべての顔エントリで、視覚的に似た顔を検索します。

これらの機能により、さまざまなアプリケーションで堅牢な顔認識と類似性の照合が可能になります。

ユーザーを識別する

入力された顔をディレクトリ内の登録されている人物と比較して、最も一致する人物を特定します。

POST {endpoint}/contentunderstanding/personDirectory/{personDirectoryId}/persons:identify?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/unknown.jpg",
    "targetBoundingBox": { ... }
  },
  "maxPersonCandidates": 1
}

faceSource.url: Azure Blob Storage に格納されている入力顔イメージの URL。
faceSource.targetBoundingBox: (オプション) 画像内の顔の近似境界ボックス。省略すると、API は最大の顔を検出します。
maxPersonCandidates: (省略可能) 返される人物候補の最大数。既定値のは 1 です。

API は、上位の人物候補と併せて、その顔で検出された境界ボックスを返します。

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}

detectedFace.boundingBox: 入力画像で検出された顔の境界ボックス。
personCandidates: 一致する可能性のある一致の一覧。それぞれに personId、関連付けられた tags、および一致の可能性を示す confidence スコアが含まれます。

似た顔の検索

ディレクトリに格納されているすべての顔エントリから、視覚的に似た顔を検索します。

POST {endpoint}/personDirectory/{personDirectoryId}/faces:find?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/target.jpg",
    "targetBoundingBox": { ... }
  },
  "maxSimilarFaces": 10
}

faceSource.url: Azure Blob Storage に格納されている入力顔イメージの URL。
faceSource.targetBoundingBox: (オプション) 画像内の顔の近似境界ボックス。省略すると、API は最大の顔を検出します。
maxSimilarFaces: (省略可能) 返される類似した顔の最大数。既定値は 1000 で、上限は 1000 です。

API は、検出された顔の境界ボックスと、ディレクトリから最も類似した顔を返します。

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}

detectedFace.boundingBox: 入力画像で検出された顔の境界ボックス。
similarFaces:類似した顔のリスト。それぞれ、 faceId、 boundingBox、 confidence スコア、ソースイメージを示す imageReferenceId が含まれます。

次のステップ

Foundry Tools のビデオソリューション (プレビュー) で Azure Content Understanding を使用して、ビデオコンテンツ内の個人を識別する方法について説明します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-09-16