コマンドラインを使用してストリーミング動画倉庫データを検索する

Vision Warehouse を作成し、アプリに追加して、アプリをデプロイしたら、ストリーミング動画ウェアハウスに保存されているデータを検索できます。

ストリーミング動画のメタデータを検索する

ウェアハウス（corpus）内のデータ（assets）を検索するには、検索するコンテンツを SearchAssetsRequest に入力します。このコンテンツには、いくつかの異なる形式があります。

  1. criteria - ユーザーが提供したテキスト、数値、日付のコンテンツ。
  2. facet_selections - サーバーから返され、ユーザーが選択したテキスト コンテンツ。
  3. content_time_ranges - 返されるすべてのコンテンツが該当する日付範囲。

次の例では、全国のさまざまなタイプの店舗の防犯カメラ映像を含む Warehouse について考えてみましょう。アノテーション "state": "California" またはアノテーション "state":"Pennsylvania" でタグ付けされた 2018 年または 2020 年のすべてのアセットを取得するには、次のリクエストを送信します。

REST

アセットを検索するには、projects.locations.corpora.searchAssets メソッドを使用して POST リクエストを送信します。

このサンプル本文では、criteria フィールドで textArray 値を使用して、2 つの txt_values（「California」と「Pennsylvania」）を指定しています。他のデータ型の検索条件を指定することもできます。各リクエストで指定できる検索条件は 1 つのみです。

その他の検索条件オプション

整数の範囲（両端を含む）

    "int_range_array" : {
      "int_ranges": { "start": "5", "end": "10" }
      "int_ranges": { "start": "20", "end": "30" }
    }

浮動小数点数の範囲（両端を含む）

    "float_range_array" : {
      "float_ranges": { "start": "2.6", "end": "14.3" }
      "float_ranges": { "start": "205.3", "end": "205.8" }
    }

位置情報（座標と半径）

    "geo_location_array": {
      "circle_areas": {
        "latitude": "37.4221",
        "longitude": "122.0841",
        "radius_meter": "500"
      },
      "circle_areas": {
        "latitude": "12.46523",
        "longitude": "-95.2146",
        "radius_meter": "100"
      }
    }

ブール値

    "bool_value" : {
      "value": "true"
    }

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

HTTP メソッドと URL:

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

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

{
  "page_size": "2",
  "content_time_ranges": {
    "date_time_ranges": {
      "start": {
        "year":"2018",
        "month":"1",
        "day":"1",
      },
      "end": {
        "year":"2019",
        "month":"1",
        "day":"1",
      }
    },
    "date_time_ranges": {
      "start": {
        "year":"2020",
        "month":"1",
        "day":"1",
      },
      "end": {
        "year":"2021",
        "month":"1",
        "day":"1",
      }
    }
  },
  "criteria": {
    "field": "state",
    "text_array": {
      "txt_values": "California",
      "txt_values": "Pennsylvania"
    }
  }
}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content

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

結果の次のページを取得するには、返された next_page_token を追加した元のリクエスト パラメータを渡します。

facet_results 配列には、元のクエリに一致したコンテンツが表示されます。上記のレスポンスは、1 台のセキュリティ カメラがスポーツ用品店に配置され、もう 1 台が食料品店に配置されていることを示しています。

このクエリを食料品店の映像のみを表示するように制限するには、ファセット選択を含む同じリクエストを渡します。

ファセット選択を含む JSON 本文のリクエスト:

{
  "page_size": "2",
  "content_time_ranges": {
    "date_time_ranges": {
      "start": {
        "year":"2018",
        "month":"1",
        "day":"1",
      },
      "end": {
        "year":"2018",
        "month":"12",
        "day":"31",
      }
    },
    "date_time_ranges": {
      "start": {
        "year":"2020",
        "month":"1",
        "day":"1",
      },
      "end": {
        "year":"2020",
        "month":"12",
        "day":"31",
      }
    }
  },
  "criteria": {
    "field": "state",
    "text_array": {
      "txt_values": "California",
      "txt_values": "Pennsylvania"
    }
  },
  "facet_selections": {
    "facetId": "state",
    "displayName": "State",
    "buckets": {
        "value": {
         "stringValue": "California"
        }
    },
    "buckets": {
      "value": {
        "stringValue": "Pennsylvania"
      }
    },
    "bucketType": "FACET_BUCKET_TYPE_VALUE"
  },
  "facet_selections": {
    "facetId": "store-type",
    "displayName": "StoreType",
    "buckets": {
      "value": {
        "stringValue": "Sporting Goods"
      }
    },
    "buckets": {
      "value": {
        "stringValue": "Grocery"
      },
      "selected": "true"
    },
    "bucketType": "FACET_BUCKET_TYPE_VALUE"
  }
}

Grocery ファセットが選択されているため、レスポンスにはアノテーション "store-type":"Grocery" が含まれます。

検索時にクリップ アセットのメタデータを返す

Vertex AI Vision API では、result_annotation_keys を使用して、検索結果とともに返す追加のクリップ メタデータを指定することもできます。

REST

この例では、ユーザーが指定したアノテーション キー "camera-location" がリクエストの本文で指定され、キーの値（"Sunnyvale"）がレスポンスで提供されます。

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

HTTP メソッドと URL:

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

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

{
   "page_size": "2",
   "criteria": {
     "field": "state",
     "text_array": {
       "txt_values": "California",
       "txt_values": "Pennsylvania"
     }
   },
   "result_annotation_keys": "camera-location"
}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content

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

条件を使用して検索でアセット メタデータを返す

検索条件で、各検索結果アイテムに一致するアノテーションを返すかどうかを指定できます。この機能は、INTEGER、FLOAT、BOOLEAN、STRING（EXACT_SEARCH のみ）のデータ スキーマ型でサポートされています。アノテーションはパーティション レベルで指定する必要があります。

ウェアハウス コーパスに次のデータ スキーマを作成するとします。

{
  "key": "image-classification",
  "schema_details": {
    "type":"STRING",
    "granularity":"GRANULARITY_PARTITION_LEVEL",
    "search_strategy": {
      "search_strategy_type":"EXACT_SEARCH"
    }
  }
}

"image-classification" の一部のアノテーションは、ストリーミング動画の取り込みまたは CreateAnnotation リクエストを使用してコーパスに取り込まれます。

アノテーションが取り込まれたら、"image-classification" を検索して、動画の結果と対応するアノテーションを取得できます。

REST

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

HTTP メソッドと URL:

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

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

{
  "page_size": "5",
  "facet_selections": {
    "facet_id": "image-classification",
    "fetch_matched_annotations": "true",
    "bucket_type": "FACET_BUCKET_TYPE_VALUE",
      "buckets": {
        "value": {
          "string_value": "cat"
        },
        "selected" : "true"
      },
  }
}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content

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

グローバル検索では、個々の条件を指定するのではなく、検索クエリを入力する場所が提供されます。データスキーマで検索可能に設定された文字列型の条件に対して検索できます。一致する結果が取得され、返されます。

この機能を使用するには、SearchAssetsRequest で search_query フィールドを設定します。

REST

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

HTTP メソッドと URL:

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

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

{
    "page_size": "2",
    "search_query': "Pennsylvania"
}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content

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

検索で返品されたアセット メタデータに並べ替え仕様を適用

並べ替え機能を使用すると、ユーザーが指定した annotation で検索結果を並べ替えることができます。これは、文字列型や数値型など、順序付け可能なデータ スキーマ型で結果を並べ替える場合に便利です。

この機能を使用するには、schema_key_sorting_strategy を指定します。これには、少なくともデータスキーマキーと昇順/降順が必要です。

REST

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

HTTP メソッドと URL:

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

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

{
    "page_size": "2",
    "schemaKeySortingStrategy":
    { "options": 
      { 
        "data_schema_key": "stream-display-name", 
        "sort_decreasing": true
      } 
    }

}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content

成功したことを示すステータス コード（2xx）と空のレスポンスが返されます。

検索構成を作成する

Vision Warehouse では、検索構成を通じて検索エクスペリエンスをカスタマイズできます。検索設定では、ユーザーが提供したアノテーションや Google Cloud 動画理解モデルによって生成された分析情報などの動画データを使用して、ユーザーに追加の検索オプションを提供します。たとえば、ウェアハウス内の車の動画データから特定の色の車を含むクリップをターゲットにする場合は、クエリに特定の検索構成を使用できます。

SearchConfig を使用して、より詳細な構成オプションを設定できます。

次の例は、SearchConfig リソースを作成する方法を示しています。

一般的なガイドライン

すべてのユースケースで、リクエストが正常に実行されるには、次の条件を満たしている必要があります。

  1. Request.search_configuration.name はまだ存在していない必要があります。
  2. mapped_fields 配列は空ではなく、既存のユーザー指定のアノテーション キーにマッピングされている必要があります。
  3. すべての mapped_fields は同じ型でなければなりません。
  4. すべての mapped_fields は完全一致/スマート一致の構成を共有する必要があります。
  5. すべての mapped_fields は同じ粒度を共有する必要があります。

SearchConfig の作成にはいくつかのユースケースがあり、それぞれに遵守すべきガイドラインがあります。

カスタム検索条件を使用して検索構成を作成する

このセクションでは、カスタム オペレータをユーザーが指定した 1 つ以上のアノテーション キーにマッピングする方法について説明します。この場合、リクエストを作成する際に一般的なガイドラインを満たす必要があります。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

この例では、ユーザーが指定したアノテーション キーは "player"、"coach"、"cheerleader" です。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=person

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

{
   "search_criteria_property": {
     "mapped_fields": "player",
     "mapped_fields": "coach",
     "mapped_fields": "cheerleader",
  }
}

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

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/searchConfigs?search_config_id=person"

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/searchConfigs?search_config_id=person" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs/person",
  "searchCriteriaProperty":
    {
      "mappedFields": [
        "player",
        "coach",
        "cheerleader"
      ]
    }
}

1 対 1 のファセット マッピングで検索構成を作成する

ユーザー指定のアノテーション キーのファセットを作成するには、Request.search_configuration.facet_property.mapped_fields に単一の要素が含まれていることを確認する必要があります。この要素の値は、ユーザーが指定したアノテーション キー名である必要があります。

次の例は、ユーザー指定のアノテーション キー "Location" のファセット マッピングを作成する方法を示しています。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

この例では、リクエスト URL の search_config_id（Location）が既存のユーザー指定のアノテーション キーを参照し、mapped_fields に search_config_id（Location）と等しい値を持つ要素が 1 つだけ含まれているため、リクエストは成功します。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location

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

{
   "facet_property": {
     "mapped_fields": "Location",
     "display_name": "Location",
     "result_size": "5",
     "bucket_type":"FACET_BUCKET_TYPE_VALUE"
  }
}

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

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/searchConfigs?search_config_id=Location"

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/searchConfigs?search_config_id=Location" | Select-Object -Expand Content
 

次のリクエストは、必要な要件を満たしていないため失敗します。

失敗したリクエストの数

失敗したリクエスト 1:

      curl -X POST \
      -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
      -H "Content-Type: application/json; charset=utf-8" \
      https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location \
      -d "{
         "facet_property": {
           "mapped_fields": "City", /* City is not equal to search_config_id. */
           "display_name": "City",
           "result_size": "5",
           "bucket_type":"FACET_BUCKET_TYPE_VALUE"
        }
      }"

失敗したリクエスト 2:

      curl -X POST \
      -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
      -H "Content-Type: application/json; charset=utf-8" \
      https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=City \
      -d "{
         "facet_property": {
           "mapped_fields": "City", /* City doesn't map to an existing user-given annotation key. */
           "display_name": "City",
           "result_size": "5",
           "bucket_type":"FACET_BUCKET_TYPE_VALUE"
        }
      }"

失敗したリクエスト 3:

      curl -X POST \
      -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
      -H "Content-Type: application/json; charset=utf-8" \
      https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location \
      -d "{
         "facet_property": {
           "mapped_fields": "Location",
           "mapped_fields": "City", /* mapped_fields contains more than 1 element. */
           "display_name": "Location",
           "result_size": "5",
           "bucket_type":"FACET_BUCKET_TYPE_VALUE"
        }
      }"

カスタムの 1:1 以上のファセット マッピングを使用して検索構成を作成する

カスタム ファセット値と 1 つ以上のユーザー指定のアノテーション キー間のマッピングを作成するクライアントは、次のことを確認する必要があります。

  1. Request.search_configuration には、Request.search_configuration.search_criteria_property.mapped_fields に Request.search_configuration.facet_property.mapped_fields と同じ要素が含まれるような SearchCriteriaProperty を含める必要があります。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

次の例は、ユーザー指定のアノテーション キー "City" と "State" のファセット マッピングを作成する方法を示しています。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location

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

{
  "search_criteria_property": {
     "mapped_fields": "City",
     "mapped_fields": "State",
     "mapped_fields": "Province",
  }
  "facet_property": {
     "mapped_fields": "City",
     "mapped_fields": "State",
     "display_name": "Province",
     "result_size": "5",
     "bucket_type":"FACET_BUCKET_TYPE_VALUE"
  }
}

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

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/searchConfigs?search_config_id=Location"

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/searchConfigs?search_config_id=Location" | Select-Object -Expand Content
 

次のリクエストは、必要な要件を満たしていないため失敗します。

失敗したリクエストの数

失敗したリクエスト 1:

      curl -X POST \
      -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
      -H "Content-Type: application/json; charset=utf-8" \
      https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location \
      -d "{
        "facet_property": { /* Request is missing a SearchCriteriaProperty object.*/
           "mapped_fields": "City",
           "mapped_fields": "State",
           "display_name": "Location",
           "result_size": "5",
           "bucket_type":"FACET_BUCKET_TYPE_VALUE"
        }
      }"

失敗したリクエスト 2:

      curl -X POST \
      -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
      -H "Content-Type: application/json; charset=utf-8" \
      https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=Location \
      -d "{
        "search_criteria_property": {
           "mapped_fields": "City",
           "mapped_fields": "State",
        }
        "facet_property": {
           "mapped_fields": "City",
           "mapped_fields": "State",
           "mapped_fields": "Province", /* Province is missing from search_criteria_property. */
           "display_name": "Location",
           "result_size": "5",
           "bucket_type":"FACET_BUCKET_TYPE_VALUE"
        }
      }"

範囲ベースのファセットを含む検索構成を作成する

範囲ファセットは通常のファセットと似ていますが、各ファセット バケットは連続した範囲をカバーします。追加の構成（range_facet_config）により、これらのファセット バケット範囲に関する情報がシステムに提供されます。

範囲ファセットは、次の環境で利用できます。

  1. 整数
  2. 日付

範囲ファセットには次の 3 種類があります。

  1. 固定範囲 - 各バケットのサイズが同じです。
  2. カスタム範囲 - プログラム可能なバケット サイズ。たとえば、対数などです。
  3. 期間 - DAY、MONTH、YEAR の固定バケットの粒度。これは日付範囲ファセットにのみ適用されます。

同じ条件が単一のファセットとして適用されます。ただし、範囲指定に関する追加の検証があります。

固定範囲バケットの仕様

次の例では、フィールド inventory-count の固定範囲ファセット仕様を作成し、バケット [-inf, 0), [0, 10), [10, 20), [20, 30), [30, inf] を生成します。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

このリクエストでは、FixedRangeBucketSpec を使用して、同じ粒度の複数のバケットを作成します。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=inventory-count

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

{
  "facet_property": {
    "mapped_fields": "inventory-count",
    "display_name": "Inventory Count",
    "result_size": "5",
    "bucket_type":"FACET_BUCKET_TYPE_FIXED_RANGE",
    "fixed_range_bucket_spec": {
       "bucket_start": {
         "integer_value": 0
       },
       "bucket_granularity": {
         "integer_value": 10
       },
       "bucket_count": 5
    }
  }
}

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

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/searchConfigs?search_config_id=inventory-count"

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/searchConfigs?search_config_id=inventory-count" | Select-Object -Expand Content
 

カスタム範囲バケットの仕様

次の例では、フィールド video-views の固定範囲ファセット仕様を作成し、バケット [inf, 0), [0, 10), [10, 100), [100, 1000), [1000, 10000), [10000, inf) を生成します。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

このリクエストでは、CustomRangeBucketSpec を使用して、値をバケット化する方法を指定します。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=video-views

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

{
  "facet_property": {
    "mapped_fields": "video-views",
    "display_name": "Video Views",
    "result_size": "6",
    "bucket_type":"FACET_BUCKET_TYPE_CUSTOM_RANGE",
    "custom_range_bucket_spec": {
       "endpoints": {
         "integer_value": 0
       },
       "endpoints": {
         "integer_value": 10
       },
       "endpoints": {
         "integer_value": 100
       },
       "endpoints": {
         "integer_value": 1000
       },
       "endpoints": {
         "integer_value": 10000
       }
    }
  }
}

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

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/searchConfigs?search_config_id=video-views"

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/searchConfigs?search_config_id=video-views" | Select-Object -Expand Content
 

日付 / 時間範囲バケットの仕様

次の例では、DAY の粒度でフィールド film-date の日付範囲仕様を作成します。

REST

新しい SearchConfig ID は、リクエストのフィールドとしてではなく、リクエスト URL の末尾に指定する必要があります。

このリクエストでは、DateTimeBucketSpec を使用して、日付値をバケット化する方法を指定します。

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

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

HTTP メソッドと URL:

POST https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs?search_config_id=film-date

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

{
  "facet_property": {
    "mapped_fields": "film-date",
    "display_name": "Film Date",
    "result_size": "5",
    "bucket_type": "FACET_BUCKET_TYPE_DATETIME",
    "datetime_bucket_spec": {
       "granularity": "DAY"
    }
 }
}

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

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/searchConfigs?search_config_id=film-date"

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/searchConfigs?search_config_id=film-date" | Select-Object -Expand Content
 

これらのファセット バケットを作成したら、それらを使用してウェアハウスを検索できます。

REST

このリクエストでは、facetSelections オブジェクトを使用してファセット バケットのグループを指定します。

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

HTTP メソッドと URL:

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

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

{
   "page_size": "10",
   "facet_selections": {
     "facet_id": "inventory-count",
     "buckets": {
       "range": {
         "end" : {
           "integer_value": 0
         }
       }
     },
     "buckets": {
       "range": {
         "start" : {
           "integer_value": 20
         },
         "end" : {
           "integer_value": 30
         }
       }
     }
   },
   "facet_selections": {
     "facet_id": "video-views",
     "buckets": {
       "range": {
         "start" : {
           "integer_value": 100
         },
         "end" : {
           "integer_value": 1000
         }
       }
     }
   },
   "facet_selections": {
     "facet_id": "film-date",
     "buckets": {
       "range": {
         "start" : {
           "datetime_value": {
             "year": 2022,
             "month": 9,
             "day": 10
           }
         },
         "end" : {
           "datetime_value": {
             "year": 2022,
             "month": 9,
             "day": 11
           }
         }
       }
     }
   }
}

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

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:searchAssets"

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:searchAssets" | Select-Object -Expand Content
 

検索構成を更新する

現在の SearchConfig を更新するには、リクエストが次の要件を満たしている必要があります。

  1. Request.searchConfig.name はすでに存在している必要があります。
  2. リクエストには、空でない searchCriteriaProperty または facetProperty を少なくとも 1 つ含める必要があります。
  3. mappedFields 配列は空にすることはできず、既存のユーザー指定のアノテーション キーにマッピングする必要があります。
  4. すべての mappedFields は同じ型でなければなりません。
  5. すべての mappedFields は同じ粒度を共有する必要があります。
  6. すべての mappedFields は、同じセマンティック SearchConfig 一致オプションを共有する必要があります。

REST とコマンドライン

次のコードサンプルは、projects.locations.corpora.searchConfigs.patch メソッドを使用して、ウェアハウス検索構成リソースを更新します。

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

HTTP メソッドと URL:

PATCH https://warehouse-visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs/SEARCHCONFIG_ID

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs/SEARCHCONFIG_ID1",
  "searchCriteriaProperty": {
    "mappedFields": "dataschema2"
  }
}

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

curl

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

PowerShell

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

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/searchConfigs/SEARCHCONFIG_ID1",
  "searchCriteriaProperty": {
    "mappedFields": [
      "dataschema2"
    ]
  }
}