管理及轉換 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. 確認驗證身分在 ADMIN 上具有 NEW_ACCOUNT_ID 角色，且 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 Support聯絡，尋求專案存取權復原方面的協助。

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 整合：在舊 Google Cloud 專案中，保留現有的 Content API for Shopping 工作流程和憑證。如果舊專案 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 預定停用日期前 (或核准的延期期限到期前)，將舊 Content API for Shopping 專案的 API 呼叫逐步轉移至新的 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 的存取期限，請參閱「申請延長遷移期限」。