Vamos começar

Este guia fornece uma breve visão geral sobre como começar a usar a biblioteca .NET da API Google Ads.

Instalação

Os binários da biblioteca de cliente são distribuídos usando o NuGet. Adicione uma referência do Nuget ao pacote Google.Ads.GoogleAds no seu projeto para usar a biblioteca de cliente.

Configure a autorização

Para autorizar suas chamadas de API, você precisa especificar o ID do cliente, a chave secreta do cliente, o token de atualização e o token de desenvolvedor na biblioteca.

Se você já tiver credenciais...

  • Copie o nó GoogleAdsApi e a seção GoogleAdsApi no nó configSections do arquivo App.config no GitHub para seu arquivo App.config/Web.config. Se você usou o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivo App.config/Web.config.
  • Inclua o token de desenvolvedor, o ID do cliente, a chave secreta do cliente e o token de atualização no App.config / Web.config do seu app. O arquivo App.config incluído no GitHub está bem documentado, mas você também pode consultar o Guia de configuração para saber mais e usar configurações alternativas.

Se você precisar gerar credenciais...

  • Siga o Guia do token de desenvolvedor para receber seu token de desenvolvedor, caso ainda não tenha um.
  • Siga as instruções do fluxo do app de área de trabalho OAuth para gerar um ID do cliente, uma chave secreta do cliente e um token de atualização.
  • Copie o nó GoogleAdsApi e a seção GoogleAdsApi no nó configSections do arquivo App.config no GitHub para seu arquivo App.config / Web.config. Se você usou o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivo App.config/Web.config.
  • Inclua o token de desenvolvedor, o ID do cliente, a chave secreta do cliente e o token de atualização no App.config / Web.config do seu app. O arquivo App.config incluído no GitHub está bem documentado, mas você também pode consultar o Guia de configuração para saber mais e usar configurações alternativas.

Fazer uma chamada de API

O uso básico da biblioteca de cliente é mostrado abaixo:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V11.CampaignService);

// Make more calls to service class.

Criar uma instância de GoogleAdsClient

As classes mais importantes da biblioteca .NET da API Google Ads são as GoogleAdsClient. Ela permite criar uma classe de serviço pré-configurada que pode ser usada para fazer chamadas de API. GoogleAdsClient fornece um construtor padrão que cria um objeto de usuário usando as configurações especificadas em App.config / Web.config do app. Consulte o Guia de configuração para ver várias opções de configuração.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Criar um serviço

GoogleAdsClient fornece um método GetService que pode ser usado para criar um serviço de anúncios.

CampaignServiceClient campaignService = client.GetService(Services.V11.CampaignService);
// Now make calls to CampaignService.

Fornecemos uma classe Services que enumera todas as versões e serviços de API compatíveis. O método GetService aceita esses objetos de enumeração como argumento ao criar o serviço. Por exemplo, se quiser criar uma instância de CampaignServiceClient para a versão V11 da API Google Ads, você precisará chamar o método GoogleAdsClient.GetService com Services.V11.CampaignService como argumento, conforme mostrado acima.

Segurança de linha de execução

Não é seguro compartilhar uma instância de GoogleAdsClient entre várias linhas de execução, já que as alterações de configuração feitas em uma instância em uma linha de execução podem afetar os serviços criados em outras linhas de execução. Operações como a aquisição de novas instâncias de serviço de uma instância GoogleAdsClient, a realização de chamadas para vários serviços em paralelo etc. são seguras para linhas de execução.

Um aplicativo com várias linhas de execução ficaria assim:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(client1);
userThread2.start(client2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  GoogleAdsClient client = (GoogleAdsClient) data;
  // Do more operations here.
  ...
}

Como cancelar métodos assíncronos

Para programação assíncrona, use o parâmetro callSettings para transmitir um CancellationToken:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V11.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

Tratamento de erros

Nem toda chamada de API terá êxito. O servidor pode gerar erros se suas chamadas de API falharem por algum motivo. É importante capturar erros da API e processá-los corretamente.

Uma instância GoogleAdsException é gerada quando ocorre um erro de API. Ela tem detalhes para ajudar você a descobrir o que deu errado:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V11.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}