Fluxo de trabalho da conta de serviço

Este guia discute como acessar a API Google Ads com contas de serviço.

Uma conta de serviço pertence ao app e não a um usuário final individual. As contas de serviço empregam um fluxo do OAuth 2.0 que não exige autorização humana, usando um arquivo de chave que somente o app pode acessar.

O uso de contas de serviço oferece duas grandes vantagens:

  • A autorização para acesso da API Google Ads às contas do Google Ads é feita como uma etapa de configuração, aproveitando os recursos de autorização e gerenciamento de contas oferecidos pela interface do Google Ads. Isso economiza o esforço do desenvolvedor, já que não é necessário criar fluxos do OAuth 2.0 e lidar com complicações que envolvem interação do usuário, armazenamento de credenciais do usuário e gerenciamento de tokens.

  • A autorização de acesso às contas do Google Ads não está vinculada a credenciais de usuário individuais, o que pode ser útil em casos em que essa autorização precisa continuar mesmo que o funcionário que autorizou o acesso originalmente deixe a equipe ou a empresa.

Configuração de acesso à conta

  1. Comece criando uma conta de serviço e credenciais.

    Faça o download da chave da conta de serviço no formato JSON e anote o ID e o e-mail da conta de serviço.

  2. Faça login na sua conta do Google Ads como administrador. Acesse Admin > Acesso e segurança.

  3. Clique no botão + na guia Usuários.

  4. Digite o e-mail da conta de serviço na caixa de entrada E-mail. Selecione o nível de acesso adequado à conta (as contas de serviço não oferecem suporte ao nível de acesso Somente e-mail) e clique no botão Adicionar conta.

    A conta de serviço recebe acesso.

  5. Opcional:por padrão, não é possível conceder acesso de administrador a uma conta de serviço. Siga o princípio de privilégio mínimo e conceda acesso de administrador somente se as chamadas de API exigirem isso. É possível fazer upgrade do acesso da seguinte maneira:

    • Clique na seta suspensa ao lado do nível de acesso da conta de serviço na coluna Nível de acesso.
    • Selecione Admin na lista suspensa.

Configuração da biblioteca de cliente

Selecione a guia correspondente à linguagem de programação para instruções sobre como configurar a biblioteca de cliente. Se a conta de serviço acessar contas de cliente por meio de uma conta de administrador do Google Ads, defina login-customer-id (ou loginCustomerId) como o ID de cliente de 10 dígitos dessa conta de administrador sem hífens (consulte ID de cliente de login).

Java

Defina o caminho JSON da chave privada na configuração. Se você estiver usando um arquivo ads.properties, adicione o seguinte:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

Consulte o guia de configuração para mais detalhes.

.NET

Defina OAuth2Mode e OAuth2SecretsJsonPath na instância GoogleAdsConfig e use-a para inicializar o objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    // ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

Consulte o guia de configuração para mais detalhes.

Python

Defina o caminho JSON da chave privada na configuração. Se você estiver usando um arquivo google-ads.yaml, uma string YAML ou um dict, adicione o seguinte:

json_key_file_path: JSON_KEY_FILE_PATH

Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ao ambiente do Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

Consulte o guia de configuração para mais detalhes.

PHP

Configure as seguintes chaves no arquivo google_ads_php.ini.

[OAUTH2]
; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Consulte o guia de configuração para mais detalhes.

Ruby

Configure as seguintes chaves no arquivo google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Consulte o guia de configuração para mais detalhes.

Perl

Defina o caminho JSON da chave privada na configuração. Se você estiver usando um arquivo googleads.properties, adicione o seguinte:

jsonKeyFilePath=JSON_KEY_FILE_PATH

Se você estiver usando variáveis de ambiente, adicione o seguinte à configuração ou ao ambiente do Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

Consulte o guia de configuração para mais detalhes.

curl

Comece definindo a conta de serviço como as credenciais ativas na CLI gcloud.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

Em seguida, busque um token de acesso do OAuth 2.0 para a API Google Ads.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

Você pode usar o token de acesso nas chamadas de API. O exemplo a seguir mostra como executar um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da geração de relatórios.

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

O conteúdo de query.json é o seguinte:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Anterior
Visão geral do modelo de acesso
Avançar
Visão geral