管理及轉換 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 專案都已連結至 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 雲端專案憑證產生的授權權杖

步驟 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 驗證工作流程設定，或原始專案擁有者已離開貴機構。

請根據您要保留現有專案，還是要為 Merchant API 使用新專案，同時在舊專案中保留 Content API for Shopping，選擇下列其中一個選項。

選擇遷移專案策略

情境	是否需要舊專案的管理員存取權？	要啟用的 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 控制台，確認您的帳戶在現有專案中具備下列任一角色：

• 擁有者 (roles/owner)、
• 編輯者 (roles/editor)
• 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)

注意： 如果工程團隊失去專案的擁有者或管理員權限，請直接與 Google Cloud 支援團隊聯絡，尋求協助以復原專案存取權。

1. 啟用 Merchant API：在 Google Cloud API 程式庫中啟用 merchantapi.googleapis.com，或使用 gcloud 指令。如需逐步說明，請參閱「透過 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，因此不需要啟用 Content API for Shopping，也不需要為新的專案 ID 申請延長關閉期限。

特殊情況：在完成遷移前，無法存取舊的 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 延長存取權，請參閱「申請延長遷移期限」。