Retail 将重命名为 Vertex AI Search for Retail。我们正在更新内容，以反映新的品牌形象。

此页面由 Cloud Translation API 翻译。

导入清单信息

本页介绍了如何导入您的目录信息并使其保持日期。

此页面上的导入步骤同时适用于这两种建议和搜索。导入数据后，这两项服务都能使用这些数据，因此您无需导入相同的两次的数据。

从 BigQuery 导入目录数据

本教程介绍如何使用 BigQuery 表导入无限制地处理大量清单数据。

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

操作演示

从 Cloud Storage 导入目录数据

本教程介绍了如何将大量商品导入清单。

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

操作演示

以内嵌方式导入清单数据

本教程介绍如何以内嵌方式将商品导入清单中。

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

操作演示

准备工作

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

您必须拥有 Retail Admin IAM 角色才能执行导入。

目录导入最佳做法

要生成高质量的结果，就需要高质量的数据。如果您的数据缺失字段或包含占位符值而非实际值，的联想查询和搜索结果都会受到影响

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

在决定哪些商品或商品组时，请务必商品是主要商品，而商品是款式/规格。在上传任何数据之前请参阅商品级别。

在导入任何数据后更改产品级配置需要大量的努力。

主要内容会作为搜索结果或建议返回。变体项不包含。

例如，如果主要 SKU 群组是“V 领衬衫”，那么推荐模型会返回一个 V 领衬衫项，圆领衬衫和叉领衬衫。不过，如果未使用不同款式/规格每个 SKU 都是主要商品，那么 V 领衬衫的每个颜色/尺寸组合在商品推荐面板中作为独立项目返回：“棕色 V 领” 衬衫，尺码为 XL”，“棕色 V 领衬衫，尺码 L”到“白色 V 领” 衬衫，尺码 M"，"白色 V 领衬衫，尺码 S"。
遵守商品导入限制。

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

对于内嵌导入，一次最多可导入 5000 个商品。
请确保包含所有必需的目录信息，并且信息正确无误。

请勿使用占位值。
请添加尽可能多的可选目录信息。
请确保您的活动都使用同一币种，尤其是在您打算使用使用 Google Cloud 控制台来获取收入指标。Vertex AI Search for Retail API 不支持使用为每个目录指定多种货币
使目录保持最新。

理想情况下，您应每天更新目录。安排定期目录导入可防止模型质量逐渐降低。您可以安排使用 Cloud Storage 存储分区 Search for Retail 控制台。或者，您也可以使用 Google Cloud Scheduler 自动执行导入。
对于尚未导入的商品项，请勿记录其用户事件。
导入目录信息后，请查看项目的错误报告和日志记录信息。

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

关于导入目录数据

您可以从 Merchant Center、Cloud Storage、BigQuery 导入商品数据，也可以在请求中指定内嵌的数据。每个过程都是一次性导入关联 Merchant Center 除外。预定定期导入目录（最好每天导入），以确保您的目录是最新的。请参阅及时更新目录。

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

目录导入注意事项

本部分介绍了可用于批量导入目录数据的方法、何时可以使用每种方法，以及这些方法的一些限制。

Merchant Center 同步	说明	通过关联，通过 Merchant Center 导入目录数据 Vertex AI Search for Retail 的账号。关联后， Merchant Center 中的商品目录数据会实时同步到 Vertex AI Search for Retail。
	使用时间	已与 Merchant Center 集成时。
	限制	架构支持受限。例如，Merchant Center 不支持产品集合。在 Merchant Center 取消关联之前，它是数据的可靠来源，因此必须将所有所需的自定义特性添加到 Merchant Center 数据中。控制受限。您无法指定要从 Merchant Center 导入的某些字段或商品集：Merchant Center 中现有的所有商品和字段都会导入。
BigQuery	说明	从先前加载的 BigQuery 表导入数据， Vertex AI Search for Retail 架构或 Merchant Center 架构。可使用 Google Cloud 控制台或 curl。
	使用时间	您的产品目录包含许多特性时。BigQuery 使用 Vertex AI Search for Retail 架构，该架构提供了更多产品，比其他导入选项（包括自定义键/值自定义）属性。您有大量数据时。BigQuery 导入没有数据限制。您已在使用 BigQuery 时。
	局限性	您需要执行额外的步骤来创建映射到 Vertex AI Search for Retail 架构。
Cloud Storage	说明	从加载到 Cloud Storage 存储桶中的文件导入 JSON 格式的数据。每个文件不得超过 2 GB，一次最多可导入 100 个文件。可以使用 Google Cloud 控制台完成导入或 curl。使用 `Product` JSON 数据格式，该格式允许自定义属性。
	使用时间	您需要在单个步骤中加载大量数据时。
	限制	不适合频繁更新商品目录和价格的目录，因为更改不会立即生效。
内嵌导入	说明	通过调用 `Product.import` 方法导入。用途 `ProductInlineSource` 对象，其中包含的商品较少与面向零售业的 Vertex AI Search 架构相比，支持自定义属性。
	使用时间	如果您有非关系型平面目录数据，或者数量或价格更新的频率较高。
	限制	一次最多只能导入 100 个目录商品。但是，可以执行许多加载步骤；没有商品限制。

完全清除目录分支

如果您要将新的清单数据导入现有分支，请务必目录分支为空。这可确保导入到的数据的完整性分支。当分支为空时，您可以导入新的清单数据，然后将分支与商家账号相关联。

如果您提供实时预测或搜索流量，并计划完全清除您的默认分支，不妨考虑先将另一个分支指定为默认分支，然后再完全清除。由于默认分支在被完全清除后会提供空结果，因此完全清除实时默认分支可能会导致服务中断。

如需从目录分支完全清除数据，请完成以下步骤：

转到 Data>（数据）>页面。

转到“数据”页面
从 Branch name 字段中选择一个清单分支。
从分支名称字段旁边的三点状菜单中，选择清除分支。

系统会显示一条消息，提醒您您即将删除其中的所有数据以及为该分支创建的任何属性。

注意：您无法撤消目录分支数据完全清除操作。
输入分支，然后点击确认，以从分支。

开始执行长时间运行的操作，以从目录分支中完全清除数据。完全清除操作完成后，系统会以 活动状态下的商品清单列表窗口。

注意：在之后，分支的目录数据列表不会自动刷新即完全清除您必须刷新页面才能看到更新的列表

将 Merchant Center 同步到 Vertex AI Search for Retail

为了在 Merchant Center 和 Vertex AI Search for Retail，您可以关联自己的 Merchant Center 账号 Vertex AI Search for Retail。关联后，您的 Merchant Center 账号会立即 Vertex AI Search for Retail。

为 Vertex AI Search for Retail 设置 Merchant Center 同步时，您必须在 Merchant Center 中分配管理员角色。虽然标准访问权限角色允许您在界面中读取 Merchant Center Feed，但当您尝试将 Merchant Center 同步到 Vertex AI Search for Retail 时，会收到错误消息。因此，您需要先相应地升级角色，然后才能成功将 Merchant Center 同步到零售行业的 Vertex AI Search。

而适用于零售业的 Vertex AI Search Search 与 Merchant Center 相关联在 Merchant Center 中对商品数据所做的更改账号会在 Vertex AI Search for Retail 中在几分钟内自动更新。如果您想阻止 Merchant Center 中的更改同步您可以解除与 Vertex AI Search for Retail 的关联， Merchant Center 账号。

解除关联 Merchant Center 账号不会删除任何 Vertex AI Search for Retail 两个产品。如需删除导入的商品，请参阅删除商品信息。

同步 Merchant Center 账号

如需同步您的 Merchant Center 账号，请完成以下步骤。

控制台

转到 Data>（数据）>页面。

转到“数据”页面
点击导入，打开导入数据面板。
选择商品清单。
选择 Merchant Center 同步作为数据源。
选择您的 Merchant Center 账号。如果您没有看到自己的账号，请查看用户访问权限。
可选：选择 Merchant Center Feed 过滤条件，仅导入所选 Feed 中的商品。

如果未指定，系统会导入所有 Feed（包括以后的 Feed）中的商品。
可选：如需仅导入定位到特定国家/地区或语言的优惠，请展开显示高级选项，然后选择 Merchant Center 目标销售国家/地区以及要过滤的语言。
选择您要将目录上传到的分支。
点击导入。

curl

检查本地环境中的服务账号既有权访问 Merchant Center 账号 Vertex AI Search for Retail。如需查看哪些账号有权访问您的 Merchant Center 账号，请参阅 Merchant Center 的用户访问权限。
使用 MerchantCenterAccountLink.create 方法建立关联。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"primaryFeedId": PRIMARY_FEED_ID_1}
    {"primaryFeedId": PRIMARY_FEED_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
```
- MERCHANT_CENTER_ID： Merchant Center 账号。
- BRANCH_ID：用于建立连接的分支的 ID 接受的值为“0”、“1”或“2”。
- LANGUAGE_CODE：（可选）您要导入的商品所属类别： Merchant Center 中“Language”列下的产品。如果未设置，系统会导入所有语言。
- FEED_LABEL：（可选）Feed 标签列出您要导入的商品的名称您可在以下位置查看 Feed 标签：产品的 Feed 标签中的 Merchant Center 列产品。如果未设置，系统会导入所有 Feed 标签。
- FEED_FILTERS：（可选）列表商品的主要 Feed 。不选择 Feed 意味着 Merchant Center 账号 Feed 是共享的。ID 可在 Content API datafeeds 资源中找到，或者通过访问 Merchant Center，选择相应 Feed 从以下位置的 dataSourceId 参数中获取 Feed ID：网站网址。例如 mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID。

若要查看关联的 Merchant Center 账号，请前往 Search for Retail 控制台数据页面，然后点击 Merchant Center 按钮。系统随即会打开关联的 Merchant Center 账号账号面板中的信息。您还可以添加其他 Merchant Center 账号账号。

如需了解更多详情，请参阅查看有关您的目录的汇总信息。有关如何查看已导入商品的说明。

列出您的 Merchant Center 账号关联

列出您的 Merchant Center 账号关联。

控制台

转到 Data>（数据）>页面。

转到“数据”页面
点击页面右上角的 Merchant Center 按钮，打开关联的 Merchant Center 账号列表。

curl

使用 MerchantCenterAccountLink.list 方法列出链接资源。

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

解除与 Merchant Center 账号的关联

如果解除关联 Merchant Center 账号，该账号将会停止将目录数据同步到 Vertex AI Search for Retail。此过程不会删除 Vertex AI Search for Retail 中已被已上传。

控制台

转到 Data>（数据）>页面。

转到“数据”页面
点击页面右上角的 Merchant Center 按钮，打开关联的 Merchant Center 账号列表。
点击要解除关联的 Merchant Center 账号旁边的解除关联，然后在显示的对话框中确认您的选择。

curl

使用 MerchantCenterAccountLink.delete 方法移除 MerchantCenterAccountLink 资源。

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

与 Merchant Center 关联的限制

一个 Merchant Center 账号可以与任意数量的目录分支相关联，但单个目录分支只能与一个 Merchant Center 账号相关联。
Merchant Center 账号不能是多客户账号 (MCA)。不过，您可以将个别子账号中的信息。
关联 Merchant Center 账号后首次导入可能需要几个小时才能完成。所需时间取决于 Merchant Center 账号中的商品/服务数量。
任何使用 API 方法进行的产品修改已针对与 Merchant Center 账号关联的分支停用。对这些分支中的产品目录数据所做的任何更改都必须使用 Merchant Center 进行。这些更改随后会自动同步 Vertex AI Search for Retail。
使用 Merchant Center 关联的分支不支持集合商品类型。
为了确保数据正确性，您的 Merchant Center 账号只能与空目录分支关联。为了从清单中删除商品请参阅删除商品信息。

从 Merchant Center 导入目录数据

Merchant Center 是一种工具，可让您用来使门店数据和商品数据可供购物广告和其他 Google 服务使用。

您可以将产品目录数据从 Merchant Center 批量导入为从 BigQuery 导入一次性过程 Merchant Center 架构（仅提供建议）。

从 Merchant Center 批量导入

您可以使用 Search for Retail 控制台或 products.import 方法。批量导入操作只需执行一次，建议。

要从 Merchant Center 导入目录，请完成以下步骤：

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

您将使用 Google Merchant Center 商品表架构。将转移作业配置为每天重复，但将数据集过期时间设置为 2 天。
如果您的 BigQuery 数据集位于其他项目中，请配置所需的权限，以便 Vertex AI Search for Retail 能够访问 BigQuery 数据集。了解详情。
将清单数据从 BigQuery 导入 Vertex AI Search for Retail。
控制台
1. 转到 Data>（数据）>页面。
  
  转到“数据”页面
2. 点击导入以打开“导入目录”面板。
3. 选择商品清单。
4. 选择 BigQuery 作为数据源。
5. 选择您要将目录上传到的分支。
6. 选择 Merchant Center 作为数据架构。
7. 输入数据所在的 BigQuery 表格。
8. 可选：输入 Cloud Storage 存储桶的位置作为数据的临时位置
  
  如果未指定，则使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储分区必须位于同一地区内。
9. 选择是否安排定期上传目录数据。
10. 如果这是您第一次导入目录，或者在完全清除目录后重新导入目录，请选择产品级别。详细了解商品级别。
  
  在导入任何产品级配置后，更改产品级配置需要投入大量精力。
  
  重要提示 ：您无法为包含仅作为商品款式/规格注入的商品清单。如果您想使用搜索和注入款式/规格，请使用 primary 商品级别。
11. 点击导入。
curl
1. 如果这是您第一次上传目录，或者要在完全清除后重新导入目录，请使用 Catalog.patch 方法设置产品级别。此操作需要 Retail Admin 角色。详细了解商品级别。
  - ingestionProductType：支持值 primary（默认值）和 variant。
  - merchantCenterProductIdField：支持值 offerId（默认值）和 itemGroupId。如果您不使用 Merchant Center，设置为默认值 offerId。
```
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 目录。将此字段留空自动创建目录（推荐）。
  - ERROR_DIRECTORY：可选。存放与导入有关的错误信息的 Cloud Storage 目录。保留此字段为空，则系统会自动创建临时目录（推荐）。
  - dataSchema：对于 dataSchema 属性，请使用值 product_merchant_center。请参阅 Merchant Center 商品表架构。
  我们建议您不要指定暂存目录或错误目录，这样的话，可以将带有新暂存目录和错误目录的 Cloud Storage 存储桶自动创建。这些目录是在同一目录下创建的作为 BigQuery 数据集的区域，并且对于每次导入都是唯一的（这可防止多个导入作业将数据暂存到同一目录，并可能重新导入相同的数据）。三天后，系统会自动删除存储分区和目录，以减少存储费用。
  
  自动创建的存储分区名称包含项目 ID、存储分区区域和数据架构名称，并以下划线分隔（例如 4321_us_catalog_retail）。自动创建的目录称为 staging 或 errors，后跟一个数字（例如 staging2345 或 errors5678）。
  
  如果指定目录，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 以正确的格式导入清单数据，请使用 Vertex AI Search for Retail 架构以正确的格式创建 BigQuery 表，并加载包含目录数据的空表。然后，上传您的数据 Vertex AI Search for Retail。

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

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

操作演示

要导入目录，请执行以下操作：

如果您的 BigQuery 数据集位于其他项目中，请配置所需的权限，以便 Vertex AI Search for Retail 能够访问 BigQuery 数据集。了解详情。
将清单数据导入适用于零售的 Vertex AI Search。
控制台
1. 转到 Data>（数据）>页面。
  
  转到“数据”页面
2. 点击导入，打开导入数据面板。
3. 选择商品清单。
4. 选择 BigQuery 作为数据源。
5. 选择您要将目录上传到的分支。
6. 选择 Retail Product Catalogs Schema。以下是 Vertex AI Search for Retail 的产品架构。
7. 输入数据所在的 BigQuery 表格。
8. 可选：在显示高级选项下，输入项目中的 Cloud Storage 存储桶，作为数据的临时位置。
  
  如果未指定，则使用默认位置。如果已指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域。
9. 如果您未启用搜索功能，且使用的是 Merchant Center 架构中，选择产品级别。
  
  您必须如果这是您第一次导入目录或在完全清除目录后重新导入该目录了解详情产品层面正在更改导入商品数据后，您需要投入大量精力。
  
  重要提示：您无法为包含已作为商品款式/规格注入的商品清单。
10. 点击导入。
curl
1. 如果这是您第一次上传目录，或者要在完全清除后重新导入目录，请使用 Catalog.patch 方法设置产品级别。此操作需要 Retail Admin 角色。
  - ingestionProductType：支持值 primary（默认值）和 variant。
  - merchantCenterProductIdField：支持值 offerId 和 itemGroupId。如果您不使用 Merchant Center，则无需设置此字段。
```
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. 为导入作业的输入参数创建一个数据文件。
  
  使用 BigQuerySource 对象指向 BigQuery 数据集。
  - DATASET_ID：BigQuery 数据集的 ID。
  - TABLE_ID：存放数据的 BigQuery 表的 ID。
  - PROJECT_ID：BigQuery 存储的项目 ID 来源如果未指定，项目 ID 将继承自请求。
  - STAGING_DIRECTORY：可选。在导入到 BigQuery 之前用作数据的临时位置的 Cloud Storage 目录。将此字段留空自动创建目录（推荐）。
  - ERROR_DIRECTORY：可选。存放与导入有关的错误信息的 Cloud Storage 目录。保留此字段为空，则系统会自动创建临时目录（推荐）。
  - dataSchema：对于 dataSchema 属性，请使用值 product（默认值）。您将使用适用于零售业的 Vertex AI Search 架构。
  我们建议您不要指定暂存目录或错误目录，这样的话，可以将带有新暂存目录和错误目录的 Cloud Storage 存储桶自动创建。这些目录是在同一目录下创建的作为 BigQuery 数据集的区域，并且对于每次导入都是唯一的（这可防止多个导入作业将数据暂存到同一目录，并可能重新导入相同的数据）。三天后，系统会自动删除存储分区和目录，以减少存储费用。
  
  自动创建的存储分区名称包含项目 ID、存储分区区域和数据架构名称，并以下划线分隔（例如 4321_us_catalog_retail）。自动创建的目录称为 staging 或 errors，后跟一个数字（例如 staging2345 或 errors5678）。
  
  如果指定目录，Cloud Storage 存储分区必须与 BigQuery 数据集位于同一区域，否则导入将失败。以 gs://<bucket>/<folder>/ 格式指定暂存和错误目录；二者应为不同的目录。
```
{
   "inputConfig":{
     "bigQuerySource": {
       "projectId":"PROJECT_ID",
       "datasetId":"DATASET_ID",
       "tableId":"TABLE_ID",
       "dataSchema":"product"}
      }
}
```
3. 通过以下方式导入您的目录信息：向 Products:import 发出 POST 请求 REST 方法，提供数据文件的名称（此处，显示为 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"
```
  您可以使用 API 以编程方式检查状态。您应该会收到类似如下所示的响应对象：
```
{
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}
```
  名称字段是操作对象的 ID。要请求此对象的状态，请将名称字段替换为 import 方法返回的值，直到 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 数据集位于其他数据集时设置访问权限，请执行以下操作： Vertex AI Search for Retail 服务，请完成以下步骤。

在 Google Cloud Console 中打开 IAM 页面。

打开 IAM 页面
选择您的 Vertex AI Search for Retail 项目。
找到名为 Retail Service Account 的服务账号。

如果您之前没有启动过导入操作，此服务账号可能未列出。如果您没有看到此服务账号，请返回导入任务并启动导入。当由于权限错误而失败时，请返回此处完成此任务。
复制服务账号的标识符，类似于电子邮件地址（例如 service-525@gcp-sa-retail.iam.gserviceaccount.com）。
切换到您的 BigQuery 项目（在相同的 IAM 和管理中）页面），然后点击 授予访问权限。
在新的主账号部分，输入 Vertex AI Search for Retail 的标识符服务账号，然后选择 BigQuery >BigQuery User 角色。
点击添加其他角色，然后选择 BigQuery > BigQuery Data Editor。

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

从 Cloud Storage 导入目录数据

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

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

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

请确保 Vertex AI Search for Retail 服务账号已对存储桶的读写权限。

Vertex AI Search for Retail 服务账号列在 IAM 页面在 Google Cloud 控制台中名为 Retail Service Account。将账号添加到存储分区权限时，请使用服务账号的标识符（类似于电子邮件地址，例如 service-525@gcp-sa-retail.iam.gserviceaccount.com）。
导入目录数据。
控制台
1. 转到 Data>（数据）>页面。
  
  转到“数据”页面
2. 点击导入，打开导入数据面板。
3. 选择商品清单作为数据源。
4. 选择您要将目录上传到的分支。
5. 选择 Retail Product Catalogs Schema 架构。
6. 输入数据的 Cloud Storage 位置。
7. 如果未启用搜索功能，请选择产品级别。
  
  您必须如果这是您第一次导入目录或在完全清除目录后重新导入该目录了解详情产品层面正在更改导入商品数据后，您需要投入大量精力。
  
  重要提示：您无法为包含已作为商品款式/规格注入的商品清单。
8. 点击导入。
curl
1. 如果这是您第一次上传目录，或者要在完全清除后重新导入目录，请使用 Catalog.patch 方法设置产品级别。详细了解商品级别。
  - ingestionProductType：支持值 primary（默认值）和 variant。
  - merchantCenterProductIdField：支持值 offerId 和 itemGroupId。如果您不使用 Merchant Center，则无需设置此字段。
```
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. 为导入作业的输入参数创建一个数据文件。您可以使用 GcsSource 对象指向您的 Cloud Storage 存储分区。
  
  您可以提供多个文件，也可以只提供一个文件；本例使用了两个文件。
  - INPUT_FILE：Cloud Storage 中包含目录数据的一个或多个文件。
  - ERROR_DIRECTORY：存放与导入有关的错误信息的 Cloud Storage 目录。
  输入文件字段必须采用 gs://<bucket>/<path-to-file>/ 格式。错误目录必须采用 gs://<bucket>/<folder>/ 格式。如果错误目录不存在，系统会创建该目录。存储桶必须已存在。
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
  }
},
"errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```
3. 导入清单信息，方法是向 Products:import REST 发出的 POST 请求方法，从而提供数据文件的名称（此处显示为 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"
```
  检查导入操作状态的最简单方法是请使用 Google Cloud 控制台。如需了解详情，请参阅查看特定集成操作的状态。
  
  您还可以使用 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

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

在一行上提供整个商品。每个产品都应独立行。

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

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

{
"inputConfig": {
"productInlineSource": {
  "products": [
    { PRODUCT_1 }
    { PRODUCT_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"

Java

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

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

  return operationName;
}

产品项 JSON 数据格式

JSON 文件中的 Product 条目应如以下示例所示。

在一行上提供整个商品。每个产品都应独立行。

至少填充以下必填字段：

  {
    "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://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

历史目录数据

适用于零售业的 Vertex AI Search 支持导入和管理历史数据目录数据。使用历史用户事件进行模型训练时，历史目录数据会很有帮助。过往商品信息可用于扩充历史用户事件数据，并提高模型准确性。

历史产品存储为过期产品。它们不会在搜索响应中返回，但对 Update、List 和 Delete API 调用可见。

导入历史目录数据

如果产品的 expireTime 字段设置为过去的时间戳，则此产品将被视为历史产品。设置产品 availability [库存状况] 至 OUT_OF_STOCK，以免影响建议。

我们建议您使用以下方法导入历史目录数据：

调用 `Product.Create` 方法

使用 Product.Create 方法创建一个 Product 条目，并将 expireTime 字段设置为过去的时间戳。

内嵌导入过期产品

相关步骤与内嵌导入基本相同，区别在于应将 expireTime 字段设为过去的时间时间戳。

在一行上提供整个商品。每个产品都应独立行。

在内嵌导入请求中使用的 ./data.json 示例：

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

从 BigQuery 或 Cloud Storage 导入过期产品

请遵循从 BigQuery 导入清单数据或从 Cloud Storage 导入清单数据。但是，请务必将 expireTime 字段更改为过去的时间戳。

让您的目录保持最新状态

为获得最佳效果，您的目录必须包含最新信息。建议您每天导入目录，以确保目录是最新的。您可以使用 Google Cloud Scheduler（用于安排导入时间），或选择使用 Google Cloud 控制台。

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

如需更新单件商品，请参阅更新商品信息。

批量更新

您可以使用导入方法来批量更新目录。您需要执行此操作和初次导入时一样请按照导入清单数据。

监控导入状况

如需监控目录注入和运行状况，请执行以下操作：

查看有关目录和上传的预览的汇总信息 Search for Retail 的目录标签页上的商品数据页面。

转到“数据”页面
评估是否需要更新清单数据以提高并解锁 数据质量页面。

详细了解如何检查搜索数据质量和查看搜索效果请参阅解锁搜索效果层级。有关请参阅目录质量指标。

转到“数据质量”页面
创建提醒，以便在数据出现问题时收到提醒请按照设置 Cloud Monitoring 提醒中的步骤进行操作。

保持目录最新对于获得优质服务非常重要结果。使用提醒来监控导入错误率，并在出现以下情况时采取措施所需的资源。

导入清单信息

从 BigQuery 导入目录数据

从 Cloud Storage 导入目录数据

以内嵌方式导入清单数据

准备工作

目录导入最佳做法

关于导入目录数据

目录导入注意事项

完全清除目录分支

将 Merchant Center 同步到 Vertex AI Search for Retail

同步 Merchant Center 账号

控制台

curl

列出您的 Merchant Center 账号关联

控制台

curl

解除与 Merchant Center 账号的关联

控制台

curl

与 Merchant Center 关联的限制

从 Merchant Center 导入目录数据

从 Merchant Center 批量导入

控制台

curl

从 BigQuery 导入目录数据

控制台

curl

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

从 Cloud Storage 导入目录数据

控制台

curl

以内嵌方式导入清单数据

curl

Java

产品项 JSON 数据格式

历史目录数据

导入历史目录数据

调用 Product.Create 方法

内嵌导入过期产品

从 BigQuery 或 Cloud Storage 导入过期产品

让您的目录保持最新状态

批量更新

监控导入状况

后续步骤

调用 `Product.Create` 方法