アノテーションを管理する

Vision Warehouse API を使用すると、コマンドラインで Vision Warehouse リソースを管理できます。

データ取り込みデプロイ済みアプリの接続済みウェアハウス（corpus）には、1 つ以上のメディア オブジェクト（動画リソースなど）があります。これらのメディア オブジェクト（asset リソース）には、メタデータとリソース アノテーション（annotations）が含まれています。メディア オブジェクトで使用されるモデルに応じて、これらのアノテーションは、ラベル、バウンディング ボックス、タイムスタンプなど、さまざまな種類の情報で構成できます。

これらのアノテーションを管理するには、次のコマンドを使用します。

アノテーションには次の 2 種類があります。

  1. アセット単位のアノテーション: アセット全体に適用されるアノテーション。例: camera-location。
  2. パーティション レベルのアノテーション: アセットの一部にのみ適用されるアノテーション。パーティション レベルのアノテーション情報を取得するには、ストリーミング動画アセットの時間パーティション（開始時間と終了時間）またはバッチ動画アセットの相対時間パーティション（開始オフセットまたは終了オフセット）を指定する必要があります。

アノテーションを作成する前に、同じキーを使用して対応するデータ スキーマを作成し、アノテーションの値のデータ型を示す必要があります。特定のキーの値の型を変更する必要がある場合は、このキーを使用しているすべてのアノテーションを削除する必要があります。これらのアノテーションを削除したら、対応するデータスキーマを更新できます。

ウェアハウス アセットのアノテーションを作成する

アセットのアノテーションを作成するには、次の手順を事前に完了する必要があります。

  • ウェアハウスに asset リソースを作成します。
  • 同じキーを使用して dataSchema リソースを作成し、annotation 値のデータ型を示します。

annotation リソースには、必要に応じて時間パーティションを関連付けることができます。たとえば、アノテーションがアセット全体に適用される場合は、関連付けられている時間パーティションを省略できます。同様に、アノテーションが動画アセットの特定の部分にのみ適用される場合は、annotation リソースの作成時にアセットの時間範囲を指定できます。

時間パーティションなしでアノテーションを作成する

アノテーションが動画アセット全体に適用される場合は、時間パーティションを指定する必要はありません。次のサンプルを使用して、アセット全体（動画の期間が指定されていない）の annotation リソースを作成します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致するプレフィックス（europe-west4- など）が含まれる場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • LOCATION_ID: Agent Platform Vision を使用しているリージョン。たとえば、us-central1、europe-west4 などです。利用可能なリージョンをご覧ください。
  • CORPUS_ID: ターゲット コーパスの ID。
  • ASSET_ID: ターゲット アセットの ID。
  • ANNOTATION_ID: （省略可）ユーザーが指定したアノテーション ID の値。このリクエストでは、値は次の形式でリクエスト URL に追加されます。
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_ID

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

リクエストの本文（JSON）: 

{
  "user_specified_annotation":{
    "key": "camera-location",
    "value": {
      "str_value": "Sunnyvale"
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "camera-location",
    "value": {
      "strValue": "Sunnyvale"
    }
  }
}

時間パーティションを含むアノテーションを作成する

ストリーミング動画アセットの一部にのみアノテーションを適用する場合は、対象の動画部分の時間範囲を指定できます。次のサンプルを使用して、時間パーティションを使用して動画アセットの特定の期間の annotation リソースを作成します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致するプレフィックス（europe-west4- など）が含まれる場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • LOCATION_ID: Agent Platform Vision を使用しているリージョン。たとえば、us-central1、europe-west4 などです。利用可能なリージョンをご覧ください。
  • CORPUS_ID: ターゲット コーパスの ID。
  • ASSET_ID: ターゲット アセットの ID。
  • ANNOTATION_ID: （省略可）ユーザーが指定したアノテーション ID の値。このリクエストでは、値は次の形式でリクエスト URL に追加されます。
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_ID

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

リクエストの本文（JSON）: 

{
  "user_specified_annotation": {
    "key": "object-detected",
    "value": {
      "str_value": "cat"
    },
    "partition": {
      "temporal_partition": {
        "start_time": {
          "seconds": "1630464728"
        },
        "end_time": {
          "seconds": "1630464729"
        }
      }
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations/ANNOTATION_ID",
  "userSpecifiedAnnotation": {
    "key": "object-detected",
    "value": {
      "strValue": "cat"
    },
    "partition": {
      "temporalPartition": {
        "startTime": "2022-09-14T20:33:09Z",
        "endTime": "2022-09-14T20:33:39Z"
      }
    }
  }
}

相対時間パーティションを含むアノテーションを作成する

アノテーションがバッチ動画アセットの一部にのみ適用される場合は、対象の動画部分の時間範囲を指定できます。次のサンプルを使用して、相対時間パーティションを使用して動画アセットの特定の期間の annotation リソースを作成します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致するプレフィックス（europe-west4- など）が含まれる場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • LOCATION_ID: Agent Platform Vision を使用しているリージョン。たとえば、us-central1、europe-west4 などです。利用可能なリージョンをご覧ください。
  • CORPUS_ID: ターゲット コーパスの ID。
  • ASSET_ID: ターゲット アセットの ID。
  • ANNOTATION_ID: （省略可）ユーザーが指定したアノテーション ID の値。このリクエストでは、値は次の形式でリクエスト URL に追加されます。
    • https://ENDPOINT/v1/[...]/corpora/CORPUS_ID/assets/ASSET_ID/annotations?annotation_id=ANNOTATION_ID

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID/annotations

リクエストの本文（JSON）: 

{
  "user_specified_annotation": {
    "key": "object-detected",
    "value": {
      "str_value": "cat"
    },
    "partition": {
      "relative_temporal_partition": {
        "start_offset": {
          "seconds": "60"
        },
        "end_offset": {
          "seconds": "300"
        }
      }
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl