Fluxo de trabalho da conta de serviço

Observação: este guia pressupõe que você conhece o modelo de acesso do Google Ads. Caso contrário, recomendamos ler o guia Modelo de acesso do Google Ads para se familiarizar com os conceitos.

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

Uma conta de serviço pertence ao seu app, e não a um usuário final específico. As contas de serviço empregam um fluxo OAuth 2.0 que não requer autorização humana, usando em vez disso um arquivo de chave que só o app pode acessar.

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

• A autorização para acesso à API Google Ads nas 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 a interação do usuário, o armazenamento de credenciais do usuário etc.

• A autorização de acesso às contas do Google Ads não está vinculada às credenciais de usuários individuais, o que pode ser útil quando se espera que essa autorização continue mesmo que o funcionário que autorizou o acesso originalmente saia da equipe ou da 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.

2. Faça login na sua conta do Google Ads como administrador. Acesse Administrador > 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 à conta adequado e clique no botão Adicionar conta. Os níveis de acesso "E-mail" e "Administrador" não são compatíveis com contas de serviço.

   

5. A conta de serviço recebe acesso.

   

Configuração da biblioteca de cliente

Selecione a guia correspondente à sua linguagem de programação para instruções sobre como configurar a biblioteca de cliente.

Java

Defina o caminho JSON da chave privada na sua 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 = "PATH_TO_JSON_SECRETS_PATH",
    ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

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

Python

Defina o caminho JSON da chave privada na sua configuração. Se você estiver usando um google-ads.yaml file, 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 à sua configuração ou ambiente do Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

Configure as seguintes chaves no seu google_ads_php.ini. Consulte o guia de configuração para mais detalhes.

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

Ruby

Configure as seguintes chaves no google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

Defina o caminho JSON da chave privada e o ID da conta delegada na sua 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 à sua configuração ou ambiente do Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

curl

Observação: este guia mostra as instruções para conseguir um token de acesso usando a CLI gcloud. No entanto, você pode usar qualquer biblioteca de cliente do OAuth 2.0 disponível na Internet. Em https://oauth.net/code/, há várias bibliotecas do OAuth específicas para cada linguagem. Consulte também a documentação do OAuth do Google para saber mais sobre o fluxo de trabalho HTTP bruto para contas de serviço.

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

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

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'

Agora você pode usar o token de acesso nas suas 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 criação de relatórios.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_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"
}