Configuração

A biblioteca cliente da Google Ads API fornece 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:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "APPLICATION",
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Opções de configuração alternativas

Também fornecemos outras opções para configurar a biblioteca de cliente: para ativá-las, adicione uma referência do Nuget ao pacote Google.Ads.GoogleAds.Extensions no seu projeto.

Se você usar uma dessas opções, as configurações não serão selecionadas automaticamente: carregue-as explicitamente, conforme mostrado abaixo.

Configurar usando App.config

Todas as configurações específicas de Google Ads API são armazenadas no nó GoogleAdsApi do arquivo App.config. Uma configuração típica de App.config é a seguinte:

<?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=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

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

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

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

Especificar um arquivo App.config separado

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

Etapa 1: especificar um configSource em App.config

Modifique seu App.config para ficar assim:

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

Etapa 2: especificar o conteúdo do arquivo de configuração

Agora, crie outro arquivo de configuração com o nome especificado em configSource e mova o nó de configuração do App.config para esse arquivo:

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

Etapa 3: corrigir as regras de criação no CSS

Por fim, inclua o novo arquivo de configuração no seu projeto. Altere as propriedades desse arquivo para Sempre copiar para a pasta de saída.

Agora, crie e execute seu projeto. O aplicativo começará a coletar valores do novo arquivo de configuração.

Configuração usando um arquivo JSON personalizado

É possível usar uma instância de IConfigurationRoot para configurar a biblioteca de cliente.

Criar um arquivo JSON

Crie um arquivo JSON chamado GoogleAdsApi.json que tenha uma estrutura semelhante ao arquivo App.config.

{
    "Timeout": "2000",

    "ProxyServer": "http://localhost:8888",
    "ProxyUser": "",
    "ProxyPassword": "",
    "ProxyDomain": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

Carregar a configuração

Em seguida, carregue o arquivo JSON em um IConfigurationRoot.

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);

Configuração usando settings.json

O processo aqui é semelhante a usar um JSON personalizado, mas as chaves precisam estar em uma seção chamada GoogleAdsApi:

{
    "GoogleAdsApi":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

Em seguida, use a instância IConfiguration na sua página:

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

Configuração usando variáveis de ambiente

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

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

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

Campos de configuração

Veja a seguir a lista de configurações suportadas pela biblioteca .NET do Google Ads.

Configurações de conectividade

  • Timeout: use esta 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 mais baixo se precisar impor um limite mais curto ao tempo máximo para uma chamada de API. É possível definir o tempo limite como 2 horas ou mais, mas a API ainda pode expirar solicitações extremamente longas 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 que você precisa autenticar no servidor proxy. Deixe este campo em branco se um nome de usuário não for obrigatório.
  • ProxyPassword: defina como a senha de ProxyUser se você definir um valor para ProxyUser.
  • ProxyDomain: defina como o domínio para ProxyUser se o servidor proxy precisar de 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 MaxReceiveMessageLengthInBytes e MaxMetadataSizeInBytes para corrigir determinados erros ResourceExhausted. Essas configurações resolvem erros do formulário Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

Nesse exemplo, o erro ocorre porque o tamanho da mensagem (423184132 bytes) é maior do que a biblioteca consegue processar (67108864 bytes). Aumente MaxReceiveMessageLengthInBytes para 500000000 para evitar esse erro.

O erro também indica que seu código processou um objeto de resposta significativamente grande (como um SearchGoogleAdsResponse grande). Isso pode ter implicações no desempenho para seu código devido à pilha de objetos grandes do .NET. Se isso se tornar uma preocupação de desempenho, talvez seja necessário explorar como reorganizar as chamadas de API ou reprojetar partes do app.

Configurações do OAuth2

Ao usar o OAuth2 para autorizar suas chamadas para os servidores da Google Ads API, você precisa definir as seguintes chaves de configuração:

  • Defina AuthorizationMethod como OAuth2.
  • OAuth2Mode: definido como APPLICATION ou SERVICE_ACCOUNT.
  • OAuth2ClientId: defina esse valor como seu ID do cliente OAuth2.
  • OAuth2ClientSecret: defina esse valor como a chave secreta do cliente OAuth2.
  • OAuth2Scope: defina esse valor com escopos diferentes se quiser autorizar tokens OAuth2 para várias APIs. Esta configuração é opcional.

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 OAuth2 pré-gerado, se você quiser reutilizar tokens de OAuth2. Esta configuração é opcional.
  • OAuth2RedirectUri: defina esse valor como o URL de redirecionamento OAuth2. Essa configuração é opcional.

Consulte os guias a seguir para mais detalhes:

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

  • OAuth2PrnEmail: defina esse valor como o endereço de e-mail da conta que você está representando.
  • OAuth2SecretsJsonPath: defina esse valor como o caminho do arquivo de configuração JSON do OAuth2.

Consulte o guia sobre fluxo de conta de serviço 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 o guia de suporte do gRPC para mais detalhes.

Configurações da Google Ads API

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

  • DeveloperToken: defina como seu token de desenvolvedor.
  • LoginCustomerId: é o ID do cliente autorizado a ser usado na solicitação, sem hifens (-).
  • LinkedCustomerId: esse cabeçalho é necessário somente para métodos que atualizam os recursos de uma entidade quando permitido pelas contas vinculadas na IU do Google Ads (recurso AccountLink na Google Ads API). 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 contas vinculadas.