商品搜索功能目前处于维护模式。如需提高可扩缩性并实现与 Product Search 相同的功能，请使用 Vision Warehouse。

创建商品集并搜索商品

本快速入门演示如何创建和使用三种 Vision API Product Search 资源：一个包含一组商品的商品集以及与这些商品关联的参考图片。

在本快速入门中，您将通过批量导入的方式一步创建商品集、商品及其参考图片。

在将商品集编入索引后，您可以使用 Vision API Product Search 查询该商品集。

本快速入门将引导您逐步完成以下过程：

使用 CSV 和批量导入功能来创建商品集、商品和参考图片。
使用存储在 Cloud Storage 存储桶中的图片向 Vision API Product Search 发出请求。

准备工作

请按照以下说明设置您的项目（如果尚未设置）。

设置项目

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable vision.googleapis.com

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Replace the following:

PROJECT_ID: Your project ID.
USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
ROLE: The IAM role that you grant to your user account.

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable vision.googleapis.com

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Replace the following:

PROJECT_ID: Your project ID.
USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
ROLE: The IAM role that you grant to your user account.

设置环境变量

为了更方便地运行本快速入门中的 curl 示例，请设置以下环境变量，其中：

PROJECT_ID 是您的 Google Cloud 项目的 ID。
LOCATION_ID 是将运行您的教程的 Google Cloud 位置，例如 us-east1。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。

使用数据集

在本快速入门中，您将使用一个包含 100 个左右 apparel-v2 商品类别条目的数据集。此公开可用的数据集位于以下公共 Cloud Storage 存储桶中：

gs://cloud-samples-data/vision/product_search/product_catalog.csv

CSV 格式如下：

gs://cloud-ai-vision-data/product-search-tutorial/images/filename1.jpg,image0,product_set0,product_id0,apparel-v2,,"style=women,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename2.jpg,image1,product_set0,product_id1,apparel-v2,,"style=men,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename3.jpg,image2,product_set0,product_id2,apparel-v2,,"style=women,category=dress",

使用批量导入操作创建商品集、商品和参考图片

使用以下 curl 命令创建一个包含商品和参考图片的新商品集。此商品集名为 product_set0（在导入 CSV 中声明的值）。

首先，创建一个名为 import_request.json 的请求 JSON 文件，并将其保存到您当前的工作目录中：

import_request.json

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

创建请求 JSON 文件后，发送以下请求：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @import_request.json \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets:import

成功的响应包含一个长时间运行的操作对象：

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fa"
}

该响应还包含相关操作 ID（例如 0a0aec86192599fa），该 ID 可用于获取操作状态。

获取导入操作状态

您可以使用从导入操作返回的 operation-id 来检查批量导入操作的状态：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/locations/LOCATION_ID/operations/OPERATION_ID

成功的响应如下所示：

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fb",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2018-11-30T03:11:04.808114024Z",
    "endTime": "2018-11-30T03:11:38.624444324Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0/referenceImages/image0",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a0cbcf70ba11e89399d20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1/referenceImages/image1",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a1aea370ba11e888d4d20059124800.jpg"
      },
      ...
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id93/referenceImages/image93",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4697319970ba11e8a7bfd20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id94/referenceImages/image94",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4698596370ba11e8bf6ad20059124800.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

编制索引

商品的 Product Search 索引大约每 30 分钟更新一次。添加或删除图片后，在下次更新索引之前，此类更改不会反映在您的 Product Search 响应中。

要确保已将某产品集成功编入索引，请检查该产品集的 indexTime 字段。

列出商品集并检查索引编制情况

您可以列出所有商品集，并使用 indexTime 字段验证是否已将商品集成功编入索引：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets

如果响应成功，系统会列出您的所有商品集，包括商品集 ID（例如 product_set0）和指示索引编制完成时间的 indexTime 字段：

{
  "productSets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

列出商品

您可以使用从商品集列表返回的 PRODUCT_SET_ID 列出商品集中的所有商品：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID/products?pageSize=15

成功的响应会列出商品详细信息。

在该请求中，您使用可选查询参数 pageSize 将结果列表设置为 15 件商品。响应中的 nextPageToken 也表明还可以列出更多商品。您可以使用列出的令牌来检索更多结果。如需详细了解如何使用 pageToken，请参阅获取和列出资源。

{
  "products": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "men"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    ...
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id21",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "dress"
        }
      ]
    }
  ],
  "nextPageToken": "1LqhSgZfM_uWKOxvog"
}

使用 Vision API Product Search 搜索匹配商品

索引编制完成后，您可以搜索与示例图片匹配的商品。在本快速入门中，您将使用存储在 Google Cloud Storage 存储桶中的图片，如下图所示。

Cloud Storage 存储桶中的连衣裙图片。 — `gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg`

使用远程图片进行搜索

通过以下请求，使用存储在公共 Cloud Storage 存储桶中的图片进行搜索。

首先，创建一个名为 search_request.json 的请求 JSON 文件，并将其保存到您当前的工作目录中。更改请求 JSON 中的以下值，以与您的项目信息相匹配：

PROJECT_ID
LOCATION_ID
PRODUCT_SET_ID

search_request.json

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg"
        }
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH"
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID",
          "productCategories": [
            "apparel-v2"
          ],
          "filter": "style=womens OR style=women"
        }
      }
    }
  ]
}

创建请求 JSON 文件后，发送以下请求：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @search_request.json \
    https://vision.googleapis.com/v1/images:annotate

成功的请求会返回由商品 ID 表示的匹配商品的列表。如果一张图片包含多件商品，则显示的结果会按由边界框标识的各件商品进一步细分。

如需查看有关检测单件商品以及检测图片中多件商品的示例，请参阅了解搜索响应和多件商品检测。

此外，还会返回 score 字段。此字段表示该服务确定商品与所提供图片相匹配的置信度，其范围介于 0（零置信度）到 1（最高置信度）之间。

indexTime 字段显示正在搜索的索引版本。在此之后对图片进行的更改不会反映在这些结果中。

响应

{
  "responses": [
    {
      "productSearchResults": {
        "indexTime": "2020-01-07T18:33:45.300851144Z",
        "results": [
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 1,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
          },
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.27578148,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29/referenceImages/image29"
          },
          ...
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                },
                {
                  "key": "kids",
                  "value": "true"
                }
              ]
            },
            "score": 0.20356013,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22/referenceImages/image22"
          }
        ],
        "productGroupedResults": [
          {
            "boundingPoly": {
              "normalizedVertices": [
                {
                  "x": 0.25542393,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.92001766
                },
                {
                  "x": 0.25542393,
                  "y": 0.92001766
                }
              ]
            },
            "results": [
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 1,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
              },
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.27369013,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57/referenceImages/image57"
              },
              ...
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.21221256,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18/referenceImages/image18"
              }
            ],
            "objectAnnotations": [
              {
                "mid": "/m/01d40f",
                "name": "Dress",
                "score": 0.968603
              }
            ]
          }
        ]
      }
    }
  ]
}

恭喜！您已向 Vision API Product Search 服务发送了第一个 images.annotate 请求。

清理

Optional: Revoke credentials from the gcloud CLI.
```
gcloud auth revoke
```
注意：删除项目会产生以下影响：
- 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
- 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。
如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。
Delete a Google Cloud project:
```
gcloud projects delete PROJECT_ID
```

后续步骤

借助 Vision API Product Search 客户端库，以您偏好的语言开始使用 Vision API Product Search。
浏览方法指南。
浏览教程。