データスキーマの作成と更新

デプロイされたデータ取り込みアプリに接続された Vision Warehouse（corpus）には、1 つ以上のメディア オブジェクト assets があります。これらのメディア オブジェクト assets の詳細は、dataSchema とユーザー提供の annotation リソースを使用して指定できます。

データスキーマ キーを含む annotation リソースを作成するには、前にデータスキーマ リソースを作成する必要があります。メディア アノテーションの解釈方法を Vertex AI Vision API に通知するデータスキーマ（dataSchema リソース）を作成したら、ウェアハウス内のメディアの annotation リソースを作成できます。

データスキーマを作成する（API）

REST

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれている場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: Google Cloud プロジェクト番号。
• LOCATION_ID: Vertex AI Vision を使用するリージョン。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。
• DATASCHEMA_KEY: このキーは、ユーザー指定のアノテーションのキーと一致し、corpus 内で一意である必要があります。例: data-key
• ANNOTATION_DATA_TYPE: アノテーションのデータ型。使用可能な値は次のとおりです。
  • DATA_TYPE_UNSPECIFIED
  • INTEGER
  • FLOAT
  • STRING
  • DATETIME
  • GEO_COORDINATE
  • PROTO_ANY
  • BOOLEAN

  詳細については、API リファレンス ドキュメントをご覧ください。

• ANNOTATION_GRANULARITY: この dataSchema の下のアノテーションの粒度。使用可能な値は次のとおりです。
  • GRANULARITY_UNSPECIFIED - 粒度は指定されていません。
  • GRANULARITY_ASSET_LEVEL - アセットレベルの粒度（アノテーションには、メディアアセットの時間的パーティション情報を含めることはできません）。
  • GRANULARITY_PARTITION_LEVEL - パーティション レベルの粒度（アノテーションには、メディアアセットのテンポラル パーティション情報が含まれている必要があります）。
• SEARCH_STRATEGY: 使用可能な列挙値のいずれか。アノテーション キーに適用する検索戦略のタイプ。使用可能な値は次のとおりです。
  • NO_SEARCH
  • EXACT_SEARCH
  • SMART_SEARCH

HTTP メソッドと URL:

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

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

{
  "key": "DATASCHEMA_KEY",
  "schema_details": {
    "type": "ANNOTATION_DATA_TYPE",
    "granularity": "ANNOTATION_GRANULARITY",
    "search_strategy": {
      "search_strategy_type": "SEARCH_STRATEGY"
    }
  }
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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/dataSchemas"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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/dataSchemas" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "data-key",
  "schemaDetails": {
    "type": "BOOLEAN",
    "granularity": "GRANULARITY_ASSET_LEVEL",
    "searchStrategy": {
      "search_strategy_type": "EXACT_SEARCH"
    }
  }
}

データスキーマを更新する（API）

REST とコマンドライン

次のコードは、projects.locations.corpora.dataSchemas.patch メソッドを使用して dataSchema を更新します。

このサンプルでは、リクエスト URL で ?updateMask=schemaDetails.type,schemaDetails.granularity を使用し、リクエスト本文に新しい schemaDetails.type 値と schemaDetails.granularity 値を含めて、データスキーマを更新します。

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれている場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: Google Cloud プロジェクト番号。
• LOCATION_ID: Vertex AI Vision を使用するリージョン。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。
• DATASCHEMA_ID: ターゲット データ スキーマの ID。
• ?updateMask=fieldToUpdate: updateMask を適用できる使用可能なフィールドの 1 つ。リクエスト本文で、対応する新しいフィールド値を指定します。この新しい値は、既存のフィールド値に置き換えられます。使用可能なフィールド:
  • キー: ?updateMask=key
  • スキーマタイプ: ?updateMask=schemaDetails.type
  • スキーマの粒度: ?updateMask=schemaDetails.granularity
  • スキーマ検索戦略のタイプ: ?updateMask=schemaDetails.searchStrategy.searchStrategyType
  • すべてのフィールドを更新: ?updateMask=*

HTTP メソッドと URL:

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity

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

{
  "key": "original-data-key",
  "schemaDetails": {
    "type":"INTEGER",
    "granularity":"GRANULARITY_PARTITION_LEVEL"
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

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

curl -X PATCH \
     -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/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

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

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

Invoke-WebRequest `
    -Method PATCH `
    -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/dataSchemas/DATASCHEMA_ID?updateMask=schemaDetails.type,schemaDetails.granularity" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "original-data-key",
  "schemaDetails": {
    "type": "INTEGER",
    "granularity": "GRANULARITY_PARTITION_LEVEL",
    "searchStrategy": {
      "searchStrategyType": "NO_SEARCH"
    }
  }
}

カスタム構造化データ スキーマを追加する

カスタム構造体を使用すると、より複雑なコンテナを定義して値を保持し、検索機能を提供できます。この機能を使用するには、次のようにデータスキーマを定義する必要があります。

REST

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれている場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: Google Cloud プロジェクト番号。
• LOCATION_ID: Vertex AI Vision を使用するリージョン。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。

HTTP メソッドと URL:

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

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

{
  "key": "person",
  "schema_details" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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/dataSchemas"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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/dataSchemas" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/dataSchemas/DATASCHEMA_ID",
  "key": "person",
  "schemaDetails" : {
    "type":"CUSTOMIZED_STRUCT",
    "granularity":"GRANULARITY_ASSET_LEVEL",
    "customized_struct_config": {
      "field_schemas": {
         "name": {
            "type":"STRING",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         },
         "age": {
            "type":"FLOAT",
            "granularity":"GRANULARITY_ASSET_LEVEL",
            "search_strategy": {
               "search_strategy_type":"EXACT_SEARCH"
            }
         }
      }
    }
  }
}

その後、アノテーションを挿入できます。

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれている場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: Google Cloud プロジェクト番号。
• LOCATION_ID: Vertex AI Vision を使用するリージョン。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。
• ASSET_ID: ターゲット アセットの 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": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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": "person",
    "value": {
      "customized_struct_value":{
        "elements" : {
          "name": {
            "str_value":"John"
          },
          "age": {
            "float_value":10.5
          }
        }
      }
    }
  }
}

アノテーションがインデックスに登録されたら、次のように検索リクエストを送信できます。

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれている場合があります。 リージョン化されたエンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: Google Cloud プロジェクト番号。
• LOCATION_ID: Vertex AI Vision を使用するリージョン。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。

HTTP メソッドと URL:

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

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

{
  "page_size": 10,
  "criteria": {
    "field": "person.name",
    "text_array": {
      "txt_values": "John"
    },
  },
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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:searchAssets"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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:searchAssets" | Select-Object -Expand Content

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

レスポンス

{
  "searchResultItems": [
    {
      "asset": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID1",
      "segments": [
        {
          "startTime": "2020-09-01T02:51:55Z",
          "endTime": "2020-09-01T02:52:09.996016Z"
        }
      ],
      "segment": {
        "startTime": "2023-07-07T16:36:10.652575Z",
        "endTime": "2023-07-07T20:30:48.812575Z"
      }
    }
  ]
}

ウェアハウス スキーマの詳細を変更する（コンソール）

スキーマ フィールドは、アプリケーションを介してモデルから生成されます。カスタム フィールドを追加することもできます。

フェイステーブル フィールドを変更したら、それを使用してウェアハウスを検索できます。

Console

1. Vertex AI Vision ダッシュボードの [倉庫] タブを開きます。

   [倉庫] タブに移動

2. 目的の倉庫を見つけて、その名前を選択します。[倉庫の詳細] ページが表示されます。

3. 検索で有効にするフィールドを選択します。