使用命令行搜索在线视频仓库数据

创建 Vision Warehouse、将其添加到应用并部署应用后，您就可以搜索存储在流式视频仓库中的数据了。

搜索流式视频元数据

如需在数据仓库 (corpus) 中搜索数据 (assets)，请在 SearchAssetsRequest 中填充您要查找的内容。此类内容有多种不同的格式：

  1. criteria - 用户提供的文本、数字或日期内容。
  2. facet_selections - 服务器返回并由用户选择的文本内容。
  3. content_time_ranges - 所有返回的内容必须位于的日期范围。

在以下示例中，假设某个仓库包含来自全国各地不同类型商店的监控摄像头拍摄的视频。如需检索 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 数组显示与原始查询匹配的内容。 上述响应表明，其中一个安全摄像头位于体育用品商店，而另一个位于杂货店。

如需限制此查询，使其仅显示杂货店的视频片段，请传回包含构面选择的相同请求。

包含分面选择的 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") 在响应中提供。

在使用任何请求数据之前，请先进行以下替换：

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

"image-classification" 的某些注释通过流式视频提取或 CreateAnnotation 请求提取到语料库中。

在系统提取注释后，您可以搜索 "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 视频理解模型 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 或更多方面映射的搜索配置

希望在自定义分面值与一个或多个用户提供的注解键之间创建映射的客户端必须确保：

  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) 可为系统提供有关这些分面区间的信息。

范围分面适用于以下情况：

  1. 整数
  2. 日期

范围型分面有三种类型：

  1. 固定范围 - 每个区段的大小相同。
  2. 自定义范围 - 可编程的分桶大小。例如，对数。
  3. 日期范围 - 固定时间段的粒度为 DAY、MONTH 和 YEAR。这仅适用于日期范围分面。

与单数型分面一样，也适用相同的条件，但范围规范方面有一些额外的验证。

固定范围分桶规范

以下示例会为字段 inventory-count 创建一个固定范围的分面规范，并生成以下分桶：[-inf, 0), [0, 10), [10, 20), [20, 30), [30, inf]。

REST

您必须在请求网址末尾指定新的 SearchConfig ID，而不能将其作为请求中的字段来指定。

此请求使用 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 方法和网址：

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，而不能将其作为请求中的字段来指定。

此请求使用 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
 

日期 / 时间范围分桶规范

以下示例会为字段 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"
    ]
  }
}