Contas de serviço

Neste guia, explicamos como acessar a API Google Ads usando contas de serviço.

Uma conta de serviço pertence ao app, não a um usuário final. As contas de serviço permitem interações de servidor para servidor entre um app da Web e um serviço do Google. O app chama as APIs do Google em nome da conta de serviço, para que os usuários não sejam diretamente envolvidos.

As contas de serviço empregam um fluxo do OAuth 2.0 que não requer autorização humana, usando um arquivo de chave que somente seu app pode acessar.

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

  • A autorização para o 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 imite outros usuários, se necessário.

Há duas maneiras de autorizar com contas de serviço: diretamente ou com impersonação.

Autorização com acesso direto à conta

Nessa opção, você concede à conta de serviço acesso direto à sua conta do Google Ads.

Configuração do 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. Navegue até Ferramentas e configurações > Configuração > 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 apropriado e clique no botão Adicionar conta.

  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 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 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 configuração. Se você estiver usando google-ads.yaml file, string YAML ou 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

PHP

Configure as chaves a seguir no 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 chaves a seguir no google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

Defina o caminho JSON da chave privada e o ID da conta delegado 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

Autorização usando falsificação de identidade

Nessa opção, você personifica 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 imitar usuários (endereços de e-mail) no mesmo Google Workspace.

Pré-requisitos

  • Um domínio do Google Workspace de sua propriedade, como mydomain.com ou mybusiness.com

  • Um token de desenvolvedor da API Google Ads e, opcionalmente, uma conta de teste

  • A biblioteca cliente para a linguagem que você está usando

  • Um projeto do Console de APIs do Google que foi configurado para a API Google Ads.

  • Um usuário do Google Ads com permissões na conta que você quer acessar. O Google Ads não oferece suporte para o uso de contas de serviço sem a identidade temporária.

Configuração do acesso à conta de serviço

Como a representação de 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 imitar qualquer usuário no domínio.

  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 da conta de serviço.

  2. 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.

    Solicite que o administrador do domínio delegue autoridade de todo o domínio à sua conta de serviço.

  3. Se você for 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 asserçã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 delegado na 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 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 uma google-ads.yaml file, uma string YAML ou 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 à configuração ou ao 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 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 chaves a seguir 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 delegado na 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 à configuração ou ao 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 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 é especialmente verdadeiro, porque essa conta de serviço pode representar qualquer usuário no 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 poderá acessar se o arquivo de chave da conta de serviço for comprometido.