Implantar para a produção

Este guia ajuda você a escolher e configurar a abordagem de autenticação adequada para sua 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) em execução no Compute Engine, no Cloud Run, no Cloud Functions ou no 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 em execução no local ou em outros provedores de nuvem, use o Application Default Credentials (ADC) com a federação de identidade de 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 a Federação de Identidade da Carga de Trabalho para GKE. As bibliotecas de cliente usam o ADC para recuperar automaticamente credenciais de curta duração para a conta de serviço, 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, interrompa-a, 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. Ative a Federação de Identidade da Carga de Trabalho para GKE no cluster.

2. Vincule sua 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 do Service Usage (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 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 (recomendado): 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 conta 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 conta de serviço (alternativa): 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 gerenciadas incorretamente. Siga as práticas recomendadas para gerenciar chaves de contas de serviço, armazene as chaves em um gerenciador de secrets seguro, restrinja as permissões de arquivos e alterne as 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 o 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 ambiente de 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 maneira 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 em cache o token de acesso automaticamente 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 do Service Usage (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 de marketing e agências, geralmente precisam enviar solicitações de API em nome de vários anunciantes que se inscrevem no serviço delas.

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 ambiente de execução com base na conta de 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 OAuth do Google solicitando o escopo https://www.googleapis.com/auth/datamanager com access_type=offline e prompt=consent. Seu 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. Armazene as 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 dele na sua plataforma.

3. Inicialize as bibliotecas de cliente no ambiente de execução: ao enviar uma solicitação de API em nome de um usuário específico, crie credenciais de usuário com base no token de atualização armazenado para o usuário, no ID do cliente e na chave secreta do cliente do 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 Cloud 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, somente 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 do app OAuth antes do lançamento para usuários externos, eles vão encontrar uma tela de app não verificado e talvez não seja possível receber credenciais para novos usuários. Para mais detalhes sobre as fases de configuração do público-alvo e os requisitos do vídeo de demonstração, consulte Verificação de apps OAuth.

A verificação de apps não é necessária para cargas de trabalho que usam 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 a organização for um parceiro de dados aprovado, use links de parceiros em vez de gerenciar tokens OAuth por usuário para a ingestão de dados contínua.

Com os links de parceiros, os anunciantes conectam as contas deles à sua 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 credenciais da sua própria conta de serviço pelo ADC, evitando a necessidade de armazenar e manter tokens de atualização de usuário de longa duração.

Práticas recomendadas de produção

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

• Tratamento de erros e validação: entenda como a API valida solicitações usando o modelo de falha rápida e retorna detalhes de erro estruturados.
• Estratégia de repetição: implemente a espera exponencial com jitter para erros temporários do servidor.
• Processamento em lote e simultaneidade: maximize a capacidade de processamento agrupando registros em lote e enviando solicitações simultaneamente dentro dos limites.
• Diagnóstico e monitoramento: capture os 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.