Implementar en producción

En esta guía, se te ayudará 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 identidades para cargas de trabajo o una clave de cuenta de servicio.
• Actúa en nombre de los usuarios: Para las plataformas de terceros y las aplicaciones de varios usuarios que administran cuentas de usuarios externos (como los anunciantes que se registran en tu plataforma), usa el flujo de 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 ejecute 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 credenciales de corta duración para la cuenta de servicio automáticamente sin requerir archivos de credenciales ni variables de entorno.

Compute Engine

Cuando crees una instancia de máquina virtual, especifica la cuenta de servicio y el permiso de la API de Data Manager para que los tokens de acceso que muestra 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 reiníciala:

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 un 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 de tu 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 (recomendado): 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 cuentas 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 ADC con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

  **Precaución:** Las claves de cuentas de servicio son credenciales de larga duración que presentan 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, almacenar claves en un administrador de secretos seguro, restringir los permisos de archivos y rotar las claves con regularidad.

Configura GOOGLE_APPLICATION_CREDENTIALS

Configura 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 el archivo de claves de cuenta de servicio para que las bibliotecas cliente puedan ubicar tus credenciales automáticamente con ADC.

Linux / macOS

Configura 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)

Configura la variable de entorno en PowerShell:

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

Docker / contenedores

Activa el archivo de credenciales en el contenedor y configura la variable de entorno:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

O 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 ellas 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 Google Cloud CLI 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 automáticamente en caché 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.

Actúa en nombre de los usuarios

Las plataformas de terceros, como las plataformas y agencias 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 de servidor web de OAuth 2.0 para obtener credenciales de 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 de anunciante que administra la solicitud.

Implementa el flujo web de OAuth 2.0

A continuación, se explica cómo configurar la delegación de usuarios para aplicaciones de varios usuarios:

1. Solicita acceso sin conexión: Dirige a los usuarios a la pantalla de consentimiento de OAuth de Google para solicitar 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. Para obtener instrucciones paso a paso, consulta OAuth 2.0 para aplicaciones de servidor web.

2. Almacena credenciales de forma segura: Almacena de forma segura el token de actualización de cada usuario en un almacenamiento de credenciales encriptado asociado con su cuenta en tu plataforma.

3. Inicializa 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, el ID de cliente 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

Debido a que los permisos de la API de Data Manager son sensibles, cualquier app en la nube 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é configurado 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 usuarios externos, configura el estado de publicación como 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, los usuarios 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 la app 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, hay algunas excepciones para casos como las aplicaciones internas. Consulta ¿Cuándo no es necesaria la verificación? para obtener más detalles.

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 ingesta continua de datos.

Con los vínculos 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. Una vez que se establece el vínculo, 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 usuario de larga duración.

Prácticas recomendadas de producción

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

• Manejo y validación de errores: Comprende cómo la API valida las solicitudes con el modelo de falla rápida y muestra detalles de errores estructurados.
• Estrategia de reintento: Implementa la retirada exponencial con fluctuación para errores transitorios del servidor.
• Procesamiento por lotes y simultaneidad: Maximiza el rendimiento 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 solicitud de respuesta y consulta el servicio de diagnóstico para verificar el procesamiento asíncrono y detectar advertencias y errores.