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

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

データスキーマキーを持つ annotation リソースを作成するには、そのデータスキーマキーを持つデータスキーマ リソースを事前に作成する必要があります。 Gemini Enterprise Agent Platform Vision API にメディア アノテーションの解釈方法を伝えるデータ スキーマ（dataSchema リソース）を作成したら、ウェアハウス内のメディアの annotation リソースを作成できます。

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

REST

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれる場合があります。リージョン エンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: プロジェクト番号。 Google Cloud
• LOCATION_ID: Agent Platform 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: 使用可能な enum 値のいずれか。アノテーション キーに適用する検索戦略のタイプ 。使用できる値は次のとおりです。
  • 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 とコマンドライン

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

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

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

• REGIONALIZED_ENDPOINT: エンドポイントには、LOCATION_ID に一致する接頭辞（europe-west4- など）が含まれる場合があります。リージョン エンドポイントの詳細をご覧ください。
• PROJECT_NUMBER: プロジェクト番号。 Google Cloud
• LOCATION_ID: Agent Platform Vision を使用しているリージョン 。例: us-central1、europe-west4。利用可能なリージョンをご覧ください。
• CORPUS_ID: ターゲット コーパスの ID。
• DATASCHEMA_ID: ターゲット データスキーマの ID。
• ?updateMask=fieldToUpdate: を適用できる使用可能なフィールドのいずれか。updateMaskリクエスト本文で対応する新しいフィールド値を指定します。この新しい値は、既存のフィールド値を置き換えます。使用可能なフィールド:
  • キー: ?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: Agent Platform 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: Agent Platform 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: Agent Platform 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"
      }
    }
  ]
}

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

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

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

コンソール

1. Gemini Enterprise Agent Platform Vision ダッシュボードの [Warehouses] タブを開きます。

   [Warehouses] タブに移動

2. 目的のウェアハウスを見つけて、その名前を選択します。[Warehouse Details] ページが表示されます。

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