Configuração

A biblioteca de cliente da API Google Ads oferece várias definições de configuração que você pode usar para personalizar o comportamento da biblioteca.

Configurar a biblioteca no momento da execução

A maneira preferencial de configurar a biblioteca de cliente é inicializar um objeto GoogleAdsConfig no ambiente de execução:

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Opções de configuração alternativas

A biblioteca também oferece outras opções para carregar definições de configuração de appsettings.json, arquivos JSON personalizados, variáveis de ambiente ou App.config. Para ativá-los, instale o pacote NuGet Google.Ads.GoogleAds.Extensions no seu projeto:

dotnet add package Google.Ads.GoogleAds.Extensions

Se você usar uma dessas opções, as definições de configuração não serão selecionadas automaticamente. É preciso carregá-las explicitamente, conforme mostrado nas seções a seguir. Processe as exceções de E/S de arquivo (como FileNotFoundException ou UnauthorizedAccessException) ao carregar configurações de arquivos ou streams externos.

Usar appsettings.json ou settings.json

Em aplicativos .NET 8.0 e ASP.NET Core, coloque as chaves de configuração em uma seção GoogleAdsApi em appsettings.json (ou settings.json):

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

Em seguida, extraia a seção GoogleAdsApi da instância IConfiguration do aplicativo (por exemplo, injetada pelo ASP.NET Core ou criada com ConfigurationBuilder) e carregue-a com LoadFromConfigurationSection:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

Como alternativa, é possível carregar um arquivo appsettings.json ou settings.json diretamente pelo caminho usando LoadFromSettingsJson:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

Também é possível carregar o caminho da variável de ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) chamando config.TryLoadFromEnvironmentFilePath.

Usar um arquivo JSON personalizado

Também é possível usar uma instância IConfigurationRoot para carregar um arquivo JSON simples sem uma seção GoogleAdsApi de nível superior.

Criar um arquivo JSON

Crie um arquivo JSON chamado GoogleAdsApi.json que defina as chaves de configuração no nível raiz:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

Carregar a configuração

Em seguida, carregue o arquivo JSON em um IConfigurationRoot:

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

Usar variáveis de ambiente

Também é possível inicializar o GoogleAdsClient usando variáveis de ambiente:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

Observação :como GoogleAdsConfig.OAuth2Mode usa APPLICATION como padrão, ao autenticar com uma conta de serviço usando GOOGLE_ADS_JSON_KEY_FILE_PATH, defina também GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT.

Confira a lista completa de variáveis de ambiente compatíveis.

Usar o App.config

Nos aplicativos .NET Framework, todas as configurações específicas da API Google Ads são armazenadas no nó GoogleAdsApi do arquivo App.config. Uma configuração típica de App.config é assim:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

Para carregar as definições de configuração de um arquivo App.config, chame o método LoadFromDefaultAppConfigSection em um objeto GoogleAdsConfig:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

Especificar um arquivo de configuração App.config separado

Se você não quiser que o App.config fique desorganizado, mova a configuração específica da biblioteca para o próprio arquivo de configuração usando a propriedade configSource:

1. Especifique um configSource no seu App.config. Modifique o App.config para referenciar um arquivo de configuração externo:

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
     </configSections>
     <GoogleAdsApi configSource="GoogleAdsApi.config" />
   </configuration>
   

2. Especifique o conteúdo do arquivo de configuração. Crie outro arquivo de configuração com o nome especificado em configSource (GoogleAdsApi.config) e mova o nó de configuração GoogleAdsApi do App.config para esse arquivo:

   <?xml version="1.0" encoding="utf-8" ?>
   <GoogleAdsApi>
     <!-- More settings. -->
   </GoogleAdsApi>
   

3. Atualize as regras de build no .csproj. Inclua o novo arquivo de configuração no projeto e defina a propriedade Copiar para o diretório de saída como Sempre copiar. Recrie e execute o projeto para que o aplicativo use os valores do novo arquivo de configuração.

Usar um stream genérico

Também é possível carregar a configuração, ou partes dela, de um stream genérico, incluindo um criptografado:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

Campos de configuração

As seções a seguir listam as configurações compatíveis com a biblioteca .NET do Google Ads.

Configurações de conectividade

• Timeout: use essa chave para definir o tempo limite do serviço em milissegundos. O valor padrão é definido com base na configuração method_config/timeout em googleads_grpc_service_config.json. Defina um valor menor se precisar aplicar um limite menor ao tempo máximo de uma chamada de API. É possível definir o tempo limite como duas horas ou mais, mas a API ainda pode atingir o tempo limite de solicitações de execução extremamente longa e retornar um erro DEADLINE_EXCEEDED.
• ProxyServer: defina como o URL do servidor proxy HTTP se você estiver usando um proxy para se conectar à Internet.
• ProxyUser: defina como o nome de usuário necessário para autenticar no servidor proxy. Deixe em branco se um nome de usuário não for necessário.
• ProxyPassword: defina como a senha de ProxyUser se você tiver definido um valor para ProxyUser.
• ProxyDomain: defina como o domínio de ProxyUser se o servidor proxy exigir um.
• MaxReceiveMessageLengthInBytes: use essa configuração para aumentar o tamanho máximo da resposta da API que a biblioteca de cliente pode processar. O valor padrão é 64 MB.
• MaxMetadataSizeInBytes: use essa configuração para aumentar o tamanho máximo da resposta de erro da API que a biblioteca de cliente pode processar. O valor padrão é 16 MB.

Ajuste as configurações de MaxReceiveMessageLengthInBytes e MaxMetadataSizeInBytes para corrigir determinados erros de ResourceExhausted. Essas configurações abordam erros do tipo:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

Neste exemplo, o erro ocorre porque o tamanho da mensagem (423184132 bytes) é maior do que a biblioteca pode processar (67108864 bytes). Aumente MaxReceiveMessageLengthInBytes para 500000000 para evitar esse erro. O erro também indica que o código processou um objeto de resposta significativamente grande (como um SearchGoogleAdsResponse grande). Isso pode ter implicações de desempenho para o código devido ao Large Object Heap do .NET. Se isso se tornar um problema de desempenho, talvez seja necessário reorganizar as chamadas de API ou reformular partes do app.

Configurações do OAuth2

Ao usar o OAuth 2.0 para autorizar suas chamadas nos servidores da API Google Ads, defina as seguintes chaves de configuração:

• Defina AuthorizationMethod como OAuth2.
• OAuth2Mode: defina como APPLICATION ou SERVICE_ACCOUNT.
• OAuth2ClientId: defina esse valor como o ID do cliente OAuth 2.0.
• OAuth2ClientSecret: defina esse valor como a chave secreta do cliente OAuth 2.0.
• OAuth2Scope: defina esse valor como escopos diferentes se quiser autorizar tokens do OAuth 2.0 para várias APIs. Essa configuração é opcional.
• UseApplicationDefaultCredentials: defina esse valor como true para autenticar usando o Application Default Credentials (compatível com o Google.Ads.GoogleAds v24.1.0 e versões mais recentes; o config.LoadFromEnvironmentVariables() lê a variável de ambiente USE_APPLICATION_DEFAULT_CREDENTIALS sem prefixo).
• Credentials: (somente ambiente de execução, com suporte no v27.0.0 e versões mais recentes) injeta uma instância pré-construída de ICredential ou GoogleCredential diretamente em GoogleAdsConfig no ambiente de execução.

Se você estiver usando OAuth2Mode == APPLICATION, será necessário definir as seguintes chaves de configuração adicionais:

• OAuth2RefreshToken: defina esse valor como um token de atualização do OAuth 2.0 pré-gerado se quiser reutilizar tokens do OAuth 2.0. Essa configuração é opcional.
• OAuth2RedirectUri: defina esse valor como o URL de redirecionamento do OAuth 2.0. Essa configuração é opcional.

Consulte os guias a seguir para saber mais:

• Fluxo do aplicativo OAuth para computador
• Fluxo do aplicativo da Web OAuth

Se você estiver usando OAuth2Mode == SERVICE_ACCOUNT, será necessário definir as seguintes chaves de configuração adicionais:

• OAuth2SecretsJsonPath: defina esse valor como o caminho do arquivo de chave JSON do OAuth 2.0.
• OAuth2PrnEmail: defina esse valor como o endereço de e-mail da conta que você está representando ao usar a delegação em todo o domínio do Google Workspace. Essa configuração é opcional.

Consulte o guia Fluxo da conta de serviço do OAuth para mais detalhes.

Configurações de transporte

• UseGrpcCore: defina essa configuração como true para usar a biblioteca Grpc.Core como a camada de transporte subjacente. Consulte Usar a biblioteca Grpc.Core.

Configurações da API Google Ads

As configurações a seguir são específicas da API Google Ads:

• LoginCustomerId: Este é o ID de cliente autorizado a ser usado na solicitação, sem hífens (-).
• LinkedCustomerId: esse cabeçalho é obrigatório apenas para métodos que atualizam os recursos de uma entidade quando autorizados por contas vinculadas na interface do Google Ads (recurso AccountLink na API Google Ads). Defina esse valor como o ID de cliente do provedor de dados que atualiza os recursos do ID de cliente especificado. Ele precisa ser definido sem hifens (-). Saiba mais sobre as contas vinculadas.