Implantar para a produção

Este guia ajuda você a escolher e configurar a abordagem de autenticação adequada para a implantação de produção da API Data Manager.

Escolher o cenário de implantação

Selecione a abordagem de autenticação que corresponde à arquitetura do aplicativo e ao ambiente de implantação:

• Cargas de trabalho no Google Cloud: para cargas de trabalho automatizadas (como pipelines de ETL, jobs em lote ou serviços de back-end) executadas no Compute Engine, Cloud Run, Cloud Functions ou GKE, use o Application Default Credentials (ADC) com uma conta de serviço anexada ou a Federação de Identidade da Carga de Trabalho para GKE.
• Cargas de trabalho fora do Google Cloud: Para cargas de trabalho automatizadas executadas no local ou em outros provedores de nuvem, use Application Default Credentials (ADC) com a Federação de Identidade da Carga de Trabalho ou uma chave de conta de serviço.
• Agir em nome dos usuários: para plataformas de terceiros e aplicativos multilocatários que gerenciam contas de usuários externos (como anunciantes que se inscrevem na sua plataforma), use o fluxo do servidor da Web do OAuth 2.0 com tokens de atualização por usuário ou links de parceiros se você for um parceiro de dados aprovado.

Para orientações gerais sobre a autenticação do Google Cloud, consulte a árvore de decisão de autenticação do Google Cloud.

Cargas de trabalho no Google Cloud

Ao executar no Google Cloud, anexe uma conta de serviço diretamente ao recurso de computação ou configure Federação de Identidade da Carga de Trabalho para GKE. As bibliotecas de cliente usam ADC para recuperar credenciais de curta duração da conta de serviço automaticamente, sem exigir arquivos de credenciais ou variáveis de ambiente.

Compute Engine

Ao criar uma instância de máquina virtual, especifique a conta de serviço e o escopo da API Data Manager para que os tokens de acesso retornados pelo servidor de metadados da instância incluam a autorização necessária.

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 atualizar os escopos ou a conta de serviço em uma instância atual, interrompa a instância, atualize a configuração com set-service-account e reinicie a instância:

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

Especifique a conta de serviço ao implantar o serviço:

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

Cloud Functions

Especifique a conta de serviço ao implantar a função:

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

GKE

1. Ativar a Federação de Identidade da Carga de Trabalho para GKE no cluster.

2. Vincular a conta de serviço do Kubernetes (KSA) à conta de serviço do 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. Anote a conta de serviço do Kubernetes com o e-mail da conta de serviço do Google:

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

4. Especifique a conta de serviço do Kubernetes na especificação do pod:

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

Verificar o acesso ao IAM e à conta

Antes de implantar o aplicativo de produção, verifique se a conta de serviço tem as permissões necessárias:

1. Permissões do IAM do Google Cloud: conceda à conta de serviço o papel de consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer) no projeto do Google Cloud em que a API Data Manager está ativada.

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

2. Acesso à conta de destino: conceda à conta de serviço o acesso necessário às contas de destino. Para instruções detalhadas, consulte Configurar o acesso à conta.

Cargas de trabalho fora do Google Cloud

Ao executar o código em data centers locais ou em outros provedores de nuvem, escolha um dos seguintes mecanismos de autenticação:

• Federação de identidade da carga de trabalho (recomendada): configure a Federação de Identidade da Carga de Trabalho para permitir que o aplicativo troque credenciais do provedor de identidade externo por credenciais de curta duração do Google Cloud sem gerenciar chaves de contas de serviço. Gere um arquivo de configuração de credenciais e forneça-o ao ADC usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

• Chaves de contas de serviço (fallback): se a Federação de Identidade da Carga de Trabalho não estiver disponível, crie uma chave de conta de serviço e forneça-a ao ADC usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  Atenção: as chaves de conta de serviço são credenciais de longa duração que apresentam um risco de segurança se forem vazadas ou mal gerenciadas. Siga as práticas recomendadas para gerenciar chaves de contas de serviço, armazene chaves em um gerenciador de secrets seguro, restrinja as permissões de arquivo e faça a rotação das chaves regularmente.

Definir GOOGLE_APPLICATION_CREDENTIALS

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho absoluto do arquivo de configuração de credenciais da Federação de Identidade da Carga de Trabalho ou do arquivo de chave da conta de serviço para que as bibliotecas de cliente possam localizar suas credenciais automaticamente usando ADC.

Linux / macOS

Defina a variável de ambiente no perfil do shell ou no script de implantação:

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

Windows (PowerShell)

Defina a variável de ambiente no PowerShell:

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

Docker / contêineres

Monte o arquivo de credenciais no contêiner e defina a variável de ambiente:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Ou transmita a variável de ambiente no momento da execução:

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

Monte as credenciais como um Secret e faça referência a ele no ambiente do 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

Autenticar solicitações REST e curl

Se o pipeline automatizado fizer solicitações HTTP brutas com curl em vez de usar uma biblioteca de cliente, use a CLI do Google Cloud para autenticar e gerenciar tokens de acesso de forma não interativa, sem assinar tokens manualmente:

1. Autorize a CLI do Google Cloud usando o arquivo de credenciais configurado no seu ambiente:

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

2. Transmita o token de acesso gerado no cabeçalho Authorization das solicitações de 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
   

   A CLI do Google Cloud armazena automaticamente o token de acesso em cache e o atualiza antes da expiração.

Verificar o acesso ao IAM e à conta

Antes de implantar o aplicativo de produção, verifique se a conta de serviço tem as permissões necessárias:

1. Permissões do IAM do Google Cloud: conceda à conta de serviço o papel de consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer) no projeto do Google Cloud em que a API Data Manager está ativada.

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

2. Acesso à conta de destino: conceda à conta de serviço o acesso necessário às contas de destino. Para instruções detalhadas, consulte Configurar o acesso à conta.

Agir em nome dos usuários

Plataformas de terceiros, como plataformas e agências de marketing, geralmente precisam enviar solicitações de API em nome de vários anunciantes que se inscrevem no serviço.

Nessa arquitetura, em vez de usar o Application Default Credentials, use o fluxo do servidor da Web do OAuth 2.0 para receber credenciais de usuário com acesso off-line de cada anunciante e, em seguida, use essas credenciais para configurar a biblioteca de cliente no momento da execução com base na conta do anunciante que a solicitação está gerenciando.

Implementar o fluxo da Web do OAuth 2.0

Veja como configurar a delegação de usuários para aplicativos multilocatários:

1. Solicitar acesso off-line: direcione os usuários para a tela de permissão do OAuth do Google solicitando o escopo https://www.googleapis.com/auth/datamanager com access_type=offline e prompt=consent. O servidor troca o código de autorização por um token de acesso e um refresh_token. Para instruções detalhadas, consulte OAuth 2.0 para aplicativos de servidor da Web.

2. Armazenar credenciais com segurança: armazene o token de atualização de cada usuário com segurança em um armazenamento de credenciais criptografado associado à conta na sua plataforma.

3. Inicializar bibliotecas de cliente no tempo de execução: ao enviar uma solicitação de API em nome de um usuário específico, crie credenciais de usuário com o token de atualização armazenado para o usuário e o ID do cliente e a chave secreta do cliente para seu app, e transmita-os ao inicializar o 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
   

Concluir a verificação de apps OAuth

Como os escopos da API Data Manager são sensíveis, qualquer app na nuvem do Google usado para receber credenciais de usuário de Contas do Google externas precisa passar pela verificação do OAuth do Google antes de entrar em produção:

• Desenvolvimento: enquanto o status de publicação do app estiver definido como Testando na página "Público-alvo" no console do Google Cloud, apenas as contas de teste designadas poderão autorizar o aplicativo.
• Produção: antes de disponibilizar o aplicativo para usuários externos, defina o status de publicação como Em produção e envie o app para verificação.

Importante: se você não concluir a verificação de apps OAuth antes de lançar para usuários externos, os usuários vão encontrar uma tela de app não verificado e talvez não seja possível receber credenciais de novos usuários. Para detalhes sobre as fases de configuração do público-alvo e os requisitos de vídeo de demonstração, consulte Verificação de apps OAuth.

A verificação de apps não é necessária para cargas de trabalho executadas usando contas de serviço. Além disso, há algumas exceções para cenários como aplicativos internos. Confira Quando a verificação não é necessária para mais detalhes.

Alternativa: links de parceiros

Se sua organização for um parceiro de dados aprovado, você poderá usar links de parceiros em vez de gerenciar tokens OAuth por usuário para ingestão de dados contínua.

Com os links de parceiros, os anunciantes conectam as contas à conta de parceiro de dados na interface do Google Ads, do Display &Video 360 ou do Google Ad Manager. Depois que o link é estabelecido, o aplicativo envia solicitações de ingestão usando as próprias credenciais da conta de serviço pelo ADC, evitando a necessidade de armazenar e manter tokens de atualização de usuários de longa duração.

Práticas recomendadas de produção

Analise estas considerações operacionais importantes ao migrar para a produção:

• Tratamento e validação de erros: entenda como a API valida solicitações usando o modelo de falha rápida e retorna detalhes de erros estruturados.
• Estratégia de repetição: implemente a espera exponencial com jitter para erros de servidor temporários.
• Lote e simultaneidade: maximize a capacidade de processamento em lote de registros e envie solicitações simultaneamente dentro dos limites.
• Diagnóstico e monitoramento: capture IDs de solicitação de resposta e consulte o serviço de diagnóstico para verificar o processamento assíncrono e detectar avisos e erros.