这是仅与 Recommendations AI 相关的文档。如需在受限 GA 阶段试用 Retail Search 和统一 Retail 控制台,请与 Cloud 销售人员联系如果您不打算使用 Retail Search,请保留在 Recommendations 控制台上,直到收到进一步的通知。

如果您使用的是 v1beta 版 Recommendations AI,请迁移到 Retail API 版本

导入目录信息

本页面介绍如何将目录信息导入到 Recommendations AI 中并使其保持最新。

准备工作

在导入目录信息之前,您必须已完成准备工作中的说明,特别是设置项目创建服务帐号将服务帐号添加到本地环境

您必须先选择商品级别,然后才能导入目录,并且您必须具有 Retail Admin IAM 角色才能执行导入操作。

目录导入最佳做法

Recommendations AI 需要使用高品质数据进行高品质的预测。如果您的数据缺失字段或具有占位符值而非实际值,则预测质量会受影响。

导入目录数据时,请确保实现以下最佳做法:

  • 在上传任何数据之前,请务必先查看商品级别信息

    在导入任何数据后更改商品级别需要花费大量精力。

  • 遵守商品导入限制。

    从 Cloud Storage 批量导入数据时,每个文件的大小不能超过 2 GB。一个批量导入请求中最多可以包含 100 个文件。

    对于内嵌导入,一次最多可导入 5000 个商品。

  • 请确保包含所有必需的目录信息,并且信息正确无误。

    请勿使用虚拟值或占位值。

  • 请添加尽可能多的可选目录信息

  • 确保您的事件都使用一种货币,尤其是如果您计划使用 Cloud Console 获取收入指标。Retail API 不支持每个目录使用多种货币。

  • 使目录保持最新。

    理想情况下,您应每天更新目录。安排定期目录导入可防止模型质量逐渐降低。您可以使用 Google Cloud Scheduler 自动执行此任务。

  • 对于尚未导入的商品项,请勿记录其用户事件。

  • 导入目录信息后,请查看项目的错误报告和日志记录信息

    有少数错误是正常的,但是如果有大量错误,则应检查这些错误并修复导致错误的所有进程问题。

导入目录数据

要导入商品数据,您可以从 Merchant CenterCloud StorageBigQuery 导入或在请求中指定内嵌的数据。每个过程都是一次性导入。建议您每天导入目录,以确保目录是最新的。请参阅使目录保持最新

您还可以导入单件商品。如需了解详情,请参阅上传商品项

从 Merchant Center 导入目录数据

您可以使用 Cloud Console 或 Retail API 从 Merchant Center 导入目录数据。

要从 Merchant Center 导入目录,请完成以下步骤:

  1. 按照 Merchant Center 转移作业中的说明,设置从 Merchant Center 到 BigQuery 的转移作业。

    您将使用 Google Merchant Center 商品表架构。将转移作业配置为每天重复,但将数据集过期时间设置为 2 天。

  2. 如果您的 BigQuery 数据集位于其他项目中,请配置所需的权限,以便 Recommendations AI 可以访问 BigQuery 数据集。了解详情

  3. 将 BigQuery 中的目录数据导入 Recommendations AI。

    控制台

    1. 转到 Google Cloud Console 中的“Recommendations AI 数据”页面。
      转到“Recommendations AI 数据”页面
    2. 点击导入以打开导入目录面板。
    3. 输入数据所在的 BigQuery 数据集和表的 ID。
    4. 输入项目中 Cloud Storage 存储分区的位置。

      该存储分区用作数据的临时位置。

    5. 如果这是您第一次导入目录,请选择上传的商品级别(用户事件记录)和预测。

      在导入任何数据后更改商品级别需要花费大量精力。详细了解商品级别。

    6. 点击导入

    cURL

    1. 如果这是您第一次上传目录,请使用 Catalog.patch 方法设置商品级别。此操作需要 Retail Admin 角色。

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT-TYPE",
        "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog"
    2. 使用 Products.import 方法导入目录。

      • dataset-id:BigQuery 数据集的 ID。
      • table-id:存放数据的 BigQuery 表的 ID。
      • staging-directory:可选。在导入到 BigQuery 之前用作数据的临时位置的 Cloud Storage 目录。将此字段留空可让 Recommendations AI 自动创建临时目录(推荐)。
      • error-directory:可选。存放与导入有关的错误信息的 Cloud Storage 目录。将此字段留空可让 Recommendations AI 自动创建临时目录(推荐)。
      • dataSchema:对于 dataSchema 属性,请使用值 product_merchant_center。请参阅 Merchant Center 商品表架构

      建议您不要指定暂存目录或错误目录,以便 Recommendations AI 可以使用新的暂存目录和错误目录自动创建 Cloud Storage 存储分区。这些目录在 BigQuery 数据集所在的区域中创建,并且对每个导入作业都是唯一的(这样可以防止多个导入作业将数据暂存到同一目录和重新导入相同的数据)。三天后,系统会自动删除存储分区和目录,以减少存储费用。

      自动创建的存储分区名称包含项目 ID、存储分区区域和数据架构名称,并以下划线分隔(例如 4321_us_catalog_recommendations_ai)。自动创建的目录称为 stagingerrors,后跟一个数字(例如 staging2345errors5678)。

      如果指定目录,Cloud Storage 存储分区必须与 BigQuery 数据集位于同一区域,否则导入将失败。以 gs://<bucket>/<folder>/ 格式指定暂存和错误目录;二者应为不同的目录。

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "inputConfig":{
      "bigQuerySource": {
        "datasetId":"dataset-id",
        "tableId":"table-id",
        "dataSchema":"product_merchant_center"
      }
      }
      }' \
      "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products:import"
      

从 BigQuery 导入目录数据

要从 BigQuery 以正确的格式导入目录数据,请使用 Recommendations AI 架构以正确格式创建 BigQuery 表,并加载空表和目录数据。然后,将数据上传到 Recommendations AI。

如需有关 BigQuery 表的更多帮助,请参阅表简介。如需有关 BigQuery 查询的帮助,请参阅查询 BigQuery 数据概览

curl

  1. 如果您的 BigQuery 数据集位于其他项目中,请配置所需的权限,以便 Recommendations AI 可以访问 BigQuery 数据集。了解详情

  2. 如果这是您第一次上传目录,请使用 Catalog.patch 方法设置商品级别。此操作需要 Recommendations AI Admin 角色。

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
       "productLevelConfig": {
         "ingestionProductType": "PRODUCT-TYPE",
         "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
       }
     }' \
    "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog"
    
  3. 为导入作业的输入参数创建一个数据文件。输入参数值取决于您是从 Cloud Storage 还是 BigQuery 导入。

    您可以使用 BigQuerySource 对象指向 BigQuery 数据集。

    • dataset-id:BigQuery 数据集的 ID。
    • table-id:存放数据的 BigQuery 表的 ID。
    • staging-directory:可选。在导入到 BigQuery 之前用作数据的临时位置的 Cloud Storage 目录。将此字段留空可让 Recommendations AI 自动创建临时目录(推荐)。
    • error-directory:可选。存放与导入有关的错误信息的 Cloud Storage 目录。将此字段留空可让 Recommendations AI 自动创建临时目录(推荐)。
    • dataSchema:对于 dataSchema 属性,请使用值 product(默认值)。您将使用 Recommendations AI 架构

    建议您不要指定暂存目录或错误目录,以便 Recommendations AI 可以使用新的暂存目录和错误目录自动创建 Cloud Storage 存储分区。这些目录在 BigQuery 数据集所在的区域中创建,并且对每个导入作业都是唯一的(这样可以防止多个导入作业将数据暂存到同一目录和重新导入相同的数据)。三天后,系统会自动删除存储分区和目录,以减少存储费用。

    自动创建的存储分区名称包含项目 ID、存储分区区域和数据架构名称,并以下划线分隔(例如 4321_us_catalog_recommendations_ai)。自动创建的目录称为 stagingerrors,后跟一个数字(例如 staging2345errors5678)。

    如果指定目录,Cloud Storage 存储分区必须与 BigQuery 数据集位于同一区域,否则导入将失败。以 gs://<bucket>/<folder>/ 格式指定暂存和错误目录;二者应为不同的目录。

    {
    "inputConfig":{
     "bigQuerySource": {
       "datasetId":"dataset-id",
       "tableId":"table-id",
       "dataSchema":"product"}
      }
    }
    
  4. Products:import REST 方法发出 POST 请求,将目录信息导入 Recommendations AI,并提供数据文件的名称(此处显示为 input.json)。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" -d @./input.json
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products:import"
    

    要检查导入操作的状态,最简单的方法是使用 Cloud Console。如需了解详情,请参阅查看特定集成操作的状态

    您还可以使用 API 以编程方式检查状态。您应该会收到类似如下所示的响应对象:

    {
    "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/import-products-123456",
    "done": false
    }
    

    名称字段是操作对象的 ID。要请求此对象的状态,请将名称字段替换为导入方法返回的值,直到 done 字段返回 true

    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/import-products-123456"
    

    操作完成后,返回的对象的 done 值为 true,并且包含一个类似于以下示例的 Status 对象:

    { "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/import-products-123456",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
      "createTime": "2020-01-01T03:33:33.000001Z",
      "updateTime": "2020-01-01T03:34:33.000001Z",
      "successCount": "2",
      "failureCount": "1"
    },
    "done": true
    "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
    },
    "errorsConfig": {
      "gcsPrefix": "gs://error-bucket/error-directory"
    }
    }
    

    您可以检查 Cloud Storage 错误目录中的文件,以查看导入期间发生的错误类型。

设置对 BigQuery 数据集的访问权限

如果 BigQuery 数据集与 Recommendations AI 服务属于不同的项目,要设置访问权限,请完成以下步骤。

  1. 在 Cloud Console 中打开 IAM 页面。

    打开 IAM 页面

  2. 选择 Recommendations AI 项目。

  3. 查找名为 AutoML Recommendations 服务帐号的服务帐号。

    如果您之前没有使用 Recommendations AI 启动导入操作,则此服务帐号可能不会列出。如果您没有看到此服务帐号,请返回导入任务并启动导入。当由于权限错误而失败时,请返回此处完成此任务。

  4. 复制服务帐号的标识符,类似于电子邮件地址(例如 service-525@gcp-sa-recommendationengine.iam.gserviceaccount.com)。

  5. 切换到 BigQuery 项目(在同一 IAM 和管理页面上),然后点击添加

  6. 输入 Recommendations AI 服务帐号的标识符,然后选择 BigQuery > BigQuery User 角色。

  7. 点击添加其他角色,然后选择 BigQuery > BigQuery Data Editor

    如果您不想向整个项目提供 Data Editor 角色,则可以将此角色直接添加到数据集。了解详情

  8. 点击保存

从 Cloud Storage 导入目录数据

如需导入 JSON 格式的目录数据,您需要创建一个或多个 JSON 文件,其中包含要导入的目录数据,然后将其上传到 Cloud Storage。然后,您可以将其导入 Recommendations AI 中。

如需查看 JSON 商品项格式的示例,请参阅商品项 JSON 数据格式

如需有关将文件上传到 Cloud Storage 方面的帮助,请参阅上传对象

curl

  1. 确保 Recommendations AI 服务帐号有权读写存储分区

    Recommendations AI 服务帐号列在 Cloud Console 的 IAM 页面中,名为Retail 服务帐号。将帐号添加到存储桶权限时,请使用其标识符(类似于电子邮件地址(例如 service-525@gcp-sa-retail.iam.gserviceaccount.com)。

  2. 如果这是您第一次上传目录,请使用 Catalog.patch 方法设置商品级别

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
       "productLevelConfig": {
         "ingestionProductType": "PRODUCT-TYPE",
         "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
       }
     }' \
    "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog"
    
  3. 为导入作业的输入参数创建一个数据文件。您可以使用 GcsSource 对象指向您的 Cloud Storage 存储分区。

    您可以提供多个文件,也可以只提供一个文件;本例使用了两个文件。

    • input-file:Cloud Storage 中包含目录数据的一个或多个文件。
    • error-directory:存放与导入有关的错误信息的 Cloud Storage 目录。

    输入文件字段必须采用 gs://<bucket>/<path-to-file>/ 格式。错误目录必须采用 gs://<bucket>/<folder>/ 格式。如果错误目录不存在,Recommendations AI 会创建它。存储分区必须已存在。

    {
    "inputConfig":{
     "gcsSource": {
       "inputUris": ["input-file1", "input-file2"],
      },
      "errorsConfig":{"gcsPrefix":"error-directory"}
    }
    
  4. Products:import REST 方法发出 POST 请求,将目录信息导入 Recommendations AI,并提供数据文件的名称(此处显示为 input.json)。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
    -H "Content-Type: application/json; charset=utf-8" -d @./input.json"
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products:import"
    

    要检查导入操作的状态,最简单的方法是使用 Cloud Console。如需了解详情,请参阅查看特定集成操作的状态

    您还可以使用 API 以编程方式检查状态。您应该会收到类似如下所示的响应对象:

    {
    "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/import-products-123456",
    "done": false
    }
    

    名称字段是操作对象的 ID。您可以请求此对象的状态,将名称字段替换为导入方法返回的值,直到 done 字段返回 true

    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_NAME]"
    

    操作完成后,返回的对象的 done 值为 true,并且包含一个类似于以下示例的 Status 对象:

    { "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/import-products-123456",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
      "createTime": "2020-01-01T03:33:33.000001Z",
      "updateTime": "2020-01-01T03:34:33.000001Z",
      "successCount": "2",
      "failureCount": "1"
    },
    "done": true
    "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
    },
    "errorsConfig": {
      "gcsPrefix": "gs://error-bucket/error-directory"
    }
    }
    

    您可以检查 Cloud Storage 错误目录中的文件,以查看导入期间发生的错误类型。

以内嵌方式导入目录数据

curl

您可以通过以下方式将目录信息内嵌导入 Recommendations AI:向 Products:import REST 方法发出 POST 请求(使用 productInlineSource 对象指定目录数据)。

如需查看 JSON 商品项格式的示例,请参阅商品项 JSON 数据格式

  1. 为您的商品创建 JSON 文件,并将其命名为 ./data.json

    {
    "inputConfig": {
    "productInlineSource": {
      "products": [
        {
          <product1>
        },
        {
          <product2>
        },
        ....
      ]
    }
    }
    }
    
  2. 调用 POST 方法:

    curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products:import"
    

产品项 JSON 数据格式

JSON 文件应类似于以下示例。换行符是为了方便阅读;您应该在一行中提供整个商品项。每个商品项应独占一行。

至少填充以下必填字段:

{
  "id": "1234",
  "categories": "Apparel & Accessories > Shoes",
  "title": "ABC sneakers"
}
{
  "id": "5839",
  "categories": "casual attire > t-shirts",
  "title": "Crew t-shirt"
}

完成对象:

{
  "name": "projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/1234",
  "id": "1234",
  "categories": "Apparel & Accessories > Shoes",
  "title": "ABC sneakers",
  "description": "Sneakers for the rest of us",
  "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
  "language_code": "en",
  "tags": [ "black-friday" ],
  "priceInfo": {"currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50},
  "availableTime": "2020-01-01T03:33:33.000001Z",
  "availableQuantity": "1",
  "uri":"http://foobar",
  "images": [{"uri": "http://foobar/img1", "height": 320, "width": 320 }]
}

使目录保持最新

Recommendations AI 需要掌握最新商品信息,以便为您提供最佳建议。建议您每天导入目录,以确保目录是最新的。您可以使用 Google Cloud Scheduler 来安排导入。

您可以只更新新商品项或发生更改的商品项,也可以导入整个目录。如果您导入目录中已有的商品,系统不会再次添加这些商品。系统会更新所有发生更改的项。

要更新某个单独的项,请参阅更新目录信息

批量更新

您可以使用导入方法来批量更新目录。此操作方法与首次导入相同;请按照导入目录数据中的步骤操作。

监控导入运行状况

为了获得高质量的推荐,保持目录保持最新至关重要。您应监控导入错误率,并在需要时采取措施。如需了解详情,请参阅为数据上传问题设置提醒

后续步骤