Autenticação e autorização

Como outras APIs do Google, a API Google Ads usa o protocolo OAuth 2.0 para autenticação e autorização. O OAuth 2.0 permite que o app cliente .NET da API Google Ads acesse a conta do Google Ads de um usuário sem precisar processar ou armazenar as informações de login do usuário.

Entender o modelo de acesso do Google Ads

Para trabalhar de forma eficaz com a API Google Ads, entenda como o modelo de acesso do Google Ads funciona. Consulte o guia do modelo de acesso do Google Ads.

Fluxos de trabalho do OAuth

Há três fluxos de trabalho comuns usados ao trabalhar com a API Google Ads.

Fluxo da conta de serviço

Esse é o fluxo de trabalho recomendado se o aplicativo não exigir interação humana. Esse fluxo de trabalho exige uma etapa de configuração, em que o usuário adiciona uma conta de serviço à conta do Google Ads. Em seguida, o app pode usar as credenciais da conta de serviço para gerenciar a conta do Google Ads do usuário.

Configure a biblioteca da seguinte maneira:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

Consulte o guia do fluxo de trabalho da conta de serviço para saber mais.

Fluxo de autenticação de usuário único

Esse fluxo de trabalho pode ser usado se você não puder usar contas de serviço. Esse fluxo de trabalho exige duas etapas de configuração:

  1. Conceda a um único usuário acesso a todas as contas a serem gerenciadas usando a API Google Ads. Uma abordagem comum é conceder ao usuário acesso a uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a essa conta de administrador.
  2. O usuário executa uma ferramenta de linha de comando, como gcloud ou o exemplo de código GenerateUserCredentials para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

Inicialize a biblioteca usando as credenciais do OAuth 2.0 do usuário da seguinte maneira:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Consulte o guia do fluxo de trabalho de autenticação de usuário único para saber mais.

Fluxo de autenticação multiusuário

Esse é o fluxo de trabalho recomendado se o app permitir que os usuários façam login e autorizem o app a gerenciar as contas do Google Ads em nome deles. O app cria e gerencia as credenciais de usuário do OAuth 2.0 dinamicamente por sessão ou solicitação do usuário e, em seguida, inicializa um GoogleAdsClient com o token de atualização do usuário ativo:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

A partir do Google.Ads.GoogleAds v27.0.0, também é possível injetar um objeto ICredential ou GoogleCredential pré-configurado diretamente no GoogleAdsConfig usando a propriedade Credentials.

Consulte o guia do fluxo de trabalho de autenticação multiusuário para saber mais. A biblioteca de cliente .NET inclui dois exemplos de código para referência:

  1. O AuthenticateInAspNetCoreApplication exemplo de código ilustra como criar um app da Web que recebe a autenticação do usuário no momento da execução para gerenciar as contas do Google Ads em nome dele. O app usa as credenciais do OAuth 2.0 do usuário para recuperar as campanhas na conta do Google Ads.
  2. O exemplo de código de linha de comando GenerateUserCredentials ilustra como receber a autenticação do usuário no momento da execução para gerenciar as contas do Google Ads em nome dele. Você pode usar esse exemplo de código como referência para criar apps para computador que exigem autenticação do usuário.

E se o usuário gerenciar várias contas?

É comum que um usuário gerencie mais de uma conta do Google Ads, seja por acesso direto às contas ou por uma conta de administrador do Google Ads. A biblioteca de cliente .NET fornece os seguintes exemplos de código que ilustram como lidar com esses casos:

  1. O exemplo de código GetAccountHierarchy mostra como recuperar a lista de todas as contas em uma conta de administrador do Google Ads.
  2. O exemplo de código ListAccessibleCustomers mostra como recuperar a lista de todas as contas a que um usuário tem acesso direto Essas contas podem ser usadas como valores válidos para a configuração LoginCustomerId.

Application Default Credentials

A biblioteca de cliente .NET (v24.1.0 e versões mais recentes) também oferece suporte à autenticação com o Application Default Credentials.

Isso é particularmente útil para desenvolvimento local ou para desenvolvimento em diferentes APIs do Google, já que você pode reutilizar as mesmas credenciais, desde que elas possam acessar os escopos do OAuth 2.0 necessários.

Para a API Google Ads, verifique se o Application Default Credentials pode acessar o escopo do OAuth 2.0 https://www.googleapis.com/auth/adwords.

Para usar o Application Default Credentials, defina a UseApplicationDefaultCredentials opção como true no seu GoogleAdsConfig (ou defina a variável de ambiente USE_APPLICATION_DEFAULT_CREDENTIALS=true ao carregar a configuração com config.LoadFromEnvironmentVariables()):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Consulte a página de configuração para mais detalhes sobre as opções disponíveis para configurar a biblioteca de cliente .NET.