Distribuzione in produzione

Questa guida ti aiuta a scegliere e configurare l'approccio di autenticazione appropriato per il deployment di produzione dell'API Data Manager.

Scegli lo scenario di deployment

Seleziona l'approccio di autenticazione che corrisponde all'architettura dell'applicazione e all'ambiente di deployment:

• Workload in Google Cloud: per i workload automatizzati (come pipeline ETL, job batch o servizi di backend) in esecuzione su Compute Engine, Cloud Run, Cloud Functions o GKE, utilizza le credenziali predefinite dell'applicazione (ADC) con un service account collegato o Workload Identity Federation per GKE.
• Workload esterni a Google Cloud: Per i workload automatizzati eseguiti on-premise o su altri provider cloud, utilizza le credenziali predefinite dell'applicazione (ADC) con la federazione delle identità per i workload o una chiave del service account.
• Agisci per conto degli utenti: per piattaforme di terze parti e applicazioni multi-tenant che gestiscono account per utenti esterni (ad esempio gli inserzionisti che si registrano sulla tua piattaforma), utilizza il flusso server web OAuth 2.0 con token di aggiornamento per utente o link partner se sei un partner di dati approvato.

Per indicazioni generali sull'autenticazione di Google Cloud, consulta l'albero decisionale per l'autenticazione di Google Cloud.

Workload in Google Cloud

Quando viene eseguito su Google Cloud, collega un service account direttamente alla risorsa di calcolo o configura Workload Identity Federation for GKE. Le librerie client utilizzano le ADC per recuperare automaticamente le credenziali temporanee per il service account senza richiedere file di credenziali o variabili di ambiente.

Compute Engine

Quando crei un'istanza di macchina virtuale, specifica il service account e l'ambito dell'API Data Manager in modo che i token di accesso restituiti dal server di metadati dell'istanza includano l'autorizzazione richiesta.

gcloud compute instances create INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

Per aggiornare gli ambiti o il service account su un'istanza esistente, arresta l'istanza, aggiorna la configurazione con set-service-account e riavvia l'istanza:

gcloud compute instances stop INSTANCE_NAME

gcloud compute instances set-service-account \
  INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

gcloud compute instances start INSTANCE_NAME

Cloud Run

Specifica il service account durante il deployment del servizio:

gcloud run deploy SERVICE_NAME \
  --image="IMAGE_URL" \
  --service-account="SERVICE_ACCOUNT_EMAIL"

Cloud Functions

Specifica il service account durante il deployment della funzione:

gcloud functions deploy FUNCTION_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --runtime="RUNTIME" \
  --trigger-http

GKE

1. Abilita Workload Identity Federation for GKE sul cluster.

2. Associa il service account Kubernetes (KSA) al service account Google (GSA):

   # Define the Kubernetes service account member:
   KUBERNETES_MEMBER="serviceAccount:PROJECT_ID.svc.id.goog[KUBERNETES_NAMESPACE/KUBERNETES_SA_NAME]"
   
   # Grant the Workload Identity User role to the Kubernetes service account:
   gcloud iam service-accounts add-iam-policy-binding \
     SERVICE_ACCOUNT_EMAIL \
     --role="roles/iam.workloadIdentityUser" \
     --member="${KUBERNETES_MEMBER}"
   

3. Annota il service account Kubernetes con l'email del service account Google:

   kubectl annotate serviceaccount KUBERNETES_SA_NAME \
     --namespace="KUBERNETES_NAMESPACE" \
     iam.gke.io/gcp-service-account="SERVICE_ACCOUNT_EMAIL"
   

4. Specifica il service account Kubernetes nella specifica del pod:

   apiVersion: v1
   kind: Pod
   metadata:
     name: data-manager-worker
   spec:
     serviceAccountName: KUBERNETES_SA_NAME
     containers:
     - name: worker
       image: IMAGE_URL
   

Verificare l'accesso a IAM e all'account

Prima di eseguire il deployment dell'applicazione di produzione, verifica che il service account disponga delle autorizzazioni necessarie:

1. Autorizzazioni IAM Google Cloud: concedi al service account il ruolo Consumer Service Usage (roles/serviceusage.serviceUsageConsumer) nel progetto Google Cloud in cui è abilitata l'API Data Manager.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/serviceusage.serviceUsageConsumer"
   

2. Accesso all'account di destinazione: concedi al service account l'accesso richiesto ai tuoi account di destinazione. Per istruzioni passo passo, vedi Configurare l'accesso all'account.

Workload al di fuori di Google Cloud

Quando esegui il codice nei data center on-premise o su altri provider cloud, scegli uno dei seguenti meccanismi di autenticazione:

• Federazione delle identità per i workload (consigliata): configura la federazione delle identità per i workload per consentire alla tua applicazione di scambiare le credenziali del tuo provider di identità esterno con credenziali Google Cloud di breve durata senza gestire le chiavi dei service account. Genera un file di configurazione delle credenziali e fornisci le credenziali predefinite dell'applicazione utilizzando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

• Chiavi del service account (fallback): se la federazione delle identità per i workload non è disponibile, crea una chiave del service account e forniscila ad ADC utilizzando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

  Attenzione :le chiavi dei service account sono credenziali di lunga durata che presentano un rischio per la sicurezza se vengono divulgate o gestite in modo errato. Segui le best practice per la gestione delle chiavi degli account di servizio, archivia le chiavi in un gestore dei secret sicuro, limita le autorizzazioni dei file e ruota regolarmente le chiavi.

Imposta GOOGLE_APPLICATION_CREDENTIALS

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso assoluto del file di configurazione delle credenziali della federazione delle identità per i carichi di lavoro o del file della chiave del service account in modo che le librerie client possano individuare automaticamente le credenziali utilizzando ADC.

Linux / macOS

Imposta la variabile di ambiente nel profilo della shell o nello script di deployment:

export GOOGLE_APPLICATION_CREDENTIALS=\
  "/path/to/credentials.json"

Windows (PowerShell)

Imposta la variabile di ambiente in PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS = `
  "C:\path\to\credentials.json"

Docker / Container

Monta il file delle credenziali nel container e imposta la variabile di ambiente:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

oppure passa la variabile di ambiente in fase di runtime:

HOST_CREDS="/host/path/credentials.json"
docker run -e GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json" \
  -v "${HOST_CREDS}:/secrets/credentials.json:ro" \
  IMAGE_NAME

Kubernetes

Monta le credenziali come secret e fai riferimento a queste nell'ambiente del pod:

apiVersion: v1
kind: Pod
metadata:
  name: data-manager-worker
spec:
  containers:
  - name: worker
    image: IMAGE_URL
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: "/etc/secrets/google/credentials.json"
    volumeMounts:
    - name: credentials-volume
      mountPath: "/etc/secrets/google"
      readOnly: true
  volumes:
  - name: credentials-volume
    secret:
      secretName: data-manager-credentials

Autenticare le richieste REST e curl

Se la tua pipeline automatizzata effettua richieste HTTP non elaborate con curl anziché utilizzare una libreria client, utilizza Google Cloud CLI per autenticarti in modo non interattivo e gestire i token di accesso senza firmarli manualmente:

1. Autorizza Google Cloud CLI utilizzando il file delle credenziali configurato nel tuo ambiente:

   gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"
   

2. Passa il token di accesso generato nell'intestazione Authorization delle richieste API:

   curl -X POST "https://datamanager.googleapis.com/v1/..." \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json
   

   Google Cloud CLI memorizza automaticamente nella cache il token di accesso e lo aggiorna prima della scadenza.

Verificare l'accesso a IAM e all'account

Prima di eseguire il deployment dell'applicazione di produzione, verifica che il service account disponga delle autorizzazioni necessarie:

1. Autorizzazioni IAM Google Cloud: concedi al service account il ruolo Consumer Service Usage (roles/serviceusage.serviceUsageConsumer) nel progetto Google Cloud in cui è abilitata l'API Data Manager.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/serviceusage.serviceUsageConsumer"
   

2. Accesso all'account di destinazione: concedi al service account l'accesso richiesto ai tuoi account di destinazione. Per istruzioni passo passo, vedi Configurare l'accesso all'account.

Agire per conto degli utenti

Spesso le piattaforme di terze parti, come le agenzie e le piattaforme di marketing, devono inviare richieste API per conto di più inserzionisti che si registrano al loro servizio.

In questa architettura, anziché utilizzare le credenziali predefinite dell'applicazione, utilizza il flusso del server web OAuth 2.0 per ottenere le credenziali utente con accesso offline da ogni inserzionista, quindi utilizza queste credenziali per configurare la libreria client in fase di runtime in base all'account inserzionista gestito dalla richiesta.

Implementa il flusso web OAuth 2.0

Ecco come configurare la delega utente per le applicazioni multi-tenant:

1. Richiedi l'accesso offline: indirizza gli utenti alla schermata per il consenso OAuth di Google che richiede l'ambito https://www.googleapis.com/auth/datamanager con access_type=offline e prompt=consent. Il server scambia il codice di autorizzazione con un token di accesso e un refresh_token. Per istruzioni dettagliate, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni server web.

2. Archivia le credenziali in modo sicuro: archivia il token di aggiornamento di ogni utente in modo sicuro in un archivio delle credenziali criptato associato al suo account sulla tua piattaforma.

3. Inizializza le librerie client in fase di runtime: quando invii una richiesta API per conto di un utente specifico, crea le credenziali utente dal token di aggiornamento che hai archiviato per l'utente e dall'ID client e dal client secret per la tua app e trasmettili durante l'inizializzazione del client:

   .NET

   using Google.Ads.DataManager.V1;
   using Google.Apis.Auth.OAuth2;
   
   UserCredential credential = CredentialFactory.FromJsonParameters<UserCredential>(
       new JsonCredentialParameters
       {
           Type = JsonCredentialParameters.AuthorizedUserCredentialType,
           ClientId = clientId,
           ClientSecret = clientSecret,
           RefreshToken = refreshToken
       });
   
   IngestionServiceClient client = new IngestionServiceClientBuilder
   {
       Credential = credential
   }.Build();
   

   Go

   import (
       "context"
   
       datamanager "cloud.google.com/go/datamanager/apiv1"
       "golang.org/x/oauth2"
       "golang.org/x/oauth2/google"
       "google.golang.org/api/option"
   )
   
   cfg := &oauth2.Config{
       ClientID:     clientID,
       ClientSecret: clientSecret,
       Endpoint:     google.Endpoint,
   }
   ts := cfg.TokenSource(ctx, &oauth2.Token{RefreshToken: refreshToken})
   
   client, err := datamanager.NewIngestionClient(ctx, option.WithTokenSource(ts))
   

   Java

   import com.google.ads.datamanager.v1.IngestionServiceClient;
   import com.google.ads.datamanager.v1.IngestionServiceSettings;
   import com.google.api.gax.core.FixedCredentialsProvider;
   import com.google.auth.oauth2.UserCredentials;
   
   UserCredentials credentials =
       UserCredentials.newBuilder()
           .setClientId(clientId)
           .setClientSecret(clientSecret)
           .setRefreshToken(refreshToken)
           .build();
   
   IngestionServiceSettings settings =
       IngestionServiceSettings.newBuilder()
           .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
           .build();
   
   try (IngestionServiceClient client = IngestionServiceClient.create(settings)) {
     // Send API requests using client...
   }
   

   Node.js

   const {IngestionServiceClient} = require('@google-ads/datamanager').v1;
   const {UserRefreshClient} = require('google-auth-library');
   
   const authClient = new UserRefreshClient({
     clientId,
     clientSecret,
     refreshToken,
   });
   
   const client = new IngestionServiceClient({authClient});
   

   PHP

   use Google\Ads\DataManager\V1\Client\IngestionServiceClient;
   use Google\Auth\Credentials\UserRefreshCredentials;
   
   $credentials = new UserRefreshCredentials(
       null,
       [
           'client_id' => $clientId,
           'client_secret' => $clientSecret,
           'refresh_token' => $refreshToken,
       ]
   );
   
   $client = new IngestionServiceClient(['credentials' => $credentials]);
   

   Python

   from google.ads.datamanager_v1 import IngestionServiceClient
   from google.oauth2.credentials import Credentials
   
   credentials = Credentials.from_authorized_user_info({
       "client_id": client_id,
       "client_secret": client_secret,
       "refresh_token": refresh_token,
   })
   
   client = IngestionServiceClient(credentials=credentials)
   

   Ruby

   require "google/ads/data_manager/v1"
   require "googleauth"
   
   credentials = Google::Auth::UserRefreshCredentials.new(
     client_id: client_id,
     client_secret: client_secret,
     refresh_token: refresh_token
   )
   
   client = Google::Ads::DataManager::V1::IngestionService::Client.new do |config|
     config.credentials = credentials
   end
   

Completa la verifica dell'app OAuth

Poiché https://www.googleapis.com/auth/datamanager è un ambito sensibile, qualsiasi app Google Cloud utilizzata per ottenere le credenziali utente da Account Google esterni deve essere sottoposta alla verifica OAuth di Google prima di passare alla produzione:

• Sviluppo: mentre lo stato di pubblicazione dell'app è impostato su Test in corso nella pagina Pubblico della console Google Cloud, solo gli account di test designati possono autorizzare la tua applicazione.
• Produzione: prima di rendere disponibile la tua applicazione agli utenti esterni, imposta lo stato di pubblicazione su In produzione e invia l'app per la verifica.

Importante: se non completi la verifica dell'app OAuth prima del lancio per gli utenti esterni, questi visualizzeranno una schermata dell'app non verificata e potresti non essere in grado di ottenere le credenziali per i nuovi utenti. Per informazioni dettagliate sulle fasi di configurazione del pubblico e sui requisiti del video dimostrativo, consulta Verifica dell'app OAuth.

La verifica dell'app non è obbligatoria per i workload eseguiti utilizzando i service account. Inoltre, esistono alcune eccezioni per scenari come le applicazioni interne. Per maggiori dettagli, consulta la sezione Quando non è necessaria la verifica.

Alternativa: link dei partner

Se la tua organizzazione è un partner per i dati approvato, puoi utilizzare i link partner anziché gestire i token OAuth per utente per l'importazione continua dei dati.

Con i collegamenti partner, gli inserzionisti collegano i propri account al tuo account partner di dati nell'interfaccia utente di Google Ads, Display & Video 360 o Google Ad Manager. Una volta stabilito il collegamento, la tua applicazione invia richieste di importazione utilizzando le credenziali del tuo service account tramite ADC, evitando la necessità di archiviare e gestire token di aggiornamento utente di lunga durata.

Best practice per la produzione

Esamina queste considerazioni operative chiave quando passi alla produzione:

• Gestione e convalida degli errori: scopri in che modo l'API convalida le richieste utilizzando il modello di interruzione rapida e restituisce dettagli strutturati degli errori.
• Strategia di ripetizione dei tentativi: implementa il backoff esponenziale con jitter per gli errori temporanei del server.
• Batch e concorrenza: massimizza la velocità effettiva raggruppando i record e inviando le richieste contemporaneamente entro i limiti.
• Diagnostica e monitoraggio: acquisisci gli ID richiesta di risposta ed esegui query sul servizio di diagnostica per verificare l'elaborazione asincrona e rilevare avvisi ed errori.