管理和过渡 Google Cloud 项目

如需使用 Merchant API，您必须通过开发者注册将 Google Cloud 项目与您的主要 Merchant Center 账号相关联。在集成生命周期内，您可能需要更改与 Merchant Center 账号关联的 Google Cloud 项目 ID、跨环境管理多个项目，或在从 Content API for Shopping 迁移时转换项目。

本指南介绍了如何完成以下操作：

• 在不中断服务的情况下，更改或轮替现有 Merchant API 集成的 Google Cloud 项目 ID。
• 从一个 Merchant Center 账号中取消注册 Google Cloud 项目，并将其注册到另一个 Merchant Center 账号。
• 如果您要从 Content API for Shopping 迁移到 Merchant API，请选择并执行正确的 Google Cloud 项目转换策略。

前提条件

在管理或转换 Google Cloud 项目之前，请先验证您是否满足开发者注册前提条件。如需了解详情，请参阅注册为开发者指南的前提条件部分。

主要规则和限制

在规划对 Google Cloud 项目的更改时，请谨记以下规则：

• 一对多项目注册：一个主 Merchant Center 账号可以同时注册多个 Google Cloud 项目。不过，每个 Google Cloud 项目在任何给定时间只能注册到一个主要 Merchant Center 账号。尝试注册已与其他 Merchant Center 账号关联的项目会返回 ALREADY_EXISTS (409 Conflict) 错误，原因为 DUPLICATE_PROJECT_REGISTRATION。
• 项目所有权隐私：出于安全和隐私方面的考虑，Google 购物和 Merchant API 支持团队无法透露 Google Cloud 项目的所有者或管理员电子邮件地址。如果您失去对项目的访问权限，请与 Google Cloud 支持团队联系。
• Content API for Shopping 关停延期是针对特定项目的：如果您获得了 Content API for Shopping 的延期访问权限批准，该延期仅适用于您在请求中提交的特定 Google Cloud 项目 ID。扩展程序不会自动转移到新的 Google Cloud 项目。

更改 Merchant API 账号的 Google Cloud 项目 ID

如果您已在使用 Merchant API，并且需要将集成切换到新的 Google Cloud 项目（例如，由于组织重组、凭证轮换政策或失去对旧项目的管理员访问权限），则可以在不停机的情况下转换项目。由于 Merchant Center 账号支持同时注册多个 Google Cloud 项目，因此您可以在停用旧项目之前注册新项目。

第 1 步：创建并配置新的 Google Cloud 项目

1. 在 Google Cloud 控制台中创建一个新项目。如需查看详细说明，请参阅创建 Google Cloud 项目。
2. 在新项目中启用 Merchant API (merchantapi.googleapis.com)。请参阅创建 Google Cloud 项目中的启用 Merchant API 部分。
3. 在新 Google Cloud 云项目中创建身份验证凭证（服务账号或 OAuth 2.0 客户端 ID）。
4. 在您的主 Merchant Center 账号中，将进行身份验证的电子邮件地址（例如新服务账号电子邮件地址）添加为具有 ADMIN 角色的用户。

第 2 步：注册新的 Google Cloud 项目

使用新 Google Cloud 项目中的凭证进行身份验证，然后调用 accounts.developerRegistration.registerGcp 方法，将新项目与您的主 Merchant Center 账号相关联。如需查看详细说明，请参阅注册为开发者中的发出注册调用部分。

第 3 步：验证已注册的 Google Cloud 项目

如需确认现有 Google Cloud 项目和新 Google Cloud 项目均已关联到您的 Merchant Center 账号，请调用 accounts.developerRegistration.getDeveloperRegistration 方法：

GET https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration
Authorization: Bearer ACCESS_TOKEN

替换以下内容：

• ACCOUNT_ID：您的 Merchant Center ID
• ACCESS_TOKEN：用于进行 API 调用的授权令牌

响应会返回 DeveloperRegistration 资源，其中 gcpIds 字段包含所有关联云项目的数字 Google Cloud 项目编号：

{
  "name": "accounts/ACCOUNT_ID/developerRegistration",
  "gcpIds": [
    "123456789012",
    "987654321098"
  ]
}

您还可以通过调用 accounts.developerRegistration.getAccountForGcpRegistration 方法，验证调用方 Google Cloud 项目注册了哪个 Merchant Center 账号：

GET https://merchantapi.googleapis.com/accounts/v1/accounts:getAccountForGcpRegistration
Authorization: Bearer ACCESS_TOKEN

替换以下内容：

• ACCESS_TOKEN：使用您要检查的 Google Cloud 云项目中的凭据生成的授权令牌

第 4 步：切换流量并取消注册旧 Google Cloud 项目

1. 更新应用配置，以使用新 Google Cloud 项目中的凭据。由于两个项目都已注册，因此您的工作负载会不间断地转换。
2. 所有流量都使用新项目后，您可以选择移除旧项目关联，方法是使用旧 Google Cloud 项目凭据进行身份验证，然后调用 accounts.developerRegistration.unregisterGcp 方法：

POST https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration:unregisterGcp
Content-Type: application/json
Authorization: Bearer OLD_PROJECT_ACCESS_TOKEN

替换以下内容：

• ACCOUNT_ID：您的 Merchant Center ID

• OLD_PROJECT_ACCESS_TOKEN：旧 Google Cloud 项目中用于进行 API 调用的授权令牌

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationName;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationServiceClient;
import com.google.shopping.merchant.accounts.v1.DeveloperRegistrationServiceSettings;
import com.google.shopping.merchant.accounts.v1.UnregisterGcpRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 * This class demonstrates how to unregister the GCP project currently used to call the Merchant API
 * for a specific account.
 */
public class UnregisterGcpSample {

  public static void unregisterGcp(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    DeveloperRegistrationServiceSettings developerRegistrationServiceSettings =
        DeveloperRegistrationServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates DeveloperRegistration name to identify the DeveloperRegistration.
    // The name has the format: accounts/{account}/developerRegistration
    String name =
        DeveloperRegistrationName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .build()
            .toString();

    // Calls the API and propagates any network failures/errors.
    try (DeveloperRegistrationServiceClient developerRegistrationServiceClient =
        DeveloperRegistrationServiceClient.create(developerRegistrationServiceSettings)) {

      // Creates a request to unregister the GCP project.
      UnregisterGcpRequest request = UnregisterGcpRequest.newBuilder().setName(name).build();

      System.out.println("Sending UnregisterGcp request for: " + name);
      developerRegistrationServiceClient.unregisterGcp(request);
      System.out.println("Unregister GCP successful.");
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    unregisterGcp(config);
  }
}
UnregisterGcpSample.java

cURL

curl -X POST \
  "https://merchantapi.googleapis.com/accounts/v1/accounts/ACCOUNT_ID/developerRegistration:unregisterGcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OLD_PROJECT_ACCESS_TOKEN"

注意： 调用 unregisterGcp 后，未注册的 Google Cloud 项目最多可以继续访问 Merchant API 1 天，之后请求会被屏蔽。如果您失去了对旧 Google Cloud 项目的访问权限，并且无法调用 unregisterGcp，那么将旧项目 ID 留在 gcpIds 中不会影响您的新项目。

将已注册的 Google Cloud 项目重新分配给其他 Merchant Center 账号

由于一个 Google Cloud 项目一次只能注册到一个主 Merchant Center 账号，因此请按照以下步骤将现有项目从一个 Merchant Center 账号 (OLD_ACCOUNT_ID) 重新分配到另一个账号 (NEW_ACCOUNT_ID)。如需了解如何选择要将项目注册到哪个 Merchant Center 账号，请参阅重要注意事项：

1. 使用有权访问 OLD_ACCOUNT_ID 的 Google Cloud 云项目中的凭据进行身份验证，并在 accounts/OLD_ACCOUNT_ID/developerRegistration 上调用 unregisterGcp。
2. 验证进行身份验证的身份是否具有 NEW_ACCOUNT_ID 的 ADMIN 角色，以及 NEW_ACCOUNT_ID 是否具有经过验证的网站。
3. 使用同一 Google Cloud 项目中的凭据在 accounts/NEW_ACCOUNT_ID/developerRegistration 上调用 registerGcp。如果 NEW_ACCOUNT_ID 还没有具有 API_DEVELOPER 角色的用户，请在 developerEmail 请求字段中传递有效的用户电子邮件。以 .gserviceaccount.com 结尾的服务账号电子邮件地址不能用作developerEmail。

从 Content API for Shopping 迁移时转换 Google Cloud 项目

从 Content API for Shopping 迁移到 Merchant API 时，您可能会遇到旧版 Google Cloud 项目的访问权限限制，例如，如果您的原始 API 密钥是直接通过旧版 Merchant Center 身份验证工作流配置的，或者原始项目所有者已离开您的组织。

根据您是想保留现有项目，还是想在旧项目上保留 Content API for Shopping 的同时为 Merchant API 使用新项目，请选择以下两个选项之一。

选择迁移项目策略

场景	是否需要对旧项目的管理员访问权限？	要启用的 API	新项目是否需要 Content API for Shopping 扩展程序？
选项 1：保留现有项目	是（或通过 Google Cloud 支持团队恢复）	在现有项目中启用 Merchant API（Content API for Shopping 已启用）	否（旧项目 ID 上的现有扩展程序仍然有效）
方法 2：保留旧项目以使用 Content API for Shopping，并使用新项目以使用 Merchant API	否	在新项目中启用 Merchant API（在旧项目中保持 Content API for Shopping 处于启用状态）	否（旧项目保留其扩展程序；新项目仅调用 Merchant API）

选项 1：保留现有 Google Cloud 项目

如果您想将现有 Google Cloud 项目同时用于 Content API for Shopping 和 Merchant API，请选择此选项。

在开始之前，请验证或恢复对现有项目的访问权限。登录 Google Cloud 控制台，确认您的账号在现有项目中拥有以下任一角色：

• Owner (roles/owner)、
• Editor (roles/editor)
• Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

注意： 如果您的工程团队失去了对项目的 Owner 或管理员权限，请直接与 Google Cloud 支持联系，以获取恢复项目访问权限方面的帮助。

1. 启用 Merchant API：在 Google Cloud API 库中或使用 gcloud 命令启用 merchantapi.googleapis.com。如需查看分步说明，请参阅通过 Merchant Center 配置 API 身份验证。
2. 向 Merchant Center 注册 Google Cloud 项目：按照注册为开发者指南中的步骤，授权来自现有项目的请求，并调用 registerGcp 方法将现有 Google Cloud 项目关联到您的主要 Merchant Center 账号。您现有的服务账号密钥和已获批准的 Content API for Shopping 扩展程序将继续正常运行，无需任何更改。

方法 2：将旧 Google Cloud 项目用于 Content API for Shopping，将新项目用于 Merchant API

如果您的旧版 Content API for Shopping 集成已在旧 Google Cloud 项目中使用有效凭证和已获批准的扩展程序运行，并且您希望在单独的专用 Google Cloud 项目中构建新的 Merchant API 集成，请选择此选项：

1. 在旧项目中保留 Content API for Shopping 集成：让现有的 Content API for Shopping 工作流和凭证在旧 Google Cloud 项目中运行。如果您针对旧项目 ID 提交的延期申请已获批准，那么您当前的 Content API for Shopping 集成在延期后的截止日期之前仍可继续使用。
2. 专门为 Merchant API 创建一个新的 Google Cloud 云项目：创建一个新的 Google Cloud 云项目，启用 merchantapi.googleapis.com，并为新的 Merchant API 工作负载创建凭证（服务账号或 OAuth 2.0 客户端 ID）。
3. 注册新项目：按照注册为开发者中的步骤，授权来自新项目的请求，并使用有效的开发者联系电子邮件地址调用 registerGcp 方法。服务账号电子邮件地址（以 .gserviceaccount.com 结尾）不能用作 developerEmail。
4. 逐步迁移工作负载：在 Content API for Shopping 预定弃用日期之前（或在您获批的延期到期之前），逐步将 API 调用从旧的 Content API for Shopping 项目转移到新的 Merchant API 项目，并在迁移完成后停用旧项目。

注意： 由于您的新 Google Cloud 项目专门用于 Merchant API，因此您无需为新项目 ID 启用 Content API for Shopping 或请求关停延期。

特殊情况：在完成迁移之前失去了对旧 Google Cloud 项目的访问权限

由于 Content API for Shopping 已弃用，因此它不再列在 Google Cloud API 库中，并且无法在新创建的 Google Cloud 项目中启用。因此，您无法自行将现有的 Content API for Shopping 工作负载迁移到新的 Google Cloud 项目。

如果您无法再通过旧项目发出 Content API for Shopping 调用（例如，由于凭证被撤销或项目访问权限无法恢复）：

1. 与 Google Cloud 支持联系，以恢复对现有 Google Cloud 云项目的访问权限（选项 1），或者
2. 按照选项 2 的说明创建并注册新的 Google Cloud 云项目，然后将受影响的工作流直接迁移到 Merchant API。如果您遇到严重的迁移阻碍，请与 Merchant API 支持团队联系。

后续步骤

• 如需详细了解开发者注册要求，请参阅注册为开发者和开发者注册常见问题解答。
• 在通过 Merchant Center 配置 API 身份验证中，查看旧版凭证的行为。
• 通过开始迁移规划子 API 发布。
• 如需详细了解 Content API for Shopping 延长访问权限，请参阅请求延长迁移期限。