使用指令列搜尋串流影片倉庫資料

建立 Vision 倉儲、新增至應用程式並部署應用程式後，即可搜尋儲存在串流影片倉儲中的資料。

搜尋串流影片中繼資料

如要在倉儲 (corpus) 中搜尋資料 (assets)，請在 SearchAssetsRequest 中填入要尋找的內容。這類內容有幾種不同格式：

  1. criteria - 使用者提供的文字、數字或日期內容。
  2. facet_selections - 伺服器傳回的文字內容，由使用者選取。
  3. content_time_ranges - 所有傳回內容必須符合的日期範圍。

在下列範例中，假設 Warehouse 包含全國各地不同類型商店的監視器影像。如要擷取 2018 年或 2020 年所有標示 "state": "California" 或 "state":"Pennsylvania" 註解的資產，請傳送下列要求：

REST

如要搜尋資產，請使用 projects.locations.corpora.searchAssets 方法傳送 POST 要求。

在這個範例主體中，criteria 欄位會使用 textArray 值提供兩個 txt_values：「加州」和「賓州」。您也可以提供其他資料類型的搜尋條件。每項要求只能指定一種搜尋條件。

其他搜尋條件選項

整數範圍 (含頭尾)

    "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"
    }

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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 陣列會顯示與原始查詢相符的內容。 上述回應指出，其中一台安全攝影機位於體育用品店，另一台則位於雜貨店。

如要限制這項查詢只顯示雜貨店的影像，請傳回相同的要求，並加入Facet 選項。

包含構面選取項目的 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" 註解。

在搜尋時傳回剪輯片段資產中繼資料

此外，使用者也可以使用 result_annotation_keys，指定要連同搜尋結果傳回的額外片段中繼資料。

REST

在本範例中，使用者在要求主體中提供註解鍵 "camera-location"，而回應中則提供該鍵的值 ("Sunnyvale")。

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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"
    }
  }
}

系統會使用串流影片擷取或 CreateAnnotation 要求，將 "image-classification" 的部分註解擷取至語料庫。

註解擷取完畢後，您就可以搜尋 "image-classification"，並取得影片結果和對應的註解：

REST

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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 的使用案例有許多種，每種案例都有不同的規範，請務必遵守。

使用自訂搜尋條件建立搜尋設定

本節說明如何將自訂運算子對應至一或多個使用者提供的註解鍵。在這種情況下，您必須在建構要求時遵守一般規範。

REST

您必須在要求網址結尾指定新的 SearchConfig ID，而非做為要求中的欄位。

本範例中，使用者提供的註解鍵為 "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 方法和網址：

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，而非做為要求中的欄位。

在本範例中，要求會成功，因為要求網址中的 search_config_id (Location) 參照現有的使用者指定註解鍵，且 mapped_fields 包含一個值等於 search_config_id (Location) 的元素。

使用任何要求資料之前，請先替換以下項目：

  • 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 方法和網址：

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 或更多側邊欄對應

如要建立自訂 Facet 值與一或多個使用者提供的註解鍵之間的對應，用戶端必須確保：

  1. Request.search_configuration 必須包含 SearchCriteriaProperty，以致於 Request.search_configuration.search_criteria_property.mapped_fields 包含的元素與 Request.search_configuration.facet_property.mapped_fields 相同。

REST

您必須在要求網址結尾指定新的 SearchConfig ID，而非做為要求中的欄位。

以下範例說明如何為使用者提供的註解鍵 "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 方法和網址：

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) 可提供系統這些層面值區範圍的相關資訊。

範圍 facet 適用於：

  1. 整數
  2. 日期

範圍層面有三種類型：

  1. 固定範圍 - 每個值區的大小相同。
  2. 自訂範圍 - 可程式化的特徵分塊大小。例如對數。
  3. 日期範圍 - 固定值區細微程度為 DAY、MONTH 和 YEAR。這只適用於日期範圍層面。

與單一層面相同，適用相同的條件，但範圍規格須通過額外驗證。

固定範圍 bucket 規格

以下範例會為 inventory-count 欄位建立固定範圍的 facet 規格，並產生以下 bucket：[-inf, 0), [0, 10), [10, 20), [20, 30), [30, inf]。

REST

您必須在要求網址結尾指定新的 SearchConfig ID，而非做為要求中的欄位。

這項要求使用 FixedRangeBucketSpec 建立多個粒度相同的 bucket。

使用任何要求資料之前，請先替換以下項目：

  • 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 方法和網址：

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
 

自訂範圍 bucket 規格

以下範例會為 video-views 欄位建立固定範圍的 facet 規格，並產生以下 bucket：[inf, 0), [0, 10), [10, 100), [100, 1000), [1000, 10000), [10000, inf)。

REST

您必須在要求網址結尾指定新的 SearchConfig ID，而非做為要求中的欄位。

這項要求使用 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 方法和網址：

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
 

日期 / 時間範圍 bucket 規格

以下範例會建立欄位 film-date 的日期範圍規格，並採用 DAY 粒度。

REST

您必須在要求網址結尾指定新的 SearchConfig ID，而非做為要求中的欄位。

這項要求會使用 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 方法和網址：

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 物件指定一組側欄篩選條件值區間。

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT_NUMBER：您的 Google Cloud專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。

HTTP 方法和網址：

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。
  3. mappedFields 陣列不得為空白，且必須對應至現有的使用者指定註解鍵。
  4. 所有 mappedFields 都必須屬於相同類型。
  5. 所有 mappedFields 都必須共用相同的精細程度。
  6. 所有 mappedFields 都必須共用相同的語意 SearchConfig 比對選項。

REST 和指令列

下列程式碼範例會使用 projects.locations.corpora.searchConfigs.patch 方法，更新倉庫搜尋設定資源。

使用任何要求資料之前，請先替換以下項目：

  • REGIONALIZED_ENDPOINT：端點可能包含與 LOCATION_ID 相符的前置字串，例如 europe-west4-。進一步瞭解 地區化端點。
  • PROJECT：您的 Google Cloud 專案 ID 或專案編號。
  • LOCATION_ID：您使用 Vertex AI Vision 的區域。例如：us-central1、europe-west4。請參閱可用區域。
  • CORPUS_ID：目標語料庫的 ID。
  • SEARCHCONFIG_ID：目標 SearchConfig 的 ID。
  • "mappedFields"：一或多個現有的使用者提供的註解鍵。

HTTP 方法和網址：

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"
    ]
  }
}