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 com o NuGet. Adicione uma referência Nuget ao pacote Google.Ads.GoogleAds
(em inglês) no 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á tem credenciais...
- Copie o nó
GoogleAdsApi
e a seçãoGoogleAdsApi
no nóconfigSections
do arquivoApp.config
no GitHub para seu arquivoApp.config
/Web.config
. Se você usou o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivoApp.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 app. O arquivoApp.config
incluído no GitHub é 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 de token de desenvolvedor para receber seu token de desenvolvedor, se ainda não tiver um.
- Siga o guia de fluxo do aplicativo OAuth para computador para gerar um ID do cliente, uma chave secreta do cliente e um token de atualização.
- Copie o nó
GoogleAdsApi
e a seçãoGoogleAdsApi
no nóconfigSections
do arquivoApp.config
no GitHub para seu arquivoApp.config
/Web.config
. Se você usou o NuGet para instalar o pacote, esses nós serão inseridos automaticamente no arquivoApp.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 app. O arquivoApp.config
incluído no GitHub é 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.V17.CampaignService);
// Make more calls to service class.
Criar uma instância GoogleAdsClient
As classes mais importantes na biblioteca .NET da API Google Ads são GoogleAdsClient
. Ele permite 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 conhecer as diversas 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.V17.CampaignService);
// Now make calls to CampaignService.
Fornecemos uma classe Services
que enumera todas as versões e serviços 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 V17
da API Google Ads, você precisa chamar o método GoogleAdsClient.GetService
com Services.V17.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 em 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 é 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 .NET Framework
Os métodos síncronos podem fazer com que alguns aplicativos do .NET Framework congelem. Um exemplo comum é fazer chamadas de API usando um método de manipulador de eventos de um aplicativo WinForm.
Há duas maneiras de resolver esse problema:
Usar a biblioteca Grpc legada.
É possível definir a propriedade
UseGrpcCore
deGoogleAdsConfig
para usar a bibliotecaGrpc.Core
legada em vez da bibliotecaGrpc.Net.Client
padrão. Esse método não foi amplamente testado em aplicativos .NET Framework, por isso pode não resolver o problema. Aqui está um exemplo de snippet:GoogleAdsConfig config = new GoogleAdsConfig(); config.UseGrpcCore = true; GoogleAdsClient client = new GoogleAdsClient(config);
Use métodos assíncronos.
É possível 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.V17.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.V17.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
Em 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.V17.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 os erros da API e processá-los adequadamente.
Uma instância GoogleAdsException
é gerada quando ocorre um erro de API. Ela contém detalhes para ajudar você a descobrir o que deu errado:
// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V17.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}");
}