Déployer en production

Ce guide vous aide à choisir et à configurer la méthode 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 et à l'environnement de déploiement de votre application :

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

Charges de travail dans Google Cloud

Lorsque vous exécutez votre application 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 l'ADC pour récupérer automatiquement des identifiants éphémères pour le 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 d'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 l'accès au compte

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

  1. Autorisations Google Cloud IAM : attribuez 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 des identifiants de votre fournisseur d'identité externe contre des identifiants Google Cloud de courte durée sans gérer de 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 la fédération d'identité de charge de travail ou du fichier de clé du 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

Installez 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 plutôt que d'utiliser une bibliothèque cliente, utilisez la 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 la 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

    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 l'accès 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 : attribuez 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 marketing et les agences 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 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 d'utilisateurs pour les applications mutualisées :

  1. Demander l'accès hors connexion : redirigez les utilisateurs vers l'écran de consentement OAuth de Google 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. Stocker 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é 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 l'ID client et le 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

Terminer la validation de l'application OAuth

Étant donné que les niveaux d'accès de l'API Data Manager sont des niveaux d'accès sensibles, toute application cloud Google Cloud utilisée pour obtenir des identifiants utilisateur à partir de comptes Google externes doit être soumise à la 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 des exceptions pour certains 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 pour les données approuvé, vous pouvez utiliser des liens partenaires au lieu de gérer des jetons OAuth par utilisateur pour l'ingestion de données en cours.

Grâce aux liens partenaires, les annonceurs associent leurs comptes à votre compte de partenaire pour les données dans l'interface utilisateur de Google Ads, Display & Video 360 ou Google Ad Manager. Une fois l'association établie, votre application envoie des requêtes d'ingestion à l'aide des identifiants de votre propre 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

Examinez ces considérations opérationnelles clés lorsque vous passez en production :