Déployer en production

Ce guide vous aide à choisir et à configurer l'approche d'authentification appropriée pour le déploiement en production de votre 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 :

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 des charges de travail 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 les ADC pour récupérer automatiquement les identifiants éphémères du compte de service, sans avoir besoin 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 d'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 lorsque vous déployez 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 Service Usage (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 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 sur 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é) : 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 à courte durée de vie, sans avoir à gérer les clés de compte de service. Générez un fichier de configuration des identifiants et fournissez-le à ADC à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

  • Clés de compte de service (solution de secours) : 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 à ADC à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Ensemble 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 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 de l'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

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

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Vous pouvez également transmettre 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 authentifier et gérer les jetons d'accès de manière non interactive, sans signer manuellement les jetons :

  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 d'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

    La 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 Service Usage (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 Configurer l'accès au compte.

Agir pour le compte des utilisateurs

Les plates-formes tierces, telles que les plates-formes et agences marketing, doivent souvent envoyer des requêtes API au nom 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 du serveur Web OAuth 2.0 pour obtenir les identifiants utilisateur avec accès hors connexion de chaque annonceur. Utilisez ensuite 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 d'utilisateur pour les applications mutualisées :

  1. Demander l'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 OAuth 2.0 pour les applications de serveur Web.

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

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

Valider une application OAuth

Étant donné que https://www.googleapis.com/auth/datamanager est un champ sensible, toute application Google Cloud utilisée pour obtenir les identifiants utilisateur à partir de comptes Google externes doit faire l'objet d'une validation Google OAuth avant d'être mise 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.

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

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

Grâce aux associations de partenaires, les annonceurs associent leurs comptes à votre compte de partenaire pour les données dans l'UI Google Ads, Display & Video 360 ou Google Ad Manager. Une fois l'association établie, votre application envoie des requêtes d'ingestion à l'aide de ses propres identifiants de compte de service via ADC, ce qui évite d'avoir à stocker et à gérer des jetons d'actualisation utilisateur de longue durée.

Bonnes pratiques en production

Passez en revue ces considérations opérationnelles clés lorsque vous passez à la production :