管理目录信息

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

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

教程：创建/获取/更新/删除商品

本教程介绍了如何使用用于执行以下操作的 API 方法：

• 创建商品
• 获取商品
• 更新商品
• 删除商品

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

教程：创建商品

本教程介绍了如何创建单件商品。

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

教程：获取商品

本教程介绍了如何检索商品。

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

教程：更新商品

本教程介绍了如何更新清单中的商品。

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

教程：删除商品

本教程介绍了如何从清单中删除商品。

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

上传商品

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": "CATEGORY"
    }' \
    "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": [
    "CATEGORY"
  ],
  "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": [
    "Parent category > Child category"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Java

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

删除商品信息

虽然该 API 提供了一种从清单中删除商品的方法，但请注意，如果您记录与已被删除的商品相关的用户事件，则 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": [
      "Parent category > Child category"
    ],
    "title": "product title",
    "availability": "IN_STOCK"
}

Java

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

查看关于目录的汇总信息

您可以在 Search for Retail 控制台的数据页面上的目录标签页中查看有关您的清单和预览所上传商品的汇总信息。

评估目录数据质量

如需评估清单数据的质量，请执行以下操作：

1. 前往 Search for Retail 控制台中的数据质量页面。
   
   转到“数据质量”页面

   数据质量页面会评估您是否需要更新目录数据，以提高搜索结果的质量并解锁搜索性能层级。

如需详细了解如何检查搜索数据质量和查看搜索效果层级，请参阅解锁搜索性能层级。

如需查看可用的目录指标摘要，请参阅目录质量指标。

更改商品类型

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

商品的类型可以设置为 TYPE_UNSPECIFIED、PRIMARY、VARIANT 或 COLLECTION。如需了解详情，请参阅参考文档中的 product.Type。

更改产品级配置

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

注意：如果您计划继续使用 Merchant Center 导入，我们建议您不要将 ingestion_product_type 设置为 VARIANT。否则可能导致未来的 Merchant Center 导入无法正常运行。

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

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

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

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

4. 按照您在导入目录信息中选择的过程，完成包含修改后的级别配置的新清单的导入。

5. 调整所有现有模型。

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

   转到“模型”页面

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