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 permitem interações entre servidores entre um web app e um serviço do Google. O app chama as APIs do Google em nome da conta de serviço, evitando o envolvimento direto dos usuários.
As contas de serviço usam um fluxo OAuth 2.0 que não requer autorização humana. Em vez disso, elas usam 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 do Google é feita como uma etapa de configuração, evitando as complicações associadas a outros fluxos do OAuth 2.0 que exigem interações do usuário.
O fluxo de declaração do OAuth 2.0 permite que seu app se passe por outros usuários, se necessário.
Há duas maneiras de autorizar com contas de serviço: diretamente ou com representação (não recomendado).
[Recomendado] Autorização com acesso direto à conta
Nessa opção, você dá à conta de serviço acesso direto à sua conta do Google Ads.
Configuração de acesso à conta
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.
Faça login na sua conta do Google Ads como administrador. Acesse Administrador > Acesso e segurança.
Clique no botão + na guia Usuários.
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 de e-mail e administrador não são compatíveis com contas de serviço.
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
Configure as seguintes chaves no seu App.config / Web.config. Consulte o guia de configuração para mais detalhes.
<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />
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
[Não recomendado] Autorização usando representação
Nessa opção, você representa um usuário que tem acesso à sua conta do Google Ads usando a conta de serviço. Essa abordagem funciona apenas para clientes do Google Workspace. Uma conta de serviço só pode personificar usuários (endereços de e-mail) no mesmo Google Workspace.
Pré-requisitos
Um domínio do Google Workspace de sua propriedade, como
mydomain.comoumybusiness.comUm token de desenvolvedor da API Google Ads e, opcionalmente, uma conta de teste
A biblioteca de cliente para a linguagem que você está usando
Um projeto do Console de APIs do Google configurado para a API Google Ads
Um usuário do Google Ads com permissões na conta que você quer acessar.
Configuração de acesso à conta de serviço
Como a representação do usuário é controlada apenas no nível do domínio, o uso de contas de serviço e fluxo de declaração com o Google OAuth 2.0 exige que você tenha seu próprio domínio registrado no Google Workspace. Seu app e os usuários dele podem se passar por qualquer usuário no domínio.
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 da conta.
Compartilhe o ID da conta de serviço e o escopo da API Google Ads (
https://www.googleapis.com/auth/adwords) com o administrador do domínio.Peça ao administrador do domínio para delegar autoridade em todo o domínio à sua conta de serviço.
Se você é o administrador do domínio, siga as instruções da Central de Ajuda.
Agora você pode usar a conta de serviço para acessar sua conta do Google Ads com o fluxo de declaração do OAuth 2.0.
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 e o ID da conta delegada na sua configuração.
Se você estiver usando um arquivo ads.properties, adicione o seguinte:
api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL
Consulte o guia de configuração para mais detalhes.
.NET
Configure as seguintes chaves no seu App.config / Web.config. Consulte o guia de configuração para mais detalhes.
<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />
<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />
Python
Defina o caminho JSON da chave privada e o e-mail representado 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
impersonated_email: IMPERSONATED_EMAIL
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
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL
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"
impersonatedEmail = "IMPERSONATED_EMAIL"
Ruby
Configure as seguintes chaves no google_ads_config.rb.
c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'
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
impersonatedEmail=IMPERSONATED_EMAIL
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
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL
Preocupações com segurança
Como a conta de serviço tem controle de delegação no nível do domínio para seu domínio do Google Workspace, é importante proteger o arquivo de chave que permite que uma conta de serviço acesse os Serviços do Google para os quais ela está autorizada. Isso é ainda mais importante porque essa conta de serviço pode representar qualquer usuário do domínio.
Outra prática recomendada é permitir que as contas de serviço acessem apenas o conjunto mínimo de APIs necessárias. Essa é uma medida preventiva para limitar a quantidade de dados que um invasor pode acessar se o arquivo de chave da conta de serviço for comprometido.