这是与 Recommendations AI、Retail Search 和新的 Retail 控制台相关的文档。如需在受限 GA 阶段使用 Retail Search,请与 Cloud 销售人员联系

如果您仅使用 Recommendations AI,请保留在 Recommendations 控制台上并参阅 Recommendations AI 文档

管理目录信息

本页面介绍如何在将目录导入 Retail API 后管理商品信息。您可以读取、写入和删除目录中的商品。

要使目录随商品信息变化而保持最新状态,请按照首次导入的方式导入目录。如需导入目录方面的帮助,请参阅导入目录信息

上传产品

curl

使用 products.create REST 方法创建单个产品项。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
      "title": "PRODUCT_TITLE",
      "categories": "Shoes & Accessories > Shoes"
    }' \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products?productID=PRODUCT_ID"

如果请求成功,则会返回商品对象,如以下示例所示。

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories \u003e Shoes"
  ],
  "title": "product title",
  "availability": "IN_STOCK"
}

Java

public static Product createProduct(Product productToCreate, String productId)
    throws IOException {
  return getProductServiceClient().createProduct(
      DEFAULT_BRANCH_NAME, productToCreate, productId
  );
}

更新产品信息

当您的产品目录发生变化时,您可以通过实时上传产品变化情况(例如新产品、价格和库存状态)来刷新目录。您只能上传已添加或更改的产品;无需重新加载整个目录。

curl

使用 products.patch 方法更新商品信息。

以下示例更新特定产品的标题:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
       "title": "new-title-value"
    }" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID?updateMask=title"

如果请求成功,则会返回商品对象,如以下示例所示。

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories > Shoes"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Java

public static Product updateProduct(Product productToUpdate) throws IOException {
  return getProductServiceClient().updateProduct(productToUpdate, FieldMask.getDefaultInstance());
}

删除产品信息

虽然 Retail API 提供了一种从目录中删除商品的方法,但请注意,如果您记录与已删除的商品项相关的用户事件,Retail API 将无法正确处理用户事件并且可能会删除用户事件。此外,添加历史目录数据可以提高模型的质量,对于优质的推荐和搜索结果至关重要。

您应该将过时商品的 availability 设置为 OUT_OF_STOCK,而不是将其删除。

curl

使用 delete 方法删除商品,将 PRODUCT_ID 替换为要删除的商品的 ID。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

Java

public static void deleteProduct(String productName) throws IOException {
  getProductServiceClient().deleteProduct(productName);
}

检索产品项

curl

要检索商品项,请向 products 端点发出 GET 请求,并将 PRODUCT_ID 替换为要检索的商品的 ID:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

您将看到如下所示的输出:

{
    "name": "projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"
    "id": "PRODUCT_ID",
    "primaryProductId": "PRODUCT_ID",
    "type": "PRIMARY",
    "categories": [
      "Shoes & Accessories \u003e Shoes"
    ],
    "title": "product title",
    "availability": "IN_STOCK"
}

Java

public static Product getProduct(String productName) throws IOException {
  return getProductServiceClient().getProduct(productName);
}

查看目录的汇总信息

您可以在“Retail 数据”页面的“目录”标签页中查看有关您的目录的汇总信息并预览上传的产品项。

重新联接目录事件

userEvents:rejoin 端点发出 POST 请求即可重新联接目录事件。

您必须具有 Retail AI Admin IAM 角色。

curl

根据您要重新联接的事件类型,设置 userEventRejoinScope

  • USER_EVENT_REJOIN_SCOPE_UNSPECIFIED:默认值。触发已联接和未联接事件的重新联接。
  • JOINED_EVENTS:仅触发已联接事件的重新联接。
  • UNJOINED_EVENTS:仅触发未联接事件的重新联接。

以下示例仅触发未联接事件的重新联接:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
     'userEventRejoinScope': 'UNJOINED_EVENTS'
     }" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:rejoin"

您应该会收到类似如下所示的响应对象:

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID"
}

您可以检查重新联接的状态。将 OPERATION_ID 替换为重新联接方法返回的操作 ID:

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID"

操作完成后,操作状态将以 done 的形式返回:

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.RejoinUserEventsResponse",
    "rejoinedUserEventsCount": "1"
  }
}

Java

public static String rejoinUserEvents(UserEventRejoinScope scope)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  RejoinUserEventsRequest request = RejoinUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEventRejoinScope(scope)
      .build();

  String operationName = userEventsClient
      .rejoinUserEventsAsync(request).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

更改商品类型

导入商品时,您可以指定商品的类型是主项、变体还是集合。如果商品类型更改或未正确指定,您必须删除商品并使用指定的更新后类型创建商品

商品的类型可以设置为 TYPE_UNSPECIFIEDPRIMARYVARIANTCOLLECTION。如需了解详情,请参阅参考文档中的 [product.Type][product-type]。

更改商品级别配置

使用 Merchant Center 导入目录时,您必须指定商品是主项还是变体。如果这些商品级别发生了更改或未正确指定,请按照以下步骤更正其配置。您必须具有 Retail Admin IAM 角色。

  1. 确保在重新配置商品级别时没有执行任何导入操作。这样可确保数据不会在错误的级别上传。

  2. 删除所有产品项。请参阅 products.delete。 目录必须完全为空,才能继续下一步。

  3. 重新导入数据即可更改商品级配置。

    此过程取决于您的导入方式。按照导入目录信息中的适当步骤将商品级别设置为其新配置。

  4. 按照您在导入目录信息中选择的步骤,使用修改后的级别配置导入新目录。

  5. 调整所有现有模型。

    如需调整模型,请转到“模型”页面,点击模型名称以查看其详情页面,然后点击按钮栏中的手动调整

    转到“Retail 模型”页面

    如需了解调整费用详情,请参阅价格