迁移账号管理

Accounts API 分为一系列资源，可让您更高效地管理 Merchant Center 账号，并更精确地控制账号的各个方面。

本指南介绍了主要变化，并帮助您将现有的账号管理集成从 Content API for Shopping 迁移到 Merchant API。

从一个资源到多个资源

在 Content API for Shopping 中，Account 资源是一个单体对象，其中包含从账号名称和网站网址到用户列表和商家信息的所有内容。

Merchant API 将此资源拆分为几个更小、更专注的资源。此项更改可实现更具针对性且更高效的 API 调用。例如，如果您现在只想更新商家地址，只需向 BusinessInfo 资源发出 PATCH 请求，而无需更新整个 Account 对象。

下面简要说明了 Content API for Shopping Account 资源中的概念如何映射到 Merchant API 中的新资源：

新功能

Merchant API 还引入了 Content API for Shopping 中未提供的全新账号管理功能：

  • 服务条款：使用 TermsOfService 和 TermsOfServiceAgreementState 资源以程序化方式检索和接受服务条款。
  • 通过别名访问账号：使用 providerId~accountAlias 格式访问账号，为管理多个账号的企业提供一种一致的方式来使用自己的账号标识符。

请求

下表对 Content API for Shopping 和 Merchant API 中常见账号管理任务的请求网址进行了整合比较。

请求说明 Content API for Shopping Merchant API
获取账号 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
按别名获取账号 无法直接使用 GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
列出子账号 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
创建子账号 POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
更新账号数据 PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} 针对相应资源的 PATCH 权限。例如，如需更新账号名称，请运行以下命令：PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
删除子账号 DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
声明网站所有权 POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
关联账号 POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

管理核心账号信息

Merchant API 中的 Account 资源包含 Merchant Center 账号的基本详细信息，例如名称、ID 和基本设置。

请求比较

请求说明 Content API for Shopping Merchant API
获取账号详情 GET /content/v2.1/{merchantId}/accounts/{accountId}（访问 name、adult_content 等核心属性） GET /accounts/v1/accounts/{account}
创建子账号 POST /content/v2.1/{merchantId}/accounts POST /accounts/v1/accounts:createAndConfigure
更新账号详细信息 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新核心属性） PATCH /accounts/v1/accounts/{account}
删除子账号 DELETE /content/v2.1/{merchantId}/accounts/{accountId} DELETE /accounts/v1/accounts/{account}

详细的字段比较

Content API for Shopping (Account) Merchant API (Account) 备注
id account_id 数字 ID 现在是仅限输出的字段。主要标识符是资源 name。
name account_name 账号的简明易懂的名称。
language language_code 字段名称现在为 language_code。

管理商家信息

您可以使用 BusinessInfo 资源来管理有关您商家的公开信息，例如地址和客户服务联系信息。这取代了 Content API for Shopping 中的 businessInformation 对象。

请求比较

请求说明 Content API for Shopping Merchant API
获取商家信息 GET /content/v2.1/{merchantId}/accounts/{accountId}（访问 business_information 属性） GET /accounts/v1/accounts/{account}/businessInfo
更新商家信息 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 business_information 属性） PATCH /accounts/v1/accounts/{account}/businessInfo

详细的字段比较

Content API for Shopping (business_information) Merchant API (BusinessInfo) 备注
phone_number phone 该字段现在是 phone，并使用 google.type.PhoneNumber。
customer_service.url customer_service.uri 字段名称现在为 uri。

管理首页

如需管理您商店的网站网址并执行验证和声明操作，请使用 Homepage 资源。这取代了 Content API for Shopping 中的 websiteUrl 字段和 accounts.claimwebsite 方法。

请求比较

请求说明 Content API for Shopping Merchant API
获取首页网址 GET /content/v2.1/{merchantId}/accounts/{accountId}（访问 website_url 属性） GET /accounts/v1/accounts/{account}/homepage
更新首页网址 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 website_url 属性） PATCH /accounts/v1/accounts/{account}/homepage
版权主张首页 POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST /accounts/v1/accounts/{account}/homepage:claim
取消声明首页 不可用 POST /accounts/v1/accounts/{account}/homepage:unclaim

详细的字段比较

Content API for Shopping (Account) Merchant API (Homepage) 备注
website_url uri 商店首页的网址。
无法直接使用 claimed 一个布尔值字段，如果首页已声明，则为 true。

管理用户

借助 User 资源，您可以管理哪些人可以访问 Merchant Center 账号。这会替换 Account 资源中的 users 数组。一个关键区别在于用户创建流程。在 Merchant API 中，添加用户会发送邀请。用户必须接受邀请才能访问相应账号。

请求比较

请求说明 Content API for Shopping Merchant API
列出用户 GET /content/v2.1/{merchantId}/accounts/{accountId}（访问 users 属性） GET /accounts/v1/accounts/{account}/users
创建用户 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 users 属性） POST /accounts/v1/accounts/{account}/users
更新用户 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 users 属性） PATCH /accounts/v1/accounts/{account}/users/{email}
删除用户 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 users 属性） DELETE /accounts/v1/accounts/{account}/users/{email}

详细的字段比较

Content API for Shopping（users 数组对象） Merchant API（User 资源） 备注
email_address name（格式为 accounts/{account}/users/{email}） 用户的电子邮件地址现在是资源名称的一部分。
admin、order_manager、reporting_manager 等 access_rights 现在，访问权限已整合到一个重复的枚举字段中。
不可用 state 一个仅限输出的新字段，用于指明用户是 PENDING 还是 VERIFIED。

管理账号关系和服务

在 Content API for Shopping 中，关系通过 accounts.link 进行管理。 Merchant API 引入了更明确的模型，其中包含 AccountService 和 AccountRelationship 资源，需要进行握手流程（提议和接受）。

请求比较

请求说明 Content API for Shopping Merchant API
关联账号 POST /content/v2.1/{merchantId}/accounts/{accountId}/link POST /accounts/v1/accounts/{account}/services:propose
列出关联的账号 GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks GET /accounts/v1/accounts/{account}/relationships和GET /accounts/v1/accounts/{account}/services

详细的字段比较

Content API for Shopping (AccountLink) Merchant API（AccountService、AccountRelationship） 备注
linked_account_id provider（位于 AccountService） 提供服务的账号的 ID。
service service_type（位于 AccountService） 所提供服务的类型（例如，ACCOUNT_AGGREGATION）。
status handshake.approval_state（位于 AccountService） 链接的状态（例如，PENDING、ESTABLISHED）。

账号税务设置

Content API for Shopping 中的 accounttax 服务在 Merchant API 中不可用。现在，您无需再提供美国销售税相关信息，如需了解详情，请参阅“2025 年的 Merchant Center 商品数据规范更新”。

管理商家身份

您可以使用 BusinessIdentity 资源自行声明与您的商家相关的属性。这取代了 Content API for Shopping 中的 businessIdentity 对象。

请求比较

请求说明 Content API for Shopping Merchant API
获取商家身份 GET /content/v2.1/{merchantId}/accounts/{accountId}（访问 business_identity 属性） GET /accounts/v1/accounts/{account}/businessIdentity
更新商家身份信息 PUT /content/v2.1/{merchantId}/accounts/{accountId}（更新 business_identity 属性） PATCH /accounts/v1/accounts/{account}/businessIdentity

详细的字段比较

Content API for Shopping (business_identity) Merchant API (BusinessIdentity) 备注
black_owned.self_identified（布尔值） black_owned.identity_declaration（枚举） 布尔值替换为枚举 (SELF_IDENTIFIES_AS、DOES_NOT_SELF_IDENTIFY_AS)，以便更明确地声明。这适用于所有身份属性。
include_for_promotions（布尔值） promotions_consent（枚举） 将全局布尔值替换为更具描述性的枚举 (PROMOTIONS_CONSENT_GIVEN、PROMOTIONS_CONSENT_DENIED)。

列出账号

在 Content API for Shopping 中，唯一的高级账号类型是“多客户账号 (MCA)”，它公开了一个 accounts.list 方法来列出指定多客户账号的子账号。Merchant API 中的高级账号功能更加强大，支持更广泛的账号类型和关系。为了让高级账号能够顺利迁移，Merchant API 提供了一个与 Content API for Shopping 的 accounts.list 直接对应的 accounts.listSubaccounts 方法。我们即将推出一种新的、更强大的 accounts.list 方法，可实现高级账号过滤。

请求比较

请求说明 Content API for Shopping Merchant API
列出子账号 GET /content/v2.1/{merchantId}/accounts GET /accounts/v1/accounts/{providerId}:listSubaccounts
列出所有可访问的账号 不可用 GET /accounts/v1/accounts

详细的字段比较（请求参数）

Content API for Shopping (accounts.list) Merchant API (accounts.listSubaccounts) 备注
merchant_id（路径参数） provider（路径参数） 高级账号的 ID，格式为 accounts/{account}。
max_results page_size 要返回的账号数量上限。