Product Search 教程

本教程介绍如何创建包含一组商品及其参考图片的商品集，本教程向用户介绍如何通过在线（逐一）导入的方式创建商品集。在将商品集编入索引后，您可以使用 Vision API Product Search 查询该商品集。

在本教程中，您将学习如何完成以下操作：

通过在线（逐一）导入的方式创建商品集
创建单件商品
将商品添加到商品集
更新商品
创建参考图片
搜索类似商品

准备工作

在开始本教程之前，请确保您已安装了相应的客户端库，已为项目启用结算和 API，并且已正确设置身份验证。

导入库

如要使用 Vision API Product Search，请在下载并安装客户端库后导入以下模块：

Go

如需了解如何安装和使用 Vision API Product Search 客户端库，请参阅 Vision API Product Search 客户端库。如需了解详情，请参阅 Vision API Product Search Go API 参考文档。

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

Java

如需了解如何安装和使用 Vision API Product Search 客户端库，请参阅 Vision API Product Search 客户端库。如需了解详情，请参阅 Vision API Product Search Java API 参考文档。

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.vision.v1.BatchOperationMetadata;
import com.google.cloud.vision.v1.ImportProductSetsGcsSource;
import com.google.cloud.vision.v1.ImportProductSetsGcsSource.Builder;
import com.google.cloud.vision.v1.ImportProductSetsInputConfig;
import com.google.cloud.vision.v1.ImportProductSetsResponse;
import com.google.cloud.vision.v1.LocationName;
import com.google.cloud.vision.v1.ProductSearchClient;
import com.google.cloud.vision.v1.ReferenceImage;
import java.io.PrintStream;
import javax.swing.JPanel;
import net.sourceforge.argparse4j.ArgumentParsers;
import net.sourceforge.argparse4j.inf.ArgumentParser;
import net.sourceforge.argparse4j.inf.ArgumentParserException;
import net.sourceforge.argparse4j.inf.Namespace;
import net.sourceforge.argparse4j.inf.Subparser;
import net.sourceforge.argparse4j.inf.Subparsers;

Node.js

如需了解如何安装和使用 Vision API Product Search 客户端库，请参阅 Vision API Product Search 客户端库。如需了解详情，请参阅 Vision API Product Search Node.js API 参考文档。

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

const vision = require('@google-cloud/vision');

Python

如需了解如何安装和使用 Vision API Product Search 客户端库，请参阅 Vision API Product Search 客户端库。如需了解详情，请参阅 Vision API Product Search Python API 参考文档。

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

运行应用

第 1 步：创建商品目录

用户可以通过两种方式创建商品目录：即使用 CSV 文件执行批量导入或使用在线导入；前一种方法可以在一次 API 调用中导入整个商品目录，后一种方法可让您控制商品集并允许一次管理一种资源或关系。这主要意味着，您可以逐一创建商品集、商品和参考图片。利用在线导入功能，您还可以逐步更新已通过批量导入创建的商品目录。

在本教程中，您将使用在线导入功能。如需获取有关使用 CSV 进行批量导入的示例，请参阅快速入门。

在线（逐一）导入

1. 创建商品集

创建一个空商品集（用于容纳一组商品的简单容器）。

请求

使用 create_product_set() 方法执行以下请求，以创建一个空商品集并将其命名为“PS_CLOTH-SHOE_070318”。以参数形式传递商品集 ID 和显示名。

REST

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
DISPLAY_NAME：您选择的字符串显示名。

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets

请求 JSON 正文：

{
  "displayName": "display-name"
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets" | Select-Object -Expand Content

如果请求成功，服务器将返回一个 200 OK HTTP 状态代码以及 JSON 格式的响应。

您应该会看到类似如下所示的输出。可以使用商品集 ID（本例中为 b6d809615b6dd675）对商品集执行其他操作。

{
  "name": "projects/project-id/locations/location-id/productSets/b6d809615b6dd675",
  "displayName": "new-product-set"
}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// createProductSet creates a product set.
func createProductSet(w io.Writer, projectID string, location string, productSetID string, productSetDisplayName string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.CreateProductSetRequest{
		Parent:       fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		ProductSetId: productSetID,
		ProductSet: &visionpb.ProductSet{
			DisplayName: productSetDisplayName,
		},
	}

	resp, err := c.CreateProductSet(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateProductSet: %w", err)
	}

	fmt.Fprintf(w, "Product set name: %s\n", resp.Name)

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * Create a product set
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productSetId - Id of the product set.
 * @param productSetDisplayName - Display name of the product set.
 * @throws IOException - on I/O errors.
 */
public static void createProductSet(
    String projectId, String computeRegion, String productSetId, String productSetDisplayName)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // A resource that represents Google Cloud Platform location.
    String formattedParent = LocationName.format(projectId, computeRegion);

    // Create a product set with the product set specification in the region.
    ProductSet myProductSet =
        ProductSet.newBuilder().setDisplayName(productSetDisplayName).build();
    CreateProductSetRequest request =
        CreateProductSetRequest.newBuilder()
            .setParent(formattedParent)
            .setProductSet(myProductSet)
            .setProductSetId(productSetId)
            .build();
    ProductSet productSet = client.createProductSet(request);
    // Display the product set information
    System.out.println(String.format("Product set name: %s", productSet.getName()));
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ProductSearchClient();

async function createProductSet() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productSetId = 'Id of the product set';
  // const productSetDisplayName = 'Display name of the product set';

  // Resource path that represents Google Cloud Platform location.
  const locationPath = client.locationPath(projectId, location);

  const productSet = {
    displayName: productSetDisplayName,
  };

  const request = {
    parent: locationPath,
    productSet: productSet,
    productSetId: productSetId,
  };

  const [createdProductSet] = await client.createProductSet(request);
  console.log(`Product Set name: ${createdProductSet.name}`);
}
createProductSet();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision

def create_product_set(project_id, location, product_set_id, product_set_display_name):
    """Create a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_set_id: Id of the product set.
        product_set_display_name: Display name of the product set.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = f"projects/{project_id}/locations/{location}"

    # Create a product set with the product set specification in the region.
    product_set = vision.ProductSet(display_name=product_set_display_name)

    # The response is the product set with `name` populated.
    response = client.create_product_set(
        parent=location_path, product_set=product_set, product_set_id=product_set_id
    )

    # Display the product set information.
    print(f"Product set name: {response.name}")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

响应

Product set name: projects/prj-prod-search-tutorials/locations/us-east1/productSets/PS_CLOTH-SHOE_070318
Product set id: PS_CLOTH-SHOE_070318
Product set display name: CLOTH-SHOE

2. 创建商品

创建商品集后，接下来需要创建商品。执行以下请求来创建商品。

REST

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
DISPLAY_NAME：您选择的字符串显示名。
PRODUCT_DESCRIPTION：您选择的字符串说明。
product-category：有效的商品类别。目前提供了以下商品类别：homegoods-v2、apparel-v2、toys-v2、packagedgoods-v1 和 general-v1。
productLabels：与商品关联的一个或多个键值对。每个 KEY_STRING 必须具有一个关联的 VALUE_STRING。

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products

请求 JSON 正文：

{
  "displayName": "display-name",
  "description": "product-description",
  "productCategory": "product-category",
  "productLabels": [
      {
        "key": "key-string",
        "value": "value-string"
      }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.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 @request.json \
     "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products" | Select-Object -Expand Content

请求正文示例：

{
  "displayName": "sample-product-1234",
  "description": "Athletic shorts",
  "productCategory": "apparel-v2",
  "productLabels": [
      {
        "key": "style",
        "value": "womens"
      },
      {
        "key": "color",
        "value": "blue"
      }
  ]
}

如果请求成功，服务器将返回一个 200 OK HTTP 状态代码以及 JSON 格式的响应。

您应该会看到类似如下所示的输出。可以使用商品 ID（本例中为 37b9811d308c4e42）对商品执行其他操作。

{
  "name": "projects/project-id/locations/location-id/products/37b9811d308c4e42",
  "displayName": "sample-product-456",
  "description": "Athletic shorts",
  "productCategory": "apparel-v2",
  "productLabels": [
    {
      "key": "style",
      "value": "womens"
    },
    {
      "key": "color",
      "value": "blue"
    }
  ]
}

使用指定的 `productId` 创建商品

创建商品资源时，您可以选择在请求中提供特定商品 ID。

此信息会以查询的形式传递到请求网址 (?productId=product-id)。

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
PRODUCT_ID：与参考图片关联的商品的 ID。此 ID 由用户在创建商品时随机设置或指定。
DISPLAY_NAME：您选择的字符串显示名。
PRODUCT_DESCRIPTION：您选择的字符串说明。
product-category：有效的商品类别。目前提供了以下商品类别：homegoods-v2、apparel-v2、toys-v2、packagedgoods-v1 和 general-v1。
productLabels：与商品关联的一个或多个键值对。每个 KEY_STRING 必须具有一个关联的 VALUE_STRING。

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products?productId=product-id

请求 JSON 正文：

{
  "displayName": "display-name",
  "description": "product-description",
  "productCategory": "product-category",
  "productLabels": [
      {
        "key": "key-string",
        "value": "value-string"
      }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.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 @request.json \
     "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products?productId=product-id"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products?productId=product-id" | Select-Object -Expand Content

请求网址和正文示例：

https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products?productId=product-id-456

{
  "displayName": "sample-product-456",
  "description": "Athletic shorts",
  "productCategory": "apparel-v2",
  "productLabels": [
      {
        "key": "style",
        "value": "womens"
      },
      {
        "key": "color",
        "value": "blue"
      }
  ]
}

如果请求成功，服务器将返回一个 200 OK HTTP 状态代码以及 JSON 格式的响应。

您应该会看到类似如下所示的输出。可以使用所设置的商品 ID（本例中为 product-id-456）对商品执行其他操作。

{
  "name": "projects/project-id/locations/location-id/products/product-id-456",
  "displayName": "sample-product-456",
  "description": "Athletic shorts",
  "productCategory": "apparel-v2",
  "productLabels": [
    {
      "key": "style",
      "value": "womens"
    },
    {
      "key": "color",
      "value": "blue"
    }
  ]
}

如果您发送带有已经存在的商品 ID 的请求，则会产生以下错误：

{
  "error": {
    "code": 409,
    "message": "Product with ID 'product-id' already exists.",
    "status": "ALREADY_EXISTS",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::already_exists: Product with ID 'product-id' already exists. [google.rpc.error_details_ext] { message: \"Product with ID \\'product-id\\' already exists.\" }"
      }
    ]
  }
}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// createProduct creates a product.
func createProduct(w io.Writer, projectID string, location string, productID string, productDisplayName string, productCategory string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.CreateProductRequest{
		Parent:    fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		ProductId: productID,
		Product: &visionpb.Product{
			DisplayName:     productDisplayName,
			ProductCategory: productCategory,
		},
	}

	resp, err := c.CreateProduct(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateProduct: %w", err)
	}

	fmt.Fprintf(w, "Product name: %s\n", resp.Name)

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * Create one product.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param productDisplayName - Display name of the product.
 * @param productCategory - Category of the product.
 * @throws IOException - on I/O errors.
 */
public static void createProduct(
    String projectId,
    String computeRegion,
    String productId,
    String productDisplayName,
    String productCategory)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // A resource that represents Google Cloud Platform location.
    String formattedParent = LocationName.format(projectId, computeRegion);
    // Create a product with the product specification in the region.
    // Multiple labels are also supported.
    Product myProduct =
        Product.newBuilder()
            .setName(productId)
            .setDisplayName(productDisplayName)
            .setProductCategory(productCategory)
            .build();
    Product product = client.createProduct(formattedParent, myProduct, productId);
    // Display the product information
    System.out.println(String.format("Product name: %s", product.getName()));
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ProductSearchClient();
async function createProduct() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const productDisplayName = 'Display name of the product';
  // const productCategory = 'Catoegory of the product';

  // Resource path that represents Google Cloud Platform location.
  const locationPath = client.locationPath(projectId, location);

  const product = {
    displayName: productDisplayName,
    productCategory: productCategory,
  };

  const request = {
    parent: locationPath,
    product: product,
    productId: productId,
  };

  const [createdProduct] = await client.createProduct(request);
  console.log(`Product name: ${createdProduct.name}`);
}
createProduct();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision
from google.protobuf import field_mask_pb2 as field_mask

def create_product(
    project_id, location, product_id, product_display_name, product_category
):
    """Create one product.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        product_display_name: Display name of the product.
        product_category: Category of the product.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = f"projects/{project_id}/locations/{location}"

    # Create a product with the product specification in the region.
    # Set product display name and product category.
    product = vision.Product(
        display_name=product_display_name, product_category=product_category
    )

    # The response is the product with the `name` field populated.
    response = client.create_product(
        parent=location_path, product=product, product_id=product_id
    )

    # Display the product information.
    print(f"Product name: {response.name}")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

响应

Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318
Product id: P_CLOTH-SHOE_46903668_070318
Product display name: Blue Dress
Product category: apparel
Product description: Short sleeved and 1950s style satin dress
Product labels:
  Product label 1:
        key: style
        value: women
  Product label 2:
        key: category
        value: dress
  Product label 3:
        key: color
        value: dark-blue

3. 将商品添加到商品集

创建商品集和商品后，您可以将商品添加到商品集中。

REST

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
PRODUCT_SET_ID：您要对其执行操作的商品集的 ID。
PRODUCT_NAME：商品的完整资源名称。格式如下：
- projects/PROJECT_ID/locations/LOCATION_ID/products/PRODUCT_ID

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct

请求 JSON 正文：

{
  "product": "product-name"
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.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 @request.json \
     "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// addProductToProductSet adds a product to a product set.
func addProductToProductSet(w io.Writer, projectID string, location string, productID string, productSetID string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.AddProductToProductSetRequest{
		Name:    fmt.Sprintf("projects/%s/locations/%s/productSets/%s", projectID, location, productSetID),
		Product: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
	}

	if err = c.AddProductToProductSet(ctx, req); err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}

	fmt.Fprintf(w, "Product added to product set.\n")

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


/**
 * Add a product to a product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param productSetId - Id of the product set.
 * @throws IOException - on I/O errors.
 */
public static void addProductToProductSet(
    String projectId, String computeRegion, String productId, String productSetId)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product set.
    String formattedName = ProductSetName.format(projectId, computeRegion, productSetId);

    // Get the full path of the product.
    String productPath = ProductName.of(projectId, computeRegion, productId).toString();

    // Add the product to the product set.
    client.addProductToProductSet(formattedName, productPath);

    System.out.println(String.format("Product added to product set."));
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

const vision = require('@google-cloud/vision');
const client = new vision.ProductSearchClient();

async function addProductToProductSet() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const productSetId = 'Id of the product set';

  const productPath = client.productPath(projectId, location, productId);
  const productSetPath = client.productSetPath(
    projectId,
    location,
    productSetId
  );

  const request = {
    name: productSetPath,
    product: productPath,
  };

  await client.addProductToProductSet(request);
  console.log('Product added to product set.');
}
addProductToProductSet();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision

def add_product_to_product_set(project_id, location, product_id, product_set_id):
    """Add a product to a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        product_set_id: Id of the product set.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product set.
    product_set_path = client.product_set_path(
        project=project_id, location=location, product_set=product_set_id
    )

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id
    )

    # Add the product to the product set.
    client.add_product_to_product_set(name=product_set_path, product=product_path)
    print("Product added to product set.")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

响应

Product added to product set.

4. 更新商品

如果您需要在创建商品或商品集后对其进行更新，则可以使用我们的更新方法。此示例展示了商品更新，其中标签有所更改：

命令行

发送 PATCH 请求时，所有先前的字段及其值都将被清空，但 productCategory 字段除外，它是不可变的。发出 PATCH 更新请求后，发送您所需的包含值的所有字段。

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
PRODUCT_ID：与参考图片关联的商品的 ID。此 ID 由用户在创建商品时随机设置或指定。
display-name：您选择的字符串显示名。它可以与之前的显示名或更新后的值相同。
description：您选择的字符串说明。它可以与之前的显示名或更新后的值相同。如果您不需要 description 字段和值，请忽略。
productLabels：与商品关联的一个或多个键值对。每个 KEY_STRING 必须具有一个关联的 VALUE_STRING。

HTTP 方法和网址：

PATCH https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id

请求 JSON 正文：

{
  "displayName": "display-name",
  "description": "description",
  "productLabels": [
    {
      "key": "key-string",
      "value": "value-string"
    },
    {
      "key": "key-string",
      "value": "value-string"
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/project-id/locations/location-id/products/product-id",
  "displayName": "display-name",
  "description": "description",
  "productCategory": "apparel-v2",
  "productLabels": [
    {
      "key": "style",
      "value": "womens"
    },
    {
      "key": "onSale",
      "value": "true"
    }
  ]
}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
	field_mask "google.golang.org/genproto/protobuf/field_mask"
)

// updateProductLabels updates product labels of a product.
func updateProductLabels(w io.Writer, projectID string, location string, productID string, key string, value string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.UpdateProductRequest{
		UpdateMask: &field_mask.FieldMask{
			Paths: []string{
				"product_labels",
			},
		},
		Product: &visionpb.Product{
			Name: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
			ProductLabels: []*visionpb.Product_KeyValue{
				{
					Key:   key,
					Value: value,
				},
			},
		},
	}

	resp, err := c.UpdateProduct(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdateProduct: %w", err)
	}

	fmt.Fprintf(w, "Product name: %s\n", resp.Name)
	fmt.Fprintf(w, "Updated product labels: %s\n", resp.ProductLabels)

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * Update the product labels.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId -Id of the product.
 * @param productLabels - Labels of the product.
 * @throws IOException - on I/O errors.
 */
public static void updateProductLabels(
    String projectId, String computeRegion, String productId, String productLabels)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product.
    String formattedName = ProductName.format(projectId, computeRegion, productId);

    // Set product name, product labels and product display name.
    // Multiple labels are also supported.
    Product product =
        Product.newBuilder()
            .setName(formattedName)
            .addProductLabels(
                KeyValue.newBuilder()
                    .setKey(productLabels.split(",")[0].split("=")[0])
                    .setValue(productLabels.split(",")[0].split("=")[1])
                    .build())
            .build();

    // Set product update field name.
    FieldMask updateMask = FieldMask.newBuilder().addPaths("product_labels").build();

    // Update the product.
    Product updatedProduct = client.updateProduct(product, updateMask);
    // Display the product information
    System.out.println(String.format("Product name: %s", updatedProduct.getName()));
    System.out.println(String.format("Updated product labels: "));
    for (Product.KeyValue element : updatedProduct.getProductLabelsList()) {
      System.out.println(String.format("%s: %s", element.getKey(), element.getValue()));
    }
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ProductSearchClient();

async function updateProductLabels() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const key = 'The key of the label';
  // const value = 'The value of the label';

  // Resource path that represents full path to the product.
  const productPath = client.productPath(projectId, location, productId);

  const product = {
    name: productPath,
    productLabels: [
      {
        key: key,
        value: value,
      },
    ],
  };

  const updateMask = {
    paths: ['product_labels'],
  };

  const request = {
    product: product,
    updateMask: updateMask,
  };

  const [updatedProduct] = await client.updateProduct(request);
  console.log(`Product name: ${updatedProduct.name}`);
  console.log(`Product display name: ${updatedProduct.displayName}`);
  console.log(`Product description: ${updatedProduct.description}`);
  console.log(`Product category: ${updatedProduct.productCategory}`);
  console.log(
    `Product Labels: ${updatedProduct.productLabels[0].key}: ${updatedProduct.productLabels[0].value}`
  );
}
updateProductLabels();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision
from google.protobuf import field_mask_pb2 as field_mask

def update_product_labels(project_id, location, product_id, key, value):
    """Update the product labels.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        key: The key of the label.
        value: The value of the label.
    """
    client = vision.ProductSearchClient()

    # Get the name of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id
    )

    # Set product name, product label and product display name.
    # Multiple labels are also supported.
    key_value = vision.Product.KeyValue(key=key, value=value)
    product = vision.Product(name=product_path, product_labels=[key_value])

    # Updating only the product_labels field here.
    update_mask = field_mask.FieldMask(paths=["product_labels"])

    # This overwrites the product_labels.
    updated_product = client.update_product(product=product, update_mask=update_mask)

    # Display the updated product information.
    print(f"Product name: {updated_product.name}")
    print(f"Updated product labels: {product.product_labels}")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

响应

Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318
Product id: P_CLOTH-SHOE_46903668_070318
Product display name: Blue Dress
Updated product labels:
  Product label 1:
        key: style
        value: women
  Product label 2:
        key: category
        value: dress
  Product label 3:
        key: color
        value: blue
Product description: Short sleeved and 1950s style satin dress

5. 创建商品的参考图片

为单件商品创建参考图片后，如果该商品已编入索引，Vision API Product Search 便可按图片搜索商品。您可以为一件商品创建多个参考图片，尤其是在希望获得更精确的匹配项时。

您可以随时为商品添加新的参考图片。

创建参考图片时，您可以选择添加边界多边形坐标。边界多边形用于标识感兴趣的参考图片区域。例如，如果为夹克商品创建了参考图片，那么您可以在边界多边形参数中提供夹克的坐标，这样，系统在查找商品匹配项时便只会考虑夹克商品。注意：您可以在索引时提供多个边界多边形，但在查询时，该 API 仅支持一个边界多边形。

获取图片的边界多边形坐标的快捷方式是使用 Vision API 对象本地化功能。如需详细了解对象本地化，请参阅检测多个对象。

REST

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

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
PRODUCT_ID：与参考图片关联的商品的 ID。此 ID 由用户在创建商品时随机设置或指定。
CLOUD_STORAGE_IMAGE_URI：Cloud Storage 存储桶中有效图片文件的路径。您必须至少拥有该文件的读取权限。示例：
- ```
gs://storage-bucket/filename.jpg
```

注意：boundingPolys 字段为可选字段。如果您未指定边界框，Cloud Vision API 将尝试推断图片中与父级商品上的 productCategory 匹配的目标区域。

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages

请求 JSON 正文：

{
  "uri": "cloud-storage-image-uri",
  "boundingPolys": [
    {
      "vertices": [
        {
          "x": X_MIN,
          "y": Y_MIN
        },
        {
          "x": X_MAX,
          "y": Y_MIN
        },
        {
          "x": X_MAX,
          "y": Y_MAX
        },
        {
          "x": X_MIN,
          "y": Y_MAX
        }
      ]
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.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 @request.json \
     "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages" | Select-Object -Expand Content

如果请求成功，服务器将返回一个 200 OK HTTP 状态代码以及 JSON 格式的响应。

您应该会看到类似如下所示的输出。示例请求在图片中指定了单个 boundingPoly。边界框的顶点未归一化；顶点值是实际像素值，与原始图片无关，且范围为 0 - 1。这些顶点具有以下值：[(33,22),(282,22),(282,278),(33,278)]。


{
  "name": "projects/project-id/locations/location-id/products/product-id/referenceImages/image-id",
  "uri": "gs://storage-bucket/filename.jpg",
  "boundingPolys": [
    {
      "vertices": [
        {
          "x": 33,
          "y": 22
        },
        {
          "x": 282,
          "y": 22
        },
        {
          "x": 282,
          "y": 278
        },
        {
          "x": 33,
          "y": 278
        }
      ]
    }
  ]
}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// createReferenceImage creates a reference image for a product.
func createReferenceImage(w io.Writer, projectID string, location string, productID string, referenceImageID string, gcsURI string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.CreateReferenceImageRequest{
		Parent: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
		ReferenceImage: &visionpb.ReferenceImage{
			Uri: gcsURI,
		},
		ReferenceImageId: referenceImageID,
	}

	resp, err := c.CreateReferenceImage(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateReferenceImage: %w", err)
	}

	fmt.Fprintf(w, "Reference image name: %s\n", resp.Name)
	fmt.Fprintf(w, "Reference image uri: %s\n", resp.Uri)

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * Create a reference image.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param referenceImageId - Id of the image.
 * @param gcsUri - Google Cloud Storage path of the input image.
 * @throws IOException - on I/O errors.
 */
public static void createReferenceImage(
    String projectId,
    String computeRegion,
    String productId,
    String referenceImageId,
    String gcsUri)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product.
    String formattedParent = ProductName.format(projectId, computeRegion, productId);
    // Create a reference image.
    ReferenceImage referenceImage = ReferenceImage.newBuilder().setUri(gcsUri).build();

    ReferenceImage image =
        client.createReferenceImage(formattedParent, referenceImage, referenceImageId);
    // Display the reference image information.
    System.out.println(String.format("Reference image name: %s", image.getName()));
    System.out.println(String.format("Reference image uri: %s", image.getUri()));
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

const vision = require('@google-cloud/vision');

const client = new vision.ProductSearchClient();

async function createReferenceImage() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const referenceImageId = 'Id of the reference image';
  // const gcsUri = 'Google Cloud Storage path of the input image';

  const formattedParent = client.productPath(projectId, location, productId);

  const referenceImage = {
    uri: gcsUri,
  };

  const request = {
    parent: formattedParent,
    referenceImage: referenceImage,
    referenceImageId: referenceImageId,
  };

  const [response] = await client.createReferenceImage(request);
  console.log(`response.name: ${response.name}`);
  console.log(`response.uri: ${response.uri}`);
}
createReferenceImage();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision

def create_reference_image(
    project_id, location, product_id, reference_image_id, gcs_uri
):
    """Create a reference image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        reference_image_id: Id of the reference image.
        gcs_uri: Google Cloud Storage path of the input image.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id
    )

    # Create a reference image.
    reference_image = vision.ReferenceImage(uri=gcs_uri)

    # The response is the reference image with `name` populated.
    image = client.create_reference_image(
        parent=product_path,
        reference_image=reference_image,
        reference_image_id=reference_image_id,
    )

    # Display the reference image information.
    print(f"Reference image name: {image.name}")
    print(f"Reference image uri: {image.uri}")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

响应

Reference image name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318/referenceImages/I_469a896b70ba11e8be97d20059124800_070418
Reference image id: I_469a896b70ba11e8be97d20059124800_070418
Reference image uri: gs://product-search-tutorial/dress-shoe-dataset/469a896b70ba11e8be97d20059124800.jpg
Reference image bounding polygons:
vertices {
  x: 80
  y: 50
}
vertices {
  x: 80
  y: 660
}
vertices {
  x: 300
  y: 50
}
vertices {
  x: 430
  y: 660
}

第 2 步：搜索匹配商品

在此界面中，您可以通过将新图片作为输入并搜索最匹配的商品来查询所创建的商品目录。

与创建参考图片类似，在搜索匹配图片时，您可以选择添加边界多边形坐标。边界多边形用于标识要查找其匹配项的来源图片中的感兴趣区域。例如，如果您的来源图片同时包含服装和钱包，而您只想查找服装匹配项，那么您可以标识仅包含服装的图片区域的边界多边形坐标。默认情况下，如果未指定边界多边形，则该 API 会确定最大的边界多边形并自动进行查询。

获取图片的边界多边形坐标的快捷方式是使用 Vision API 对象本地化功能。如需详细了解对象本地化，请参阅检测多个对象。例如，若要明确查询完整图片，指定整个图片框的边界多边形即可：[(0, 0), (0, 1), (1, 1), (1, 0)]。

该请求会返回 API 响应，其中包含与图片最匹配的商品以及得分和匹配图片。该图片是以最高置信度值返回的。

REST

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

BASE64_ENCODED_IMAGE：二进制图片数据的 base64 表示（ASCII 字符串）。此字符串应类似于以下字符串：
- /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
如需了解详情，请参阅 base64 编码主题。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION_ID：有效的位置标识符。有效的位置标识符包括 us-west1、us-east1、europe-west1 和 asia-east1。
PRODUCT_SET_ID：您要对其执行操作的商品集的 ID。

特定于字段的注意事项：

features.maxResults - 要返回的结果数的上限。
imageContext.productCategories - 要搜索的商品类别。目前，您只能指定一种商品类别（家庭用品、服装、玩具、包装商品和一般商品）。
imageContext.filter -（可选）用于商品标签的一个（或多个）键值对过滤表达式。格式：“key=value”。过滤键值对可以与 AND 或 OR 表达式搭配使用：“color=blue AND style=mens”或“color=blue OR color=black”。如果使用 OR 表达式，则表达式中的所有键必须相同。

HTTP 方法和网址：

POST https://vision.googleapis.com/v1/images:annotate

请求 JSON 正文：

{
  "requests": [
    {
      "image": {
        "content": base64-encoded-image
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH",
          "maxResults": 5
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/project-id/locations/location-id/productSets/product-set-id",
          "productCategories": [
               "apparel"
          ],
          "filter": "style = womens"
        }
      }
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.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 @request.json \
     "https://vision.googleapis.com/v1/images:annotate"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

如果请求成功，服务器将返回一个 200 OK HTTP 状态代码以及 JSON 格式的响应。

响应 JSON 包含以下两种结果类型：

productSearchResults - 包含整个图片的匹配商品列表。在示例响应中，匹配商品为 product_id65、product_id35、product_id34、product_id62 和 product_id32。
productGroupedResults - 包含图片中识别的每个商品的边界框坐标和匹配项。在以下响应中，仅识别了一个商品，后跟示例商品集中的匹配商品：product_id65、product_id35、product_id34、product_id93 和 product_id62。

请注意，虽然这两种结果类型存在重叠，但也可能存在差异（例如，响应中的 product_id32 和 product_id93）。

响应

{
  "responses": [
    {
      "productSearchResults": {
        "indexTime": "2019-09-04T21:03:35.662099907Z",
        "results": [
          {
            "product": {
              "name": "projects/project-id/locations/location-id/products/product_id65",
              "displayName": " ",
              "productCategory": "apparel",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.38946953,
            "image": "projects/project-id/locations/location-id/products/product_id65/referenceImages/image65"
          },
          {
            "product": {
              "name": "projects/project-id/locations/location-id/products/product_id35",
              "displayName": " ",
              "productCategory": "apparel",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.3847863,
            "image": "projects/project-id/locations/location-id/products/product_id35/referenceImages/image35"
          },
          {
            "product": {
              "name": "projects/project-id/locations/location-id/products/product_id34",
              "displayName": " ",
              "productCategory": "apparel",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.33896044,
            "image": "projects/project-id/locations/location-id/products/product_id34/referenceImages/image34"
          },
          {
            "product": {
              "name": "projects/project-id/locations/location-id/products/product_id62",
              "displayName": " ",
              "productCategory": "apparel",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.32509044,
            "image": "projects/project-id/locations/location-id/products/product_id62/referenceImages/image62"
          },
          {
            "product": {
              "name": "projects/project-id/locations/location-id/products/product_id32",
              "displayName": " ",
              "productCategory": "apparel",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.3237155,
            "image": "projects/project-id/locations/location-id/products/product_id32/referenceImages/image32"
          }
        ],
        "productGroupedResults": [
          {
            "boundingPoly": {
              "normalizedVertices": [
                {
                  "x": 0.00458825,
                  "y": 0.11000001
                },
                {
                  "x": 0.988353,
                  "y": 0.11000001
                },
                {
                  "x": 0.988353,
                  "y": 0.9290588
                },
                {
                  "x": 0.00458825,
                  "y": 0.9290588
                }
              ]
            },
            "results": [
              {
                "product": {
                  "name": "projects/project-id/locations/location-id/products/product_id65",
                  "displayName": " ",
                  "productCategory": "apparel",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.41785678,
                "image": "projects/project-id/locations/location-id/products/product_id65/referenceImages/image65"
              },
              {
                "product": {
                  "name": "projects/project-id/locations/location-id/products/product_id35",
                  "displayName": " ",
                  "productCategory": "apparel",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.3803885,
                "image": "projects/project-id/locations/location-id/products/product_id35/referenceImages/image35"
              },
              {
                "product": {
                  "name": "projects/project-id/locations/location-id/products/product_id34",
                  "displayName": " ",
                  "productCategory": "apparel",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.36055994,
                "image": "projects/project-id/locations/location-id/products/product_id34/referenceImages/image34"
              },
              {
                "product": {
                  "name": "projects/project-id/locations/location-id/products/product_id93",
                  "displayName": " ",
                  "productCategory": "apparel",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "shoe"
                    },
                    {
                      "key": "kids",
                      "value": "true"
                    }
                  ]
                },
                "score": 0.33286288,
                "image": "projects/project-id/locations/location-id/products/product_id93/referenceImages/image93"
              },
              {
                "product": {
                  "name": "projects/project-id/locations/location-id/products/product_id62",
                  "displayName": " ",
                  "productCategory": "apparel",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.32263064,
                "image": "projects/project-id/locations/location-id/products/product_id62/referenceImages/image62"
              }
            ],
            "objectAnnotations": [
              {
                "mid": "/m/01d40f",
                "name": "Dress",
                "score": 0.95488
              }
            ]
          }
        ]
      }
    }
  ]
}

Go

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import (
	"context"
	"fmt"
	"io"
	"os"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// getSimilarProducts searches for products from a product set similar to products in an image file.
func getSimilarProducts(w io.Writer, projectID string, location string, productSetID string, productCategory string, file string, filter string) error {
	ctx := context.Background()
	c, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return fmt.Errorf("NewImageAnnotatorClient: %w", err)
	}
	defer c.Close()

	f, err := os.Open(file)
	if err != nil {
		return fmt.Errorf("Open: %w", err)
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return fmt.Errorf("NewImageFromReader: %w", err)
	}

	ictx := &visionpb.ImageContext{
		ProductSearchParams: &visionpb.ProductSearchParams{
			ProductSet:        fmt.Sprintf("projects/%s/locations/%s/productSets/%s", projectID, location, productSetID),
			ProductCategories: []string{productCategory},
			Filter:            filter,
		},
	}

	response, err := c.ProductSearch(ctx, image, ictx)
	if err != nil {
		return fmt.Errorf("ProductSearch: %w", err)
	}

	fmt.Fprintf(w, "Product set index time:\n")
	fmt.Fprintf(w, "seconds: %d\n", response.IndexTime.Seconds)
	fmt.Fprintf(w, "nanos: %d\n", response.IndexTime.Nanos)

	fmt.Fprintf(w, "Search results:\n")
	for _, result := range response.Results {
		fmt.Fprintf(w, "Score(Confidence): %f\n", result.Score)
		fmt.Fprintf(w, "Image name: %s\n", result.Image)

		fmt.Fprintf(w, "Prodcut name: %s\n", result.Product.Name)
		fmt.Fprintf(w, "Product display name: %s\n", result.Product.DisplayName)
		fmt.Fprintf(w, "Product labels: %s\n", result.Product.ProductLabels)
	}

	return nil
}

Java

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * Search similar products to image in local file.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productSetId - Id of the product set.
 * @param productCategory - Category of the product.
 * @param filePath - Local file path of the image to be searched
 * @param filter - Condition to be applied on the labels. Example for filter: (color = red OR
 *     color = blue) AND style = kids It will search on all products with the following labels:
 *     color:red AND style:kids color:blue AND style:kids
 * @throws IOException - on I/O errors.
 */
public static void getSimilarProductsFile(
    String projectId,
    String computeRegion,
    String productSetId,
    String productCategory,
    String filePath,
    String filter)
    throws IOException {
  try (ImageAnnotatorClient queryImageClient = ImageAnnotatorClient.create()) {

    // Get the full path of the product set.
    String productSetPath = ProductSetName.format(projectId, computeRegion, productSetId);

    // Read the image as a stream of bytes.
    File imgPath = new File(filePath);
    byte[] content = Files.readAllBytes(imgPath.toPath());

    // Create annotate image request along with product search feature.
    Feature featuresElement = Feature.newBuilder().setType(Type.PRODUCT_SEARCH).build();
    // The input image can be a HTTPS link or Raw image bytes.
    // Example:
    // To use HTTP link replace with below code
    //  ImageSource source = ImageSource.newBuilder().setImageUri(imageUri).build();
    //  Image image = Image.newBuilder().setSource(source).build();
    Image image = Image.newBuilder().setContent(ByteString.copyFrom(content)).build();
    ImageContext imageContext =
        ImageContext.newBuilder()
            .setProductSearchParams(
                ProductSearchParams.newBuilder()
                    .setProductSet(productSetPath)
                    .addProductCategories(productCategory)
                    .setFilter(filter))
            .build();

    AnnotateImageRequest annotateImageRequest =
        AnnotateImageRequest.newBuilder()
            .addFeatures(featuresElement)
            .setImage(image)
            .setImageContext(imageContext)
            .build();
    List<AnnotateImageRequest> requests = Arrays.asList(annotateImageRequest);

    // Search products similar to the image.
    BatchAnnotateImagesResponse response = queryImageClient.batchAnnotateImages(requests);

    List<Result> similarProducts =
        response.getResponses(0).getProductSearchResults().getResultsList();
    System.out.println("Similar Products: ");
    for (Result product : similarProducts) {
      System.out.println(String.format("\nProduct name: %s", product.getProduct().getName()));
      System.out.println(
          String.format("Product display name: %s", product.getProduct().getDisplayName()));
      System.out.println(
          String.format("Product description: %s", product.getProduct().getDescription()));
      System.out.println(String.format("Score(Confidence): %s", product.getScore()));
      System.out.println(String.format("Image name: %s", product.getImage()));
    }
  }
}

Node.js

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');
const fs = require('fs');
// Creates a client
const productSearchClient = new vision.ProductSearchClient();
const imageAnnotatorClient = new vision.ImageAnnotatorClient();

async function getSimilarProductsFile() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'nodejs-docs-samples';
  // const location = 'us-west1';
  // const productSetId = 'indexed_product_set_id_for_testing';
  // const productCategory = 'apparel';
  // const filePath = './resources/shoes_1.jpg';
  // const filter = '';
  const productSetPath = productSearchClient.productSetPath(
    projectId,
    location,
    productSetId
  );
  const content = fs.readFileSync(filePath, 'base64');
  const request = {
    // The input image can be a GCS link or HTTPS link or Raw image bytes.
    // Example:
    // To use GCS link replace with below code
    // image: {source: {gcsImageUri: filePath}}
    // To use HTTP link replace with below code
    // image: {source: {imageUri: filePath}}
    image: {content: content},
    features: [{type: 'PRODUCT_SEARCH'}],
    imageContext: {
      productSearchParams: {
        productSet: productSetPath,
        productCategories: [productCategory],
        filter: filter,
      },
    },
  };
  const [response] = await imageAnnotatorClient.batchAnnotateImages({
    requests: [request],
  });
  console.log('Search Image:', filePath);
  const results = response['responses'][0]['productSearchResults']['results'];
  console.log('\nSimilar product information:');
  results.forEach(result => {
    console.log('Product id:', result['product'].name.split('/').pop(-1));
    console.log('Product display name:', result['product'].displayName);
    console.log('Product description:', result['product'].description);
    console.log('Product category:', result['product'].productCategory);
  });
}
getSimilarProductsFile();

Python

如需向 Vision API Product Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

from google.cloud import vision

def get_similar_products_file(
    project_id,
    location,
    product_set_id,
    product_category,
    file_path,
    filter,
    max_results,
):
    """Search similar products to image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_set_id: Id of the product set.
        product_category: Category of the product.
        file_path: Local file path of the image to be searched.
        filter: Condition to be applied on the labels.
                Example for filter: (color = red OR color = blue) AND style = kids
                It will search on all products with the following labels:
                color:red AND style:kids
                color:blue AND style:kids
        max_results: The maximum number of results (matches) to return. If omitted, all results are returned.
    """
    # product_search_client is needed only for its helper methods.
    product_search_client = vision.ProductSearchClient()
    image_annotator_client = vision.ImageAnnotatorClient()

    # Read the image as a stream of bytes.
    with open(file_path, "rb") as image_file:
        content = image_file.read()

    # Create annotate image request along with product search feature.
    image = vision.Image(content=content)

    # product search specific parameters
    product_set_path = product_search_client.product_set_path(
        project=project_id, location=location, product_set=product_set_id
    )
    product_search_params = vision.ProductSearchParams(
        product_set=product_set_path,
        product_categories=[product_category],
        filter=filter,
    )
    image_context = vision.ImageContext(product_search_params=product_search_params)

    # Search products similar to the image.
    response = image_annotator_client.product_search(
        image, image_context=image_context, max_results=max_results
    )

    index_time = response.product_search_results.index_time
    print("Product set index time: ")
    print(index_time)

    results = response.product_search_results.results

    print("Search results:")
    for result in results:
        product = result.product

        print(f"Score(Confidence): {result.score}")
        print(f"Image name: {result.image}")

        print(f"Product name: {product.name}")
        print("Product display name: {}".format(product.display_name))
        print(f"Product description: {product.description}\n")
        print(f"Product labels: {product.product_labels}\n")

其他语言

C#：请按照客户端库页面上的 C# 设置说明操作，然后访问 .NET 版 Vision API Product Search 参考文档。

PHP：请按照客户端库页面上的 PHP 设置说明操作，然后访问 PHP 版 Vision API Product Search 参考文档。

Ruby 版：请按照客户端库页面上的 Ruby 设置说明操作，然后访问 Ruby 版 Vision API Product Search 参考文档。

服装响应示例

Search Image:
  D:/product/final/images-20180618T073733Z-01/images/469355b570ba11e88ff2d20059124800.jpg

Similar product information:
 Product id: 46930b6b
 Product display name: Evening gown
 Product description: Blue evening gown in 1940s style
 Product category: apparel
 style: women
 category: dress
 color: blue

使用标签进行搜索

以下搜索示例包括一个基于颜色的过滤条件。

请求

使用方法 get_similar_products_file() 或 get_similar_products_uri() 执行以下请求，以发出搜索请求。商品集 ID、本地图片文件路径和过滤条件作为参数传入。该输入图片也存在于“resources/input/”中。

Python

python product_search.py get_similar_products_file "12000002" "D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg" "color=white"

响应

Search Image:
  D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg

Similar product information:
 Product id: p569d4e7a1
 Product display name: Wedding Dress
 Product description: Elegant Wedding Dress for women
 Product category: apparel
 style: women
 category: dress
 color: white

Product Search 教程

准备工作

导入库

Go

Java

Node.js

Python

其他语言

运行应用

第 1 步：创建商品目录

在线（逐一）导入

1. 创建商品集

请求

REST

curl

PowerShell

Go

Java

Node.js

Python

其他语言

响应

2. 创建商品

REST

curl

PowerShell

使用指定的 productId 创建商品

curl

PowerShell

Go

Java

Node.js

Python

其他语言

响应

3. 将商品添加到商品集

REST

curl

PowerShell

Go

Java

Node.js

Python

其他语言

响应

4. 更新商品

命令行

curl

PowerShell

Go

Java

Node.js

Python

其他语言

响应

5. 创建商品的参考图片

REST

curl

PowerShell

Go

Java

Node.js

Python

其他语言

响应

第 2 步：搜索匹配商品

REST

curl

PowerShell

响应

Go

Java

Node.js

Python

其他语言

服装响应示例

使用标签进行搜索

请求

Python

响应

使用指定的 `productId` 创建商品