Déployer en production

Ce guide vous aide à choisir et à configurer l'approche d'authentification appropriée pour votre déploiement en production de l'API Data Manager.

Choisir votre scénario de déploiement

Sélectionnez l'approche d'authentification qui correspond à l'architecture de votre application et à votre environnement de déploiement :

• Charges de travail dans Google Cloud : pour les charges de travail automatisées (telles que les pipelines ETL, les jobs par lot ou les services de backend) exécutées sur Compute Engine, Cloud Run, Cloud Functions ou GKE, utilisez les identifiants par défaut de l'application (ADC) avec un compte de service associé ou Workload Identity Federation for GKE.
• Charges de travail en dehors de Google Cloud: Pour les charges de travail automatisées exécutées sur site ou chez d'autres fournisseurs de services cloud, utilisez les identifiants par défaut de l'application (ADC) avec la fédération d'identité de charge de travail ou une clé de compte de service.
• Agir pour le compte des utilisateurs: pour les plates-formes tierces et les applications mutualisées qui gèrent les comptes d'utilisateurs externes (tels que les annonceurs qui s'inscrivent sur votre plate-forme), utilisez le flux de serveur Web OAuth 2.0 avec des jetons d'actualisation par utilisateur ou des liens partenaires si vous êtes un partenaire de données approuvé.

Pour obtenir des conseils généraux sur l'authentification Google Cloud, consultez l' arbre de décision sur l'authentification Google Cloud.

Charges de travail dans Google Cloud

Lorsque vous exécutez du code sur Google Cloud, associez un compte de service directement à votre ressource de calcul ou configurez la fédération d'identité de charge de travail pour GKE. Les bibliothèques clientes utilisent ADC pour récupérer automatiquement les identifiants éphémères du compte de service sans nécessiter de fichiers d'identifiants ni de variables d'environnement.

Compute Engine

Lorsque vous créez une instance de machine virtuelle, spécifiez le compte de service et le champ d'application de l'API Data Manager afin que les jetons d'accès renvoyés par le serveur de métadonnées de l'instance incluent l'autorisation requise.

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"

Pour mettre à jour les champs d'application ou le compte de service sur une instance existante, arrêtez l'instance, mettez à jour la configuration avec set-service-account, puis redémarrez l'instance :

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

Spécifiez le compte de service lors du déploiement du service :

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

Cloud Functions

Spécifiez le compte de service lors du déploiement de la fonction :

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

GKE

1. Activez la fédération d'identité de charge de travail pour GKE sur votre cluster.

2. Associez votre compte de service Kubernetes (KSA) au compte de service 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. Annotez le compte de service Kubernetes avec l'adresse e-mail du compte de service Google :

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

4. Spécifiez le compte de service Kubernetes dans la spécification de votre pod :

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

Vérifier l'accès IAM et au compte

Avant de déployer votre application de production, vérifiez que votre compte de service dispose des autorisations nécessaires :

1. Autorisations IAM Google Cloud : accordez au compte de service le rôle Consommateur d'utilisation du service (roles/serviceusage.serviceUsageConsumer) dans le projet Google Cloud où l'API Data Manager est activée.

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

2. Accès au compte de destination : accordez au compte de service l'accès requis à vos comptes de destination. Pour obtenir des instructions détaillées, consultez la section Configurer l'accès au compte.

Charges de travail en dehors de Google Cloud

Lorsque vous exécutez du code dans des centres de données sur site ou chez d'autres fournisseurs de services cloud, choisissez l'un des mécanismes d'authentification suivants :

• Fédération d'identité de charge de travail (recommandée) : configurez la fédération d'identité de charge de travail pour permettre à votre application d'échanger les identifiants de votre fournisseur d'identité externe contre des identifiants Google Cloud éphémères sans gérer les clés de compte de service. Générez un fichier de configuration des identifiants et fournissez-le aux identifiants par défaut de l'application à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

• Clés de compte de service (solution de repli) : si la fédération d'identité de charge de travail n'est pas disponible, créez une clé de compte de service et fournissez-la aux identifiants par défaut de l'application à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

  Attention : Les clés de compte de service sont des identifiants de longue durée qui présentent un risque de sécurité s'ils sont divulgués ou mal gérés. Suivez les bonnes pratiques pour gérer les clés de compte de service, stockez les clés dans un Secret Manager sécurisé, limitez les autorisations de fichiers et faites les régulièrement pivoter.

Définir GOOGLE_APPLICATION_CREDENTIALS

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès absolu du fichier de configuration des identifiants de la fédération d'identité de charge de travail ou du fichier de clé de compte de service afin que les bibliothèques clientes puissent localiser automatiquement vos identifiants à l'aide des ADC.

Linux / macOS

Définissez la variable d'environnement dans votre profil de shell ou votre script de déploiement :

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

Windows (PowerShell)

Définissez la variable d'environnement dans PowerShell :

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

Docker / Conteneurs

Installez le fichier d'identifiants dans le conteneur et définissez la variable d'environnement :

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Ou transmettez la variable d'environnement au moment de l'exécution :

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

Installez les identifiants en tant que secret et référencez-les dans l'environnement du 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

Authentifier les requêtes REST et curl

Si votre pipeline automatisé effectue des requêtes HTTP brutes avec curl au lieu d'utiliser une bibliothèque cliente, utilisez Google Cloud CLI pour vous authentifier de manière non interactive et gérer les jetons d'accès sans les signer manuellement :

1. Autorisez Google Cloud CLI à l'aide du fichier d'identifiants configuré dans votre environnement :

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

2. Transmettez le jeton d'accès généré dans l'en-tête Authorization de vos requêtes 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 met automatiquement en cache le jeton d'accès et l'actualise avant son expiration.

Vérifier l'accès IAM et au compte

Avant de déployer votre application de production, vérifiez que votre compte de service dispose des autorisations nécessaires :

1. Autorisations IAM Google Cloud : accordez au compte de service le rôle Consommateur d'utilisation du service (roles/serviceusage.serviceUsageConsumer) dans le projet Google Cloud où l'API Data Manager est activée.

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

2. Accès au compte de destination : accordez au compte de service l'accès requis à vos comptes de destination. Pour obtenir des instructions détaillées, consultez la section Configurer l'accès au compte.

Agir pour le compte des utilisateurs

Les plates-formes tierces, telles que les plates-formes marketing et les agences, doivent souvent envoyer des requêtes API pour le compte de plusieurs annonceurs qui s'inscrivent à leur service.

Dans cette architecture, au lieu d'utiliser les identifiants par défaut de l'application, utilisez le flux de serveur Web OAuth 2.0 pour obtenir les identifiants utilisateur avec un accès hors connexion de chaque annonceur, puis utilisez ces identifiants pour configurer la bibliothèque cliente au moment de l'exécution en fonction du compte d'annonceur géré par la requête.

Implémenter le flux Web OAuth 2.0

Voici comment configurer la délégation utilisateur pour les applications mutualisées :

1. Demander un accès hors connexion : redirigez les utilisateurs vers l'écran de consentement OAuth de Google en demandant le champ d'application https://www.googleapis.com/auth/datamanager avec access_type=offline et prompt=consent. Votre serveur échange le code d'autorisation contre un jeton d'accès et un refresh_token. Pour obtenir des instructions détaillées, consultez la section OAuth 2.0 pour les applications de serveur Web.

2. Stocker les identifiants de manière sécurisée : stockez de manière sécurisée le jeton d'actualisation de chaque utilisateur dans un magasin d'identifiants chiffré associé à son compte sur votre plate-forme.

3. Initialiser les bibliothèques clientes au moment de l'exécution : lorsque vous envoyez une requête API pour le compte d'un utilisateur spécifique, créez des identifiants utilisateur à partir du jeton d'actualisation que vous avez stocké pour l'utilisateur, de l'ID client et du code secret du client de votre application, puis transmettez-les lors de l'initialisation du 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
   

Effectuer la validation de l'application OAuth

Étant donné que les niveaux d'accès de l'API Data Manager sont sensibles, toute application cloud Google Cloud utilisée pour obtenir des identifiants utilisateur à partir de comptes Google externes doit faire l'objet d'une validation Google OAuth avant de passer en production :

• Développement : lorsque l'état de publication de l'application est défini sur Test sur la page "Audience" de la console Google Cloud, seuls les comptes de test désignés peuvent autoriser votre application.
• Production : avant de mettre votre application à la disposition des utilisateurs externes, définissez l'état de publication sur En production et envoyez l'application pour validation.

Important : Si vous n'effectuez pas la validation de l'application OAuth avant de la lancer auprès d' utilisateurs externes, ces derniers verront un écran d'application non validée et vous ne pourrez peut-être pas obtenir d'identifiants pour les nouveaux utilisateurs. Pour en savoir plus sur les phases de configuration de l'audience et les exigences concernant les vidéos de démonstration, consultez la section Validation de l'application OAuth.

La validation de l'application n'est pas requise pour les charges de travail exécutées à l'aide de comptes de service. De plus, il existe quelques exceptions pour les scénarios tels que les applications internes. Pour en savoir plus, consultez la section Quand la validation n'est-elle pas nécessaire ?

Autre solution : liens partenaires

Si votre organisation est un partenaire pour les données approuvé, vous pouvez utiliser des liens partenaires au lieu de gérer les jetons OAuth par utilisateur pour l'ingestion continue de données.

Avec les liens partenaires, les annonceurs associent leurs comptes à votre compte partenaire pour les données dans l'interface utilisateur de Google Ads, Display &Video 360 ou Google Ad Manager. Une fois le lien établi, votre application envoie des requêtes d'ingestion à l'aide de ses propres identifiants de compte de service via les identifiants par défaut de l'application, ce qui évite d'avoir à stocker et à gérer des jetons d'actualisation utilisateur de longue durée.

Bonnes pratiques en production

Tenez compte de ces considérations opérationnelles clés lorsque vous passez en production :

• Gestion des exceptions et validation: découvrez comment l'API valide les requêtes à l'aide du modèle de défaillance rapide et renvoie des détails d'erreur structurés.
• Stratégie de nouvelle tentative : implémentez un intervalle exponentiel entre les tentatives avec une gigue pour les erreurs de serveur temporaires.
• Traitement par lot et simultanéité : maximisez le débit en traitant les enregistrements par lot et en envoyant les requêtes simultanément dans les limites.
• Diagnostic et surveillance : capturez les ID de requête de réponse et interrogez le service de diagnostic pour vérifier le traitement asynchrone et détecter les avertissements et les erreurs.