迁移账号管理

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 资源以编程方式检索和接受服务条款。
  • 账号创建： accounts.createAndConfigure 方法现在支持创建具有关系（例如 accountManagement）、设置 alias，以及使用 user.verificationMailSettings.verificationMailMode 字段禁止电子邮件 验证，转而使用新的 accounts.verifySelf 方法进行基于 API 的验证。
  • 按别名访问账号： 使用 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

管理核心账号信息

Account resource in Merchant API contains the essential details of a Merchant Center account, such as its name, ID, and basic settings.

请求比较

请求说明 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）。

账号税务设置

Merchant API 中没有 Content API for Shopping 中的 accounttax 服务。不再需要提供美国销售税，如需了解详情，请参阅 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's 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 要返回的账号数量上限。