Implementar en producción

Esta guía te ayuda a elegir y configurar el enfoque de autenticación adecuado para la implementación de producción de la API de Data Manager.

Elige tu caso de implementación

Selecciona el enfoque de autenticación que coincida con la arquitectura de tu aplicación y el entorno de implementación:

• Cargas de trabajo en Google Cloud: Para las cargas de trabajo automatizadas (como las canalizaciones de ETL, los trabajos por lotes o los servicios de backend) que se ejecutan en Compute Engine, Cloud Run, Cloud Functions o GKE, usa las credenciales predeterminadas de la aplicación (ADC) con una cuenta de servicio adjunta o Workload Identity Federation for GKE.
• Cargas de trabajo fuera de Google Cloud: Para las cargas de trabajo automatizadas que se ejecutan de forma local o en otros proveedores de servicios en la nube, usa las credenciales predeterminadas de la aplicación (ADC) con la federación de Workload Identity o una clave de cuenta de servicio.
• Actúa en nombre de los usuarios: Para las plataformas de terceros y las aplicaciones de varios arrendatarios que administran cuentas de usuarios externos (como los anunciantes que se registran en tu plataforma), usa el flujo del servidor web de OAuth 2.0 con tokens de actualización por usuario o vínculos de socios si eres un socio de datos aprobado.

Para obtener orientación general sobre la autenticación de Google Cloud, consulta el árbol de decisiones de autenticación de Google Cloud.

Cargas de trabajo en Google Cloud

Cuando se ejecuta en Google Cloud, adjunta una cuenta de servicio directamente a tu recurso de procesamiento o configura Workload Identity Federation for GKE. Las bibliotecas cliente usan ADC para recuperar automáticamente credenciales de corta duración para la cuenta de servicio sin necesidad de archivos de credenciales ni variables de entorno.

Compute Engine

Cuando crees una instancia de máquina virtual, especifica la cuenta de servicio y el alcance de la API de Data Manager para que los tokens de acceso que devuelve el servidor de metadatos de la instancia incluyan la autorización requerida.

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"

Para actualizar los permisos o la cuenta de servicio en una instancia existente, detén la instancia, actualiza la configuración con set-service-account y reinicia la instancia:

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

Especifica la cuenta de servicio cuando implementes el servicio:

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

Cloud Functions

Especifica la cuenta de servicio cuando implementes la función:

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

GKE

1. Habilita Workload Identity Federation for GKE en tu clúster.

2. Vincula tu cuenta de servicio de Kubernetes (KSA) a la cuenta de servicio de 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. Anota la cuenta de servicio de Kubernetes con el correo electrónico de la cuenta de servicio de Google:

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

4. Especifica la cuenta de servicio de Kubernetes en la especificación del Pod:

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

Verifica el acceso a la IAM y a la cuenta

Antes de implementar tu aplicación de producción, verifica que tu cuenta de servicio tenga los permisos necesarios:

1. Permisos de Cloud IAM de Google Cloud: Otorga a la cuenta de servicio el rol de Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en el proyecto de Google Cloud en el que está habilitada la API de Data Manager.

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

2. Acceso a la cuenta de destino: Otorga a la cuenta de servicio el acceso requerido a tus cuentas de destino. Para obtener instrucciones paso a paso, consulta Configura el acceso a la cuenta.

Cargas de trabajo fuera de Google Cloud

Cuando ejecutes código en centros de datos locales o en otros proveedores de servicios en la nube, elige uno de los siguientes mecanismos de autenticación:

• Federación de identidades para cargas de trabajo (recomendada): Configura la federación de identidades para cargas de trabajo para permitir que tu aplicación intercambie credenciales de tu proveedor de identidad externo por credenciales de Google Cloud de corta duración sin administrar claves de cuentas de servicio. Genera un archivo de configuración de credenciales y proporciónalo a ADC con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

• Claves de cuenta de servicio (reserva): Si la federación de identidades para cargas de trabajo no está disponible, crea una clave de cuenta de servicio y proporciónala a las ADC con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

  Precaución: Las claves de cuentas de servicio son credenciales de larga duración que representan un riesgo de seguridad si se filtran o se administran de forma inadecuada. Sigue las prácticas recomendadas para administrar claves de cuentas de servicio, almacena las claves en un administrador de secretos seguro, restringe los permisos de archivos y rota las claves con regularidad.

Conjunto GOOGLE_APPLICATION_CREDENTIALS

Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso absoluta del archivo de configuración de credenciales de la federación de identidades para cargas de trabajo o del archivo de claves de la cuenta de servicio para que las bibliotecas cliente puedan ubicar tus credenciales automáticamente con ADC.

Linux/macOS

Establece la variable de entorno en tu perfil de shell o secuencia de comandos de implementación:

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

Windows (PowerShell)

Establece la variable de entorno en PowerShell:

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

Docker / Contenedores

Monta el archivo de credenciales en el contenedor y establece la variable de entorno:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

O bien pasa la variable de entorno en el tiempo de ejecución:

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

Activa las credenciales como un Secret y haz referencia a él en el entorno 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

Autentica solicitudes de REST y cURL

Si tu canalización automatizada realiza solicitudes HTTP sin procesar con curl en lugar de usar una biblioteca cliente, usa la CLI de Google Cloud para autenticar y administrar tokens de acceso de forma no interactiva sin firmar tokens de forma manual:

1. Autoriza Google Cloud CLI con el archivo de credenciales configurado en tu entorno:

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

2. Pasa el token de acceso generado en el encabezado Authorization de tus solicitudes a la 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 almacena en caché automáticamente el token de acceso y lo actualiza antes de que venza.

Verifica el acceso a la IAM y a la cuenta

Antes de implementar tu aplicación de producción, verifica que tu cuenta de servicio tenga los permisos necesarios:

1. Permisos de Cloud IAM de Google Cloud: Otorga a la cuenta de servicio el rol de Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en el proyecto de Google Cloud en el que está habilitada la API de Data Manager.

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

2. Acceso a la cuenta de destino: Otorga a la cuenta de servicio el acceso requerido a tus cuentas de destino. Para obtener instrucciones paso a paso, consulta Configura el acceso a la cuenta.

Actuar en nombre de los usuarios

Las plataformas de terceros, como las agencias y las plataformas de marketing, a menudo necesitan enviar solicitudes a la API en nombre de varios anunciantes que se registran en su servicio.

En esta arquitectura, en lugar de usar las credenciales predeterminadas de la aplicación, usa el flujo del servidor web de OAuth 2.0 para obtener las credenciales del usuario con acceso sin conexión de cada anunciante y, luego, usa esas credenciales para configurar la biblioteca cliente en el tiempo de ejecución según la cuenta del anunciante que administra la solicitud.

Implementa el flujo web de OAuth 2.0

Sigue estos pasos para configurar la delegación de usuarios para aplicaciones multiusuario:

1. Solicita acceso sin conexión: Dirige a los usuarios a la pantalla de consentimiento de OAuth de Google y solicita el permiso https://www.googleapis.com/auth/datamanager con access_type=offline y prompt=consent. Tu servidor intercambia el código de autorización por un token de acceso y un refresh_token. Si deseas obtener instrucciones paso a paso, consulta OAuth 2.0 para aplicaciones de servidor web.

2. Almacena las credenciales de forma segura: Almacena de forma segura el token de actualización de cada usuario en un almacén de credenciales encriptado asociado a su cuenta en tu plataforma.

3. Inicializa las bibliotecas cliente en el tiempo de ejecución: Cuando envíes una solicitud a la API en nombre de un usuario específico, crea credenciales de usuario a partir del token de actualización que almacenaste para el usuario y el ID y el secreto del cliente de tu app, y pásalos cuando inicialices el cliente:

   .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 verificación de la app de OAuth

Dado que https://www.googleapis.com/auth/datamanager es un alcance sensible, cualquier app de Google Cloud que se use para obtener credenciales de usuario de Cuentas de Google externas debe someterse a la verificación de OAuth de Google antes de pasar a producción:

• Desarrollo: Mientras el estado de publicación de la app esté establecido como Prueba en la página Público de la consola de Google Cloud, solo las cuentas de prueba designadas podrán autorizar tu aplicación.
• Producción: Antes de que tu aplicación esté disponible para los usuarios externos, establece el estado de publicación en En producción y envía la app para su verificación.

Importante: Si no completas la verificación de la app de OAuth antes de lanzarla para usuarios externos, estos verán una pantalla de app no verificada y es posible que no puedas obtener credenciales para usuarios nuevos. Para obtener detalles sobre las fases de configuración del público y los requisitos de los videos de demostración, consulta Verificación de apps de OAuth.

No se requiere la verificación de la app para las cargas de trabajo que se ejecutan con cuentas de servicio. Además, existen algunas excepciones para situaciones como las aplicaciones internas. Consulta Cuándo no se necesita la verificación para obtener más información.

Alternativa: Vínculos de socios

Si tu organización es un socio de datos aprobado, puedes usar vínculos de socios en lugar de administrar tokens de OAuth por usuario para la transferencia continua de datos.

Con las vinculaciones de socios, los anunciantes conectan sus cuentas a tu cuenta de socio de datos en la IU de Google Ads, Display & Video 360 o Google Ad Manager. Después de establecer la vinculación, tu aplicación envía solicitudes de transferencia con tus propias credenciales de cuenta de servicio a través de ADC, lo que evita la necesidad de almacenar y mantener tokens de actualización de usuarios de larga duración.

Prácticas recomendadas de producción

Revisa estas consideraciones operativas clave cuando pases a producción:

• Control y validación de errores: Comprende cómo la API valida las solicitudes con el modelo de falla rápida y devuelve detalles de errores estructurados.
• Estrategia de reintento: Implementa la retirada exponencial con fluctuaciones para los errores transitorios del servidor.
• Procesamiento por lotes y simultaneidad: Maximiza la capacidad de procesamiento procesando registros por lotes y enviando solicitudes de forma simultánea dentro de los límites.
• Diagnóstico y supervisión: Captura los IDs de las solicitudes de respuesta y consulta el servicio de diagnóstico para verificar el procesamiento asíncrono y detectar advertencias y errores.