Como começar

Este guia fornece uma breve visão geral de 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 com o NuGet. Adicione uma referência do Nuget ao pacote Google.Ads.GoogleAds (link em inglês) no seu projeto para usar a biblioteca de cliente.

configure a autorização

Para autorizar suas chamadas de API, especifique o ID do cliente, a chave secreta do cliente, o token de atualização e o token de desenvolvedor para a 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ê tiver usado o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivo App.config / Web.config.
• Inclua o token de desenvolvedor, ID do cliente, chave secreta do cliente e 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 definições de configuração alternativas.

Se você precisar gerar credenciais...

• Siga o guia sobre token de desenvolvedor para receber seu token de desenvolvedor, caso ainda não tenha um.
• Siga o guia de fluxo de aplicativos para computador 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ê tiver usado o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivo App.config / Web.config.
• Inclua o token de desenvolvedor, ID do cliente, chave secreta do cliente e 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 definições de configuração alternativas.

Fazer uma chamada de API

Confira abaixo o uso básico da biblioteca de cliente:

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

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

// Make more calls to service class.

Criar uma instância GoogleAdsClient

A classe mais importante na biblioteca .NET da API Google Ads é a GoogleAdsClient. Com ele, é possível criar uma classe de serviço pré-configurada que pode ser usada para fazer chamadas de API. O GoogleAdsClient fornece um construtor padrão que cria um objeto de usuário usando as configurações especificadas no App.config / Web.config do app. Consulte o Guia de configuração para 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 do Google Ads.

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

Fornecemos uma classe Services que enumera todos os serviços e versões da API compatíveis. O método GetService aceita esses objetos de enumeração como argumento ao criar o serviço. Por exemplo, para criar uma instância de CampaignServiceClient para a versão V16 da API Google Ads, você precisa chamar o método GoogleAdsClient.GetService com Services.V16.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 mudanças de configuração feitas em uma instância de uma linha de execução podem afetar os serviços criados em outras linhas de execução. Operações como receber novas instâncias de serviço de uma instância GoogleAdsClient, fazer chamadas para vários serviços em paralelo etc., são thread-safe.

Um aplicativo com várias linhas de execução seria mais ou menos 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 evitar congelamentos em aplicativos do .NET Framework

Os métodos síncronos podem fazer com que alguns aplicativos do .NET Framework congelam. Um exemplo comum é fazer chamadas de API de um método de manipulador de eventos de um aplicativo WinForm.

Há duas maneiras de resolver esse problema:

1. Use a biblioteca Grpc legada.

   Você pode definir a propriedade UseGrpcCore de GoogleAdsConfig para usar a biblioteca Grpc.Core legada em vez da biblioteca Grpc.Net.Client padrão. Como esse método não foi extensivamente testado em aplicativos .NET Framework, pode não resolver o problema. Confira um exemplo de snippet:

   GoogleAdsConfig config = new GoogleAdsConfig();
   config.UseGrpcCore = true;
   GoogleAdsClient client = new GoogleAdsClient(config);
   

2. Use métodos assíncronos.

   Você pode usar métodos assíncronos para evitar congelamentos. Confira alguns exemplos:

   SearchStream

   Uma chamada para SearchStream() é realizada, e os resultados são preenchidos em uma visualização em lista.

   private async void button1_Click(object sender, EventArgs e)
   {
   // Get the GoogleAdsService.
   GoogleAdsServiceClient googleAdsService = client.GetService(
       Services.V16.GoogleAdsService);
    
   // Create a query that will retrieve all campaigns.
   string query = @"SELECT
                   campaign.id,
                   campaign.name,
                   campaign.network_settings.target_content_network
               FROM campaign
               ORDER BY campaign.id";
    
   List items = new List();
   Task t =  googleAdsService.SearchStreamAsync(customerId.ToString(), query,
       delegate (SearchGoogleAdsStreamResponse resp)
       {
           foreach (GoogleAdsRow googleAdsRow in resp.Results)
           {
               ListViewItem item = new ListViewItem();
               item.Text = googleAdsRow.Campaign.Id.ToString();
               item.SubItems.Add(googleAdsRow.Campaign.Name);
               items.Add(item);
           }
       }
   );
   await t;
   listView1.Items.AddRange(items.ToArray());
   }
   

   Orçamento da campanha

   Uma chamada CampaignBudget é criada, e o nome do recurso do novo orçamento é exibido usando um alerta MessageBox.

   private async void button2_Click(object sender, EventArgs e)
   {
   // Get the BudgetService.
   CampaignBudgetServiceClient budgetService = client.GetService(
       Services.V16.CampaignBudgetService);
    
   // Create the campaign budget.
   CampaignBudget budget = new CampaignBudget()
   {
       Name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
       DeliveryMethod = BudgetDeliveryMethod.Standard,
       AmountMicros = 500000
   };
    
   // Create the operation.
   CampaignBudgetOperation budgetOperation = new CampaignBudgetOperation()
   {
       Create = budget
   };
    
   // Create the campaign budget.
   Task t = budgetService.MutateCampaignBudgetsAsync(
       customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });
    
   await t;
   MutateCampaignBudgetsResponse response = t.Result;
   MessageBox.Show(response.Results[0].ResourceName);
   }
   

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.V16.GoogleAdsService);

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

Tratamento de erros

Nem todas as chamadas de API serão bem-sucedidas. O servidor poderá gerar erros se as chamadas de API falharem por algum motivo. É importante capturar erros de API e processá-los adequadamente.

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

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V16.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}");
}