此页面由 Cloud Translation API 翻译。

导入目录信息

本页介绍了如何导入目录信息并使其保持最新。

此页面上的导入过程同时适用于推荐和搜索。导入数据后，这两项服务都可以使用该数据，因此如果同时使用这两种服务，则无需两次导入相同的数据。

您可以从 BigQuery 导入商品数据，也可以在请求中指定内嵌的数据。每个过程都是一次性导入，但关联 Merchant Center 除外。安排定期导入目录（理想情况下为每日）以验证您的目录是否为最新状态。

请参阅使目录保持最新状态。

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

准备工作

在开始导入目录之前，您必须：

设置项目。
创建服务账号。
将服务账号添加到本地环境。

如需了解详情，请参阅设置前提条件。

目录导入注意事项

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

BigQuery	说明	从使用 Vertex AI Search for Commerce 架构的先前加载的 BigQuery 表中导入数据。可以使用 Google Cloud 控制台或 curl 执行。
	使用时间	您的产品目录包含许多特性时。BigQuery 导入使用 Vertex AI Search for Commerce 架构，该架构具有的产品特性比其他导入选项多（包括键值对自定义特性）。您有大量数据时。BigQuery 导入没有数据限制。您已在使用 BigQuery 时。
	局限性	需要额外执行创建映射到 Vertex AI Search 商务解决方案架构的 BigQuery 表这一步骤。
Cloud Storage	说明	从加载到 Cloud Storage 存储桶中的文件导入 JSON 格式的数据。每个文件不得超过 2 GB，一次最多可导入 100 个文件。可以使用 Google Cloud 控制台或 curl 完成导入操作。使用 `Product` JSON 数据格式，该格式允许自定义属性。
	使用时间	您需要在单个步骤中加载大量数据时。
	限制	不适合频繁更新商品目录和价格的目录，因为更改不会立即生效。
内嵌导入	说明	通过调用 `Product.import` 方法导入。使用 `ProductInlineSource` 对象，该对象具有的产品目录特性比 Vertex AI Search for Commerce 架构少，但支持自定义特性。
	使用时间	如果您有非关系型平面目录数据，或者数量或价格更新的频率较高。
	限制	一次最多只能导入 100 个目录商品。但是，可以执行许多加载步骤；没有商品限制。

教程

本部分将通过视频和 shell 教程探索不同的目录导入方法。

视频教程

观看此视频，了解如何使用 Retail API 导入目录。

教程：从 BigQuery 导入目录

本教程将介绍如何使用 BigQuery 表不受限制地导入大量商品目录数据。

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

操作演示

教程：从 Cloud Storage 导入目录

本教程介绍了如何将大量商品导入到目录中。

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

操作演示

教程：以内嵌方式导入清单数据

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

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

操作演示

目录导入最佳做法

需要使用高品质数据才能生成高质量的结果。如果您的数据缺少字段或具有占位值而非实际值，则预测和搜索结果的质量将受到影响。

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

请务必仔细区分主商品和变体商品。在上传任何数据之前，请参阅商品级别。
- 在花费大量精力导入数据后更改商品级配置。系统会返回主要商品（而非变体商品）作为搜索结果或推荐内容。
- 示例：如果主要 SKU 组是 V 领衬衫，则推荐模型会返回 V 领衬衫，可能还会返回圆领衬衫和低圆领衬衫。不过，如果不使用款式/规格，且每个 SKU 都是主商品，那么每种颜色或尺码组合的 V 领衬衫都会在推荐面板上显示为不同的商品：棕色 V 领衬衫（加大码）、棕色 V 领衬衫（大码）到白色 V 领衬衫（中码）、白色 V 领衬衫（小码）。
- 只要在 collectionMemberIds[] 中包含主要商品 ID 以及款式/规格 ID，系统就可以将合集识别为一组。这会导致系统在用户事件中捕获商品合集（用户可能已购买该合集中的一件或多件商品），并将整个合集归因于购买交易。这有助于在未来的相关查询中向同一用户投放指定集合中的其他商品。
- 示例：用户之前购买过被套，因此系统会返回床单系列中的配套产品，例如枕套。
遵守商品导入限制。
- 从 Cloud Storage 批量导入数据时，每个文件的大小不能超过 2 GB。一个批量导入请求中最多可以包含 100 个文件。
- 对于内嵌导入，一次最多可导入 5000 个商品。
请确保包含必需的目录信息，并且信息正确无误。请勿使用占位值。
请添加尽可能多的可选目录信息。
确保您的事件都使用一种货币，尤其是如果您计划使用Google Cloud 控制台获取收入指标。Vertex AI Search for Commerce API 不支持每个目录使用多种货币。
使目录保持最新状态，最好每天更新一次。安排定期目录导入可防止模型质量逐渐降低。使用 Search for commerce 控制台导入目录时，您可以安排自动进行周期性导入。或者，您也可以使用 Google Cloud Scheduler 自动执行导入。
对于尚未导入的商品项，请勿记录其用户事件。
导入目录信息后，请查看项目的错误报告和日志记录信息。如果您发现的错误不止几个，请检查这些错误，并修复导致错误的所有流程问题。

Vertex AI Search 商务解决方案的数据注入流水线同时包含产品目录和用户事件数据。此数据流通过反馈机制为可靠的模型训练和持续评估奠定了基础。准确完整的数据注入不仅是前提条件，也是保持底层模型适应性的必要持续性流程。这反过来又会直接影响搜索结果的质量和相关性，从而带来丰厚的回报。

在设计商业搜索解决方案时，请考虑以下数据注入最佳实践。

批量导入、实时流式传输，还是两者兼而有之？

Vertex AI Search 商务解决方案提供了两种主要的目录注入方法：

批量导入
实时流式处理

这种双重方法可满足各种客户后端的不同架构需求。您无需专门选择一种方法；可以采用混合提取模式，根据具体要求同时使用批量导入和流式更新。

如果需要一次性添加、删除或更新数千种商品，批量导入功能非常适合。相比之下，如果需要持续更新相对较少的产品，实时流式插入效果会更好。选择哪种方法取决于产品目录的性质、更新频率以及后端系统的总体架构。

批量导入功能支持三种不同的数据源：

BigQuery：BigQuery 可快速修改目录数据，支持在导入期间指定分区日期，并允许通过 SQL 查询高效地转换数据。
Google Cloud Storage：Cloud Storage 要求遵循特定格式（例如 JSON）和文件限制。用户负责管理存储桶结构、文件分块和导入流程的其他方面。此外，直接在 Cloud Storage 中修改目录可能很麻烦，虽然可能具有成本效益，但不如其他方法灵活。
内嵌数据：对于大型目录，由于大小限制，内嵌导入可能不是最具可伸缩性的选项。仅在进行小规模更新或实验性测试时使用。

对于在短时间内以固定间隔进行大量产品目录更新（数千种产品发生变化、添加或删除）的场景，批量导入和实时流式传输相结合的方法非常有效。在 BigQuery 或 Cloud Storage 中暂存更新，并定期（例如每隔一到两小时）执行增量批量导入。此方法可高效管理大规模更新，同时最大限度地减少中断。

对于较小、更新频率较低或需要在目录中立即反映的更新，请使用实时流式传输 API。在混合方法中，实时流式传输可以弥补批量导入之间的空白，确保目录始终保持最新状态。此策略可在进行单个 REST API 调用（用于修补商品）和执行批量更改之间取得平衡，从而优化 Vertex AI Search for Commerce 商品目录管理的效率和响应速度。

目录管理的分支策略

在单个分支中维护统一的目录，而不是在多个分支中维护不同的目录。此实践可简化目录更新，并降低分支切换期间出现不一致的风险。

以下常见的分支策略可有效用于目录管理。

单分支更新

将一个实时分支指定为默认分支，并在目录发生更改时持续更新该分支。对于批量更新，请在流量较低的时段使用导入功能，以最大限度地减少中断。使用流式 API 进行较小的增量更新，或将它们分批处理成较大的块以进行常规导入。

分支切换

您可以通过以下几种方式管理不同的分支：

使用分支进行预演和验证：
- 一些商务网站工程师会选择分支切换方法，即在非实时分支中更新目录，然后在准备好投入生产时将其设为默认（实时）分支。这样一来，您就可以提前准备第二天的目录。您可以使用批量导入或流式传输方式将更新内容添加到非实时分支，确保在流量较低时实现无缝过渡。
- 选择哪种策略取决于您的具体要求、更新频率和基础架构设置。不过，无论选择哪种策略，在单个分支中维护统一的目录对于在 Vertex AI Search for Commerce 中获得最佳性能和一致的搜索结果至关重要。
使用分支进行备份：
- 单个实时分支专注于持续注入和处理商品更新，以使 Vertex AI Search 商务解决方案索引近乎实时地保持最新状态。
- 另一个分支侧重于在 Retail Search 中创建转换后数据的每日快照，以在分支 0 出现数据损坏或问题时充当可靠的后备机制。
- 第三个分支侧重于创建转换后日期的每周快照。这样，客户就可以在不同的分支中分别拥有一天前的备份和一周前的备份。

完全清除目录分支

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

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

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

前往 Search for Commerce 控制台中的数据页面。

前往“数据”页面
从分支名称字段中选择目录分支。
在分支名称字段旁边的三点状菜单中，选择清除分支。

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

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

系统会启动一个长时间运行的操作，以从目录分支中清除数据。清除操作完成后，活动状态窗口中的产品目录列表会显示清除状态。

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

Vertex AI Search 商务解决方案中的商品目录更新

本部分介绍了如何通过定期更新商品目录来优化 Vertex AI Search 商务解决方案的性能。

实时流式传输

对于库存信息（价格、供应情况）和商店级详细信息（包括履单状态和商店特定价格）等动态数据，实时流式传输是 Vertex AI Search for Commerce 中的唯一选择。
之所以会出现这种区别，是因为与相对静态的商品目录数据相比，库存波动频率较高。商品供应情况每天可能会多次发生变化，而说明或属性则相对保持不变。
零售地点的数量越多，商店级更新的频率就越高。

异步更新

为了适应这种快速的变化，Vertex AI Search for Commerce 采用异步库存更新，使用返回作业 ID 的 API。
在轮询并确认作业状态之前，更新过程不会被视为完成，这可能会导致几秒到几分钟的短暂延迟。

无序更新

此系统的一项显著功能是能够在将相应商品纳入目录之前更新商品目录信息。这解决了零售商中库存和商品数据流水线独立运行的常见情况，有时会导致库存信息在商品目录更新之前就可供使用。更新商品目录时，请使用 allowMissing 选项来处理商品目录与商品之间的无序更新。
通过允许在目录注入之前更新商品目录，Vertex AI Search for Commerce 可以适应这些流水线差异，确保即使是新推出的产品也能提供准确的商品目录数据。
不过，商品目录信息会保留 24 小时，如果在此时间范围内未提取到匹配的商品，则会清除这些信息。此机制可确保数据一致性，并防止过时的商品目录信息持续存在于系统中。

Vertex AI Search 商务解决方案中用于进行可靠 A/B 测试的商品目录预检

本部分介绍了如何对产品目录数据运行预检。

确保目录更新对等性一致

为了在 Vertex AI Search 商务解决方案中进行 A/B 测试，必须严格保持旧版（对照）目录与 Vertex AI Search 商务解决方案（测试）目录之间的一致性。两者之间的任何不平衡都可能会对 A/B 测试产生负面影响，导致观测结果出现偏差，并可能导致结果无效。例如，商品库存状况、价格不一致，甚至细微的属性差异都可能会在测试数据中引入意外的偏差。
为缓解此风险，必须为控制目录和测试目录设计并行更新流程，尽可能避免顺序更新。目标是尽可能延长两个目录保持同步的时间。另一方面，串行更新可能会导致一个车道或另一个车道出现延迟。这些延迟可能会导致目录暂时不一致，即某个产品在一个目录中显示为有货，但在另一个目录中显示为无货。或者，新添加的商品在一个目录中显示的时间早于另一个目录。这种差异会显著影响用户行为、点击次数和购买次数，最终导致比较不公平，并使 A/B 测试结果不准确。
通过优先处理并行更新并努力实现一致的目录对等性，零售商可以确保在 Vertex AI Search for Commerce 中进行 A/B 测试时，所有商品都处于同一起跑线上。这种方法可以对测试结果进行公正的分析，从而获得更可靠的数据洞见，并做出更明智的决策。

实现目录数据对等

电子商务搜索模型对产品的理解程度和准确性取决于其底层商品目录信息的丰富程度和质量。目录中的商品数据越全面，模型就越能有效地理解和分类商品。
因此，在准备进行 A/B 测试时，务必要确保上传到旧版（对照组）目录和 Vertex AI Search for Commerce（测试组）目录的商品数据完全相同。这两个环境中的产品信息如有任何差异，都可能会严重影响 A/B 测试结果。
例如，如果旧版搜索引擎的商品目录比 Vertex AI Search for Commerce 的商品目录更丰富或更广泛，则会造成不公平的优势。Vertex AI Search for Commerce 商品目录中缺少的信息对于了解和分类商品至关重要，可能会导致搜索结果不准确，并导致效果比较产生误导。使用外部工具检测此类差异可能非常困难，通常需要对两个目录进行细致的手动检查。
通过认真确保两个目录包含相同的产品数据，且详细程度相同，零售商可以在 Vertex AI Search for Commerce 中为 A/B 测试创造公平的竞争环境。这种方法有助于公平公正地比较这两个搜索引擎，从而准确评估它们各自的性能和功能。

灾难恢复计划

制定周全的灾难恢复计划可确保您的商务搜索功能保持正常运行并及时响应，从而最大限度地减少对客户体验和收入的影响。无论根本原因是什么，此方案都应能快速恢复目录，以解决目录和用户事件提取流水线的潜在故障。

使用 BigQuery 进行数据暂存可在灾难恢复方面提供显著优势。如果 Vertex AI Search 商务解决方案中的当前目录或用户事件数据与 BigQuery 中存储的最新快照没有显著差异，则调用导入 API 可以启动快速恢复。这种方法可最大限度地缩短停机时间，并确保搜索功能保持正常运行。

反之，如果 BigQuery 未集成到数据流水线中，则必须有替代机制来快速从已知良好状态重新加载目录。这些机制可能涉及备份系统、数据复制或其他故障切换策略。

通过将这些灾难恢复注意事项纳入 Vertex AI Search 商务解决方案架构中，您可以增强系统的稳健性，即使在遇到意外中断时也能保持业务连续性。

规划高可用性

将产品目录上传到 Vertex AI Search 时，请务必考虑不同 Google Cloud 服务如何处理区域性问题，以便设计出弹性数据注入流水线。

如需使用 Dataflow 构建具备灾难恢复功能的提取流水线，请使用以下设计之一在多个区域中部署作业：

主动/主动：多个区域中的 Dataflow 实例同时主动处理数据。
主动/被动：一个区域中的 Dataflow 实例处于活跃状态，而其他区域中的实例则保持待机状态。

下面介绍了如何使用 Pub/Sub 和 Dataflow 实现这些设计：

全球服务：某些服务（例如 Pub/Sub）在全球范围内运行。 Google Cloud 会根据其特定的服务等级协议 (SLA) 管理其可用性。
区域化服务：您可能用于将数据转换并注入 Vertex AI Search 的其他服务（例如 Dataflow）是区域化服务。您需要负责配置这些组件，以实现高可用性和灾难恢复。

例如，在利用 BigQuery 持久保留数据时，可将其配置为多区域，以便 Google Cloud自动处理数据冗余和可用性。同样，在使用 Cloud Storage 时，可以将其配置为多区域。

主动/主动设计

主动/主动设计使用 Pub/Sub 消息属性和订阅过滤条件，以确保每个消息都由特定区域中的活跃 Dataflow 作业处理一次。

添加消息属性：向 Pub/Sub 主题发布消息（例如商品更新）时，请添加一个属性来指明目标区域。例如：
- region：us-central1
- region：us-east1
配置订阅过滤条件：为每个区域级 Dataflow 流水线配置其 Pub/Sub 订阅，以使用消息过滤条件仅拉取与其区域匹配的消息。例如，us-central1 Dataflow 作业的订阅将具有 attributes.region = "us-central1" 等过滤条件。
故障切换：如果某个区域变得不可用，请更新上游发布系统，以使用健康区域的属性标记所有新消息。这会将消息处理重新路由到故障切换区域中的 Dataflow 实例。

架构中使用的多个组件可以配置为默认多区域。例如，当利用 BigQuery 持久保留数据时，可以将其配置为多区域，以便 Cloud Storage 自动处理数据冗余和可用性。同样，在使用 Cloud Storage 时，也可以将其配置为多区域。

主动/被动设计

此设计方案涉及在任何时间都只让一个区域级 Dataflow 流水线主动从 Pub/Sub 中提取消息。

附加一个订阅：确保仅附加了有效区域的 Dataflow 作业的 Pub/Sub 订阅，并且该订阅正在拉取消息。应创建被动区域中 Dataflow 作业的订阅，但这些订阅应保持分离状态。
故障切换：如果有效区域发生故障，请手动或以编程方式执行以下操作：
- 分离与失败区域的 Dataflow 作业关联的 Pub/Sub 订阅。
- 附加与被动（备用）区域中的 Dataflow 作业关联的 Pub/Sub 订阅。

这样会将消息处理负载转移到新激活的区域。

弹性和取证

在数据注入的设计中使用 BigQuery 可以提高处理弹性，并创建用于取证和调试的功能。直接通过 patch 和 addLocalInventory API 提取的产品和库存意味着，当数据发送到 Vertex AI Search for Commerce 时，不会留下任何产品和库存更新的痕迹。用户可能想知道为什么商品未按预期显示。使用 BigQuery 构建包含完整数据历史记录的临时区域有助于进行此类调查和调试。

参考架构

在此架构中，数据注入通常会包含原始阶段、整理阶段和使用阶段，所有这些阶段都基于 BigQuery 构建。系统会使用 Dataflow 在各个阶段之间移动数据，并使用云工作流编排所有这些操作以实现自动化：

系统会按原样获取原始数据，并添加时间标记以保留历史记录。此数据未发生变化，因此客户会将其视为真实来源。
然后，系统会将数据转换为精选阶段，并再次添加时间标记。这样，客户就能知道何时进行了转换以及是否发生了任何故障。
最后，系统会在消费阶段使用之前为精选数据添加的时间标记，在精选数据中创建视图。这样，客户就可以准确了解哪些转换后的数据最终应注入到 Vertex AI Search 商务解决方案中。

分支 0、分支 1 和分支 2 分别用作实时备份、前一天备份和一周前备份分支。直接注入到分支 0 中的数据每天会汇总并编入分支 1 的索引，每周会汇总并编入分支 2 的索引。这样一来，任何数据损坏都可以回滚，从而提高业务连续性和系统弹性。

此外，由于全球 BigQuery 数据集中保留了数据的完整历史记录和沿袭信息，因此可以进行分析和调试。

规划目录提取的特殊情况

在 Vertex AI Search 商务解决方案中建立目录注入的核心机制后，主动方法包括评估这些机制在各种极端情况下的恢复能力。虽然其中一些场景可能与您的具体业务需求并不直接相关，但将它们纳入后端设计中可以提供宝贵的未来保障。

此准备步骤包括检查数据流水线处理意外情况或极端情况的能力，确保其稳健性和对不断变化的需求的适应性。通过预测潜在的挑战并主动应对，您可以减少未来的中断，并保持产品数据顺畅地流入零售搜索系统。

为此，应构建 Dataflow 逻辑，使其：

验证原始数据的每个项是否与适当的架构匹配。应预先确定原始数据的合约，并且应始终根据合约检查每个数据元素。如果验证失败，原始数据元素应带有时间标记，并保留在 BigQuery 失败的原始表中，其中包含用于取证的实际错误。

此类失败的示例包括：
- 某个不属于合同的属性突然出现在原始数据元素中。
- 原始数据元素中缺少某个必需属性。
验证原始数据的每个项是否可以转换为 Vertex AI Search for Commerce 格式。Vertex AI Search 商务解决方案在注入商品时需要提供一些强制性字段。现在，应再次检查原始数据的每个元素是否可以成功转换为 Vertex AI Search for Commerce 架构格式。如果转换失败，原始数据元素应带有时间标记，并保留在 BigQuery 失败的精选表中，其中包含可帮助进行取证的实际错误消息。

此类失败的示例包括：
- 价格等特定属性无法格式化为数字，因为原始数据元素是字母数字。
- 商品名称完全缺失。

此示例展示了一个示例 BigQuery 表架构，用于保留所有失败情况以进行调试：

查看 BigQuery 表架构示例

[
    {
      "mode": "REQUIRED",
      "name": "ingestedTimestamp",
      "type": "TIMESTAMP"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadString",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadBytes",
      "type": "BYTES"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "key",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "value",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "attributes",
      "type": "RECORD"
    },
    {
      "mode": "NULLABLE",
      "name": "errorMessage",
      "type": "STRING"
    },
    {
      "mode": "NULLABLE",
      "name": "stacktrace",
      "type": "STRING"
    }
  ]

压力测试和可伸缩性

通过压力测试和可伸缩性来为高流量活动和增长做好准备。

高流量活动

节假日等高流量事件对数据注入流水线提出了重大挑战。库存更新（包括库存水平和价格）的激增以及商品属性的潜在变化需要强大的基础设施。请务必评估您的提取系统是否可以处理这种增加的负载。模拟负载测试可复制流量高峰模式，从而发现瓶颈并确保在这些关键时期顺利运行。

闪购

限时抢购活动因持续时间短且库存波动快而带来独特的挑战。确保实时同步广告资源对于防止搜索结果与实际可用性之间出现差异至关重要。否则，可能会导致客户体验不佳，例如热门商品实际上已售完，但却显示为有货，反之亦然。此外，在限时抢购期间的价格变动可能会对商品排名产生重大影响，这凸显了在搜索索引中准确及时更新价格的必要性。

扩大目录范围

业务增长或产品线扩展可能会导致商品清单中的商品数量大幅增加，例如增加 5 倍或 10 倍。您的提取架构必须具有可伸缩性，才能无缝适应这种增长。这可能需要重新审视整个 ETL（提取、转换、加载）流水线，尤其是在引入新的数据源或产品信息格式时。

通过主动应对这些潜在情况，您可以确保 Vertex AI Search for Commerce 提取流水线即使在突然出现流量高峰、闪购或目录大幅增长的情况下，也能保持稳健、可伸缩和响应迅速。这种主动式方法可确保搜索结果的准确性和可靠性，从而有助于提升用户体验并推动业务成功。

应评估数据注入流水线的性能，并针对以下指标形成基准：

发布和注入整个目录和广告资源数据需要多长时间？在 BFCM 期间，整个目录的价格可能会发生显著变化，因此可能需要临时执行此操作。
单个商品更新需要多长时间才能反映出来？
系统可以处理的商品和目录更新的最高速率是多少？

瓶颈

评估并确定流水线是否能够正确地向上和向下扩展。
确定实例数上限是否过高或过低。
通过检查 HTTP 代码 429，确定系统是否受到 Vertex AI Search 商务解决方案的速率限制。
确认是否需要提高某些 API 配额以降低速率限制。

商品目录提取的商品数据结构

本部分介绍如何准备商品数据以进行目录提取。

主要产品

主商品充当容器，用于对款式/规格商品进行分组，并充当搜索网格中的条目。仅为主要商品指定在不同款式之间共用的通用属性。其中包括：

主要商品 ID
商品 ID（与主要商品 ID 相同）
标题
说明

如需了解详情，请参阅商品属性简介。

多款式产品

不同款式/规格的商品会沿用主商品的通用属性，但也可以指定唯一值。

必需属性包括：

为主要商品指定的所有属性（商品名、说明）。价格、商品名和说明可以与主商品不同。
具体的款式/规格属性（颜色、尺寸和其他相关商品款式/规格）。

如需了解详情，请参阅商品属性简介。

属性检索

检索过程会考虑主要商品和不同款式的商品的所有可搜索属性。

搜索结果中的款式/规格匹配

款式/规格匹配（例如蓝色连衣裙）会根据预定义的款式/规格属性（例如颜色和尺寸）过滤结果。搜索结果最多会为每件主要商品返回 5 个匹配的款式。

将 Merchant Center 与 Vertex AI Search for Commerce 同步

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

如需在 Merchant Center 和 Vertex AI Search 商务解决方案之间持续同步，您可以将您的 Merchant Center 账号与 Vertex AI Search 商务解决方案相关联。

为 Vertex AI Search for Commerce 设置 Merchant Center 同步时，您必须在 Merchant Center 中拥有 Admin IAM 角色。虽然标准访问权限角色允许您读取 Merchant Center Feed，但当您尝试将 Merchant Center 与 Vertex AI Search for Commerce 同步时，系统会显示一条错误消息。因此，您需要先升级自己的角色，然后才能成功将 Merchant Center 与 Vertex AI Search for Commerce 同步。

关联 Merchant Center 账号

Vertex AI Search 商务解决方案与 Merchant Center 账号关联后，对 Merchant Center 账号中商品数据的更改会在几分钟内在 Vertex AI Search 商务解决方案中自动更新。如果您希望阻止 Merchant Center 将更改同步到 Vertex AI Search for commerce，可以解除与 Merchant Center 账号的关联。

解除与 Merchant Center 账号的关联不会删除 Vertex AI Search 商务解决方案中的商品。如需删除导入的商品，请参阅删除商品信息。

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

同步您的 Merchant Center 账号

Cloud 控制台

前往 Search for Commerce 控制台中的数据页面。

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

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

curl

检查本地环境中的服务账号是否有权访问 Merchant Center 账号和 Vertex AI Search for commerce。如需查看哪些账号有权访问您的 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": [
    {"dataSourceId": DATA_SOURCE_ID_1}
    {"dataSourceId": DATA_SOURCE_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 账号的 ID。
- BRANCH_ID：要与其建立关联的分支的 ID。接受的值为“0”、“1”或“2”。
- LANGUAGE_CODE：（可选）要导入的商品的双字母语言代码。如 Merchant Center 中商品的 Language 列所示。如果未设置，则导入所有语言。
- FEED_LABEL：（可选）您要导入的产品的商品 Feed 标签。您可以在 Merchant Center 中商品的商品 Feed 标签列中查看 Feed 标签。如果未设置，则导入所有 Feed 标签。
- FEED_FILTERS：（可选）将从中导入商品的主要 Feed 的列表。如果不选择 Feed，则表示共享所有 Merchant Center 账号 Feed。您可以在 Content API datafeeds 资源中找到这些 ID，也可以访问 Merchant Center，选择一个 Feed，然后从网站网址的 afmDataSourceId 参数中获取 Feed ID。例如 mc/products/sources/detail?a=MERCHANT_CENTER_ID&afmDataSourceId=DATA_SOURCE_ID。

如需查看关联的 Merchant Center，请前往“Search for commerce”控制台的数据页面，然后点击页面右上角的 Merchant Center 按钮。系统随即会打开关联的 Merchant Center 账号面板。您还可以通过此面板添加其他 Merchant Center 账号。

请参阅查看目录的汇总信息，了解如何查看已导入的商品。

列出 Merchant Center 账号关联

Cloud 控制台

前往 Search for Commerce 控制台中的数据页面。

前往“数据”页面
点击页面右上角的 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 商务解决方案。此过程不会删除 Vertex AI Search for Commerce 中已上传的任何产品。

Cloud 控制台

前往 Search for Commerce 控制台中的数据页面。

前往“数据”页面
点击页面右上角的 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 账号中的商品/服务数量。
对于与 Merchant Center 账号关联的分支，使用 API 方法的所有商品修改都将被停用。对这些分支中的产品目录数据所做的任何更改都必须使用 Merchant Center 进行。然后，这些更改会自动同步到 Vertex AI Search for Commerce。
使用 Merchant Center 关联的分支不支持集合商品类型。
为了确保数据准确性，您的 Merchant Center 账号只能与空目录分支关联。如需从目录分支中删除商品，请参阅删除商品信息。

从 BigQuery 导入目录数据

如需从 BigQuery 以正确的格式导入目录数据，请使用 Vertex AI Search for Commerce 架构以正确的格式创建 BigQuery 表，并加载空表和目录数据。然后，将您的数据上传到 Vertex AI Search for Commerce。

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

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

操作演示

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

如果您的 BigQuery 数据集位于其他项目中，请配置所需的权限，以便 Vertex AI Search for commerce 可以访问 BigQuery 数据集。了解详情。
将目录数据导入 Vertex AI Search 商务解决方案。
Cloud 控制台
1. 前往 Search for Commerce 控制台中的数据页面。
  
  前往“数据”页面
2. 点击导入以打开导入数据面板。
3. 选择商品清单。
4. 选择 BigQuery 作为数据源。
5. 选择您要将目录上传到的分支。
6. 选择零售产品目录架构。这是 Vertex AI Search for Commerce 的商品架构。
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 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"
  您可以使用 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 commerce 服务属于不同的项目，要设置访问权限，请完成以下步骤。

在 Google Cloud 控制台中打开 IAM 页面。

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

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

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

商品架构

从 BigQuery 导入目录时，请使用以下 Vertex AI Search for commerce 商品架构创建一个格式正确的 BigQuery 表，并将其与您的目录数据一起加载。然后，导入目录。

查看 Vertex AI Search 商务解决方案产品架构

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

从 Cloud Storage 导入目录数据

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

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

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

确保 Vertex AI Search for Commerce 服务账号有权读写存储桶。

Vertex AI Search for commerce 服务账号在 Google Cloud 控制台的 IAM 页面中列出，名称为 Retail 服务账号。将账号添加到存储桶权限时，请使用服务账号的标识符（类似于电子邮件地址，例如 service-525@gcp-sa-retail.iam.gserviceaccount.com）。
导入目录数据。
Cloud 控制台
1. 前往 Search for Commerce 控制台中的数据页面。
  
  前往“数据”页面
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 对象指定目录数据，可以内嵌方式将目录信息导入到 Retail API 中。

在一行中提供整个商品。每件商品应独占一行。

如需查看 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 字段设置为过去的时间戳，则此产品将被视为历史产品。为了避免影响推荐，请将产品可用性设置为 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 commerce Data”（搜索商业数据）页面的目录标签页中，您可以查看有关目录的汇总信息并预览已上传的商品。

转到“数据”页面
在数据质量页面上，评估您是否需要更新目录数据，以提高搜索结果质量并解锁搜索效果层级。

如需详细了解如何检查搜索数据质量和查看搜索效果层级，请参阅解锁搜索效果层级。如需查看本页面上提供的目录指标的摘要，请参阅目录质量指标。

前往“数据质量”页面
如需创建提醒，以便在数据上传出现问题时收到通知，请按照设置 Cloud Monitoring 提醒中的步骤操作。

为了获得高质量的结果，保持目录保持最新至关重要。使用提醒来监控导入错误率，并在需要时采取措施。

导入目录信息 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

目录导入注意事项

教程

视频教程

教程：从 BigQuery 导入目录

教程：从 Cloud Storage 导入目录

教程：以内嵌方式导入清单数据

目录导入最佳做法

批量导入、实时流式传输，还是两者兼而有之？

目录管理的分支策略

单分支更新

分支切换

完全清除目录分支

Vertex AI Search 商务解决方案中的商品目录更新

实时流式传输

异步更新

无序更新

Vertex AI Search 商务解决方案中用于进行可靠 A/B 测试的商品目录预检

确保目录更新对等性一致

实现目录数据对等

灾难恢复计划

规划高可用性

主动/主动设计

主动/被动设计

弹性和取证

参考架构

规划目录提取的特殊情况

压力测试和可伸缩性

高流量活动

闪购

扩大目录范围

瓶颈

商品目录提取的商品数据结构

主要产品

多款式产品

属性检索

相关性评分

搜索结果中的款式/规格匹配

将 Merchant Center 与 Vertex AI Search for Commerce 同步

关联 Merchant Center 账号

同步您的 Merchant Center 账号

Cloud 控制台

curl

列出 Merchant Center 账号关联

Cloud 控制台

curl

解除 Merchant Center 账号关联

Cloud 控制台

curl

与 Merchant Center 关联的限制

从 BigQuery 导入目录数据

Cloud 控制台

curl

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

商品架构

查看 Vertex AI Search 商务解决方案产品架构

从 Cloud Storage 导入目录数据

Cloud 控制台

curl

以内嵌方式导入目录数据

curl

Java

产品项 JSON 数据格式

历史目录数据

导入历史目录数据

调用 Product.Create 方法

内嵌导入过期产品

从 BigQuery 或 Cloud Storage 导入过期产品

使目录保持最新状态

批量更新

监控导入运行状况

后续步骤

导入目录信息

调用 `Product.Create` 方法