Gestisci ed esegui la transizione dei progetti Google Cloud

Per utilizzare l'API Merchant, devi collegare il tuo progetto Google Cloud al tuo account Merchant Center principale tramite la registrazione dello sviluppatore. Nel corso del ciclo di vita della tua integrazione, potresti dover modificare l'ID progetto Google Cloud associato al tuo account Merchant Center, gestire più progetti in ambienti diversi o eseguire la transizione dei progetti durante la migrazione dall'API Content for Shopping.

Questa guida spiega come:

  • Modifica o ruota l'ID progetto Google Cloud per un'integrazione dell'API Merchant esistente senza tempi di inattività.
  • Annullare la registrazione di un progetto Google Cloud da un account Merchant Center e registrarlo con un altro account Merchant Center.
  • Scegli ed esegui la strategia di transizione del progetto Google Cloud corretta se stai eseguendo la migrazione dall'API Content for Shopping all'API Merchant.

Prerequisiti

Prima di gestire o eseguire la transizione dei progetti Google Cloud, verifica di soddisfare i prerequisiti per la registrazione degli sviluppatori. Per maggiori dettagli, consulta la sezione Prerequisiti della guida Registrati come sviluppatore.

Regole e limitazioni principali

Quando pianifichi le modifiche ai tuoi progetti Google Cloud, tieni presente le seguenti regole:

  • Registrazione di progetti one-to-many: a un singolo account Merchant Center principale possono essere registrati contemporaneamente più progetti Google Cloud. Tuttavia, ogni progetto Google Cloud può essere registrato in un solo account Merchant Center principale alla volta. Se provi a registrare un progetto già collegato a un altro account Merchant Center, viene restituito un errore ALREADY_EXISTS (409 Conflict) con motivo DUPLICATE_PROJECT_REGISTRATION.
  • Privacy della proprietà del progetto: per motivi di sicurezza e privacy, l'assistenza di Google Shopping e dell'API Merchant non può divulgare gli indirizzi email del proprietario o dell'amministratore di un progetto Google Cloud. Se perdi l'accesso a un progetto, contatta l'assistenza Google Cloud.
  • Le estensioni per la disattivazione dell'API Content for Shopping sono specifiche per il progetto: se hai ricevuto un'approvazione per l'accesso esteso all'API Content for Shopping, l'estensione si applica solo all'ID progetto Google Cloud specifico inviato nella richiesta. Le estensioni non vengono trasferite automaticamente ai nuovi progetti Google Cloud.

Modifica l'ID progetto Google Cloud per un account API Merchant

Se utilizzi già l'API Merchant e devi trasferire l'integrazione a un nuovo progetto Google Cloud, ad esempio a causa di una riorganizzazione aziendale, di policy di rotazione delle credenziali o della perdita dell'accesso amministrativo a un progetto precedente, puoi eseguire la transizione dei progetti senza tempi di inattività. Poiché un account Merchant Center supporta più progetti Google Cloud registrati contemporaneamente, puoi registrare il nuovo progetto prima di ritirare quello precedente.

Passaggio 1: crea e configura il nuovo progetto Google Cloud

  1. Crea un nuovo progetto nella console Google Cloud. Per istruzioni dettagliate, consulta Crea un progetto Google Cloud.
  2. Attiva l'API Merchant (merchantapi.googleapis.com) nel nuovo progetto. Consulta la sezione Abilita l'API Merchant in Crea un progetto Google Cloud.
  3. Crea le credenziali di autenticazione (un service account o un ID client OAuth 2.0) nel nuovo progetto Google Cloud.
  4. Aggiungi l'indirizzo email di autenticazione (ad esempio l'indirizzo email del nuovo service account) come utente con il ruolo ADMIN nel tuo account Merchant Center principale.

Passaggio 2: registra il nuovo progetto Google Cloud

Esegui l'autenticazione utilizzando le credenziali del tuo nuovo progetto Google Cloud e chiama il metodo accounts.developerRegistration.registerGcp per collegare il nuovo progetto al tuo account Merchant Center principale. Per istruzioni dettagliate, consulta la sezione Effettua la chiamata di registrazione in Registrati come sviluppatore.

Passaggio 3: verifica i progetti Google Cloud registrati

Per verificare che i tuoi progetti Google Cloud esistenti e nuovi siano collegati al tuo account Merchant Center, chiama il metodo accounts.developerRegistration.getDeveloperRegistration:

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

Sostituisci quanto segue:

  • ACCOUNT_ID: il tuo ID Merchant Center
  • ACCESS_TOKEN: il token di autorizzazione per effettuare la chiamata API

La risposta restituisce la risorsa DeveloperRegistration con i numeri di progetto Google Cloud numerici di tutti i progetti collegati nel campo gcpIds:

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

Puoi anche verificare con quale account Merchant Center è registrato il progetto Google Cloud chiamante chiamando il metodo accounts.developerRegistration.getAccountForGcpRegistration:

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

Sostituisci quanto segue:

  • ACCESS_TOKEN: il token di autorizzazione generato utilizzando le credenziali del progetto Google Cloud che vuoi controllare

Passaggio 4: cambia il traffico e annulla la registrazione del vecchio progetto Google Cloud

  1. Aggiorna la configurazione dell'applicazione in modo che utilizzi le credenziali del nuovo progetto Google Cloud. Poiché entrambi i progetti sono registrati, i tuoi workload vengono trasferiti senza interruzioni.
  2. Una volta che tutto il traffico utilizza il nuovo progetto, puoi facoltativamente rimuovere il link al vecchio progetto autenticandoti con le credenziali del vecchio progetto Google Cloud e chiamando il metodo 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

Sostituisci quanto segue:

  • ACCOUNT_ID: il tuo ID Merchant Center

  • OLD_PROJECT_ACCESS_TOKEN: il token di autorizzazione del vecchio progetto Google Cloud per effettuare la chiamata 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);
  }
}

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"

Riassegna un progetto Google Cloud registrato a un altro account Merchant Center

Poiché un progetto Google Cloud può essere registrato in un solo account Merchant Center principale alla volta, segui questi passaggi per riassegnare un progetto esistente da un account Merchant Center (OLD_ACCOUNT_ID) a un altro (NEW_ACCOUNT_ID). Per linee guida sulla scelta dell'account Merchant Center in cui registrare il progetto, consulta Considerazioni importanti:

  1. Esegui l'autenticazione utilizzando le credenziali del progetto cloud Google Cloud che hanno accesso a OLD_ACCOUNT_ID e chiama unregisterGcp su accounts/OLD_ACCOUNT_ID/developerRegistration.
  2. Verifica che l'identità di autenticazione disponga del ruolo ADMIN su NEW_ACCOUNT_ID e che NEW_ACCOUNT_ID abbia un sito web verificato.
  3. Chiama registerGcp su accounts/NEW_ACCOUNT_ID/developerRegistration utilizzando le credenziali dello stesso progetto Google Cloud. Se NEW_ACCOUNT_ID non ha ancora un utente con il ruolo API_DEVELOPER, passa un indirizzo email utente valido nel campo della richiesta developerEmail. Le email dei service account che terminano con .gserviceaccount.com non possono essere utilizzate come developerEmail.

Esegui la transizione dei progetti Google Cloud durante la migrazione dall'API Content for Shopping

Durante la migrazione dall'API Content for Shopping all'API Merchant, potresti riscontrare limitazioni di accesso al tuo progetto Google Cloud precedente, ad esempio se le chiavi API originali sono state configurate direttamente tramite il workflow di autenticazione di Merchant Center precedente o se il proprietario del progetto originale ha lasciato la tua organizzazione.

A seconda che tu voglia mantenere il progetto esistente o utilizzarne uno nuovo per l'API Merchant, mantenendo l'API Content for Shopping nel progetto precedente, scegli una delle due opzioni seguenti.

Scegli la strategia del progetto di migrazione

Scenario È richiesto l'accesso amministrativo al vecchio progetto? API da abilitare Estensione API Content for Shopping obbligatoria per il nuovo progetto?
Opzione 1: mantieni il progetto esistente Sì (o recupero tramite l'assistenza Google Cloud) Abilita l'API Merchant nel progetto esistente (l'API Content for Shopping è già abilitata) No (l'estensione esistente sul vecchio ID progetto rimane valida)
Opzione 2: mantieni il progetto precedente per l'API Content for Shopping e utilizza un nuovo progetto per l'API Merchant No Attiva l'API Merchant nel nuovo progetto (mantieni attiva l'API Content for Shopping nel vecchio progetto) No (il vecchio progetto conserva l'estensione; il nuovo progetto chiama solo l'API Merchant)

Opzione 1: mantieni il progetto Google Cloud esistente

Scegli questa opzione se vuoi utilizzare il tuo progetto Google Cloud esistente sia per l'API Content for Shopping sia per l'API Merchant.

Prima di iniziare, verifica o recupera l'accesso al progetto esistente. Accedi alla console Google Cloud e verifica che il tuo account disponga di uno dei seguenti ruoli nel progetto esistente:

  • Proprietario (roles/owner),
  • Editor (roles/editor)
  • Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin)
  1. Abilita l'API Merchant: abilita merchantapi.googleapis.com nella libreria API Google Cloud o con il comando gcloud. Per istruzioni passo passo, consulta Configura l'autenticazione API da Merchant Center.
  2. Registra il progetto Google Cloud con Merchant Center: segui i passaggi della guida Registrati come sviluppatore per autorizzare le richieste dal tuo progetto esistente e chiama il metodo registerGcp per collegare il tuo progetto Google Cloud esistente al tuo account Merchant Center principale. Le chiavi dei service account esistenti e l'estensione API Content for Shopping approvata continuano a funzionare senza modifiche.

Opzione 2: utilizza il vecchio progetto Google Cloud per l'API Content for Shopping e un nuovo progetto per l'API Merchant

Scegli questa opzione se la tua integrazione legacy dell'API Content for Shopping è già in esecuzione con credenziali valide e un'estensione approvata nel tuo vecchio progetto Google Cloud e vuoi creare la tua nuova integrazione dell'API Merchant in un progetto Google Cloud separato e dedicato:

  1. Mantieni l'integrazione dell'API Content for Shopping nel vecchio progetto cloud: lascia i flussi di lavoro e le credenziali dell'API Content for Shopping esistenti in esecuzione nel vecchio progetto Google Cloud. Se la tua richiesta di estensione per il vecchio ID progetto è stata approvata, l'integrazione attuale dell'API Content for Shopping continuerà a funzionare fino alla scadenza estesa.
  2. Crea un nuovo progetto Google Cloud esclusivamente per l'API Merchant: crea un nuovo progetto Google Cloud, attiva merchantapi.googleapis.com e crea le credenziali (un service account o un ID client OAuth 2.0) per i nuovi workload dell'API Merchant.
  3. Registra il nuovo progetto: segui i passaggi descritti in Registrati come sviluppatore per autorizzare le richieste dal nuovo progetto e chiama il metodo registerGcp con un indirizzo email di contatto dello sviluppatore valido. Gli indirizzi email dei service account (che terminano con .gserviceaccount.com) non possono essere utilizzati come developerEmail.
  4. Esegui la migrazione dei workload in modo incrementale: sposta gradualmente le chiamate API dal vecchio progetto API Content for Shopping al nuovo progetto API Merchant prima della data di ritiro pianificata dell'API Content for Shopping (o prima della scadenza dell'estensione approvata) e ritira il vecchio progetto una volta completata la migrazione.

Caso speciale: perdita dell'accesso al vecchio progetto Google Cloud prima del completamento della migrazione

Poiché l'API Content for Shopping è stata ritirata, non è più elencata nella libreria API di Google Cloud e non può essere abilitata nei progetti Google Cloud appena creati. Di conseguenza, non puoi spostare autonomamente i workload esistenti dell'API Content for Shopping in un nuovo progetto Google Cloud.

Se non riesci più a effettuare chiamate all'API Content for Shopping dal tuo vecchio progetto (ad esempio, a causa di credenziali revocate o accesso al progetto non recuperabile):

  1. Contatta l'assistenza Google Cloud per recuperare l'accesso al tuo progetto Google Cloud esistente (Opzione 1) oppure
  2. Segui l'Opzione 2 per creare e registrare un nuovo progetto Google Cloud ed eseguire la migrazione dei workflow interessati direttamente all'API Merchant. Se riscontri un problema critico che blocca la migrazione, contatta l'assistenza dell'API Merchant.

Passaggi successivi

Avanti
Overview