Questa guida fornisce una breve panoramica su come iniziare a utilizzare la libreria .NET dell'API Google Ads.
Installazione
I file binari della libreria client vengono distribuiti utilizzando NuGet. Aggiungi un riferimento Nuget al pacchetto Google.Ads.GoogleAds
nel progetto per utilizzare la libreria client.
Configura l'autorizzazione
Per autorizzare le chiamate API, devi specificare l'ID client, il client secret, il token di aggiornamento e il token sviluppatore nella libreria.
Se hai già le credenziali...
- Copia il nodo
GoogleAdsApi
e la sezioneGoogleAdsApi
sotto il nodoconfigSections
dal fileApp.config
di GitHub nel fileApp.config
/Web.config
. Se hai utilizzato NuGet per installare il pacchetto, questi nodi verranno inseriti automaticamente nel fileApp.config
/Web.config
. - Includi il token sviluppatore, l'ID client, il client secret e il token di aggiornamento
nell'elemento
App.config
/Web.config
della tua app. Il fileApp.config
incluso in GitHub è ben documentato, ma puoi anche fare riferimento alla guida alla configurazione per saperne di più e per utilizzare impostazioni di configurazione alternative.
Se devi generare le credenziali...
- Segui la guida sui token sviluppatore per ottenere il token sviluppatore, se non ne hai già uno.
- Segui la guida al flusso delle app desktop OAuth per generare un ID client, un client secret e un token di aggiornamento.
- Copia il nodo
GoogleAdsApi
e la sezioneGoogleAdsApi
sotto il nodoconfigSections
dal fileApp.config
di GitHub nel fileApp.config
/Web.config
. Se hai utilizzato NuGet per installare il pacchetto, questi nodi verranno inseriti automaticamente nel fileApp.config
/Web.config
. - Includi il token sviluppatore, l'ID client, il client secret e il token di aggiornamento
nell'elemento
App.config
/Web.config
della tua app. Il fileApp.config
incluso in GitHub è ben documentato, ma puoi anche fare riferimento alla guida alla configurazione per saperne di più e per utilizzare impostazioni di configurazione alternative.
Esegui una chiamata API
L'utilizzo di base della libreria client è illustrato di seguito:
// 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.
Crea un'istanza GoogleAdsClient
Le classi più importanti nella libreria .NET dell'API Google Ads sono
la classe GoogleAdsClient
. Consente di creare una classe di servizio
preconfigurata utilizzabile per effettuare chiamate API. GoogleAdsClient
fornisce un costruttore predefinito che crea un oggetto utente utilizzando le impostazioni specificate in App.config
/ Web.config
dell'app. Consulta la guida alla configurazione per le varie opzioni di configurazione.
// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();
Creare un Service
GoogleAdsClient
fornisce un metodo GetService
che può essere utilizzato per creare un
servizio Google Ads.
CampaignServiceClient campaignService = client.GetService(Services.V16.CampaignService);
// Now make calls to CampaignService.
Forniamo una classe Services
che elenca tutte le versioni API e i servizi supportati. Il metodo GetService
accetta questi oggetti di enumerazione come argomento durante la creazione del servizio. Ad esempio, per creare un'istanza di
CampaignServiceClient
per la versione V16
dell'API Google Ads,
devi chiamare il metodo GoogleAdsClient.GetService
con
Services.V16.CampaignService
come argomento, come mostrato
sopra.
Sicurezza dei thread
Non è sicuro condividere un'istanza GoogleAdsClient
tra più thread, poiché le modifiche alla configurazione apportate su un'istanza in un thread potrebbero influire sui servizi creati in altri thread. Operazioni come l'ottenimento di nuove istanze di servizio da un'istanza GoogleAdsClient
, l'esecuzione di chiamate a più servizi in parallelo e così via sono sicure per i thread.
Un'applicazione multithread potrebbe avere il seguente aspetto:
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.
...
}
Evitare blocchi nelle applicazioni .NET Framework
I metodi sincroni possono causare il blocco di alcune applicazioni .NET Framework. Un esempio comune è l'esecuzione di chiamate API da un metodo di gestore di eventi di un'applicazione WinForm.
Esistono due modi per risolvere questo problema:
Utilizza la libreria Grpc precedente.
Puoi impostare la proprietà
UseGrpcCore
diGoogleAdsConfig
in modo che utilizzi la libreriaGrpc.Core
precedente anziché la libreriaGrpc.Net.Client
predefinita. Questo metodo non è stato testato a fondo sulle applicazioni .NET Framework, pertanto potrebbe non risolvere il problema. Di seguito è riportato uno snippet di esempio:GoogleAdsConfig config = new GoogleAdsConfig(); config.UseGrpcCore = true; GoogleAdsClient client = new GoogleAdsClient(config);
Utilizza metodi asincroni.
Puoi utilizzare metodi asincroni per evitare blocchi. Ecco alcuni esempi:
SearchStream
Viene eseguita una chiamata a
SearchStream()
e i risultati vengono compilati in una visualizzazione elenco.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()); } Budget della campagna
Viene creata una chiamata CampaignBudget e il nome della risorsa del nuovo budget viene visualizzato utilizzando un avviso
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); }
Annullamento dei metodi asincroni
Per la programmazione asincrona, puoi utilizzare il parametro callSettings
per passare un 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
);
Gestione degli errori
Non tutte le chiamate API avranno esito positivo. Il server può restituire errori se le chiamate API non vanno a buon fine per qualche motivo. È importante acquisire gli errori dell'API e gestirli in modo appropriato.
Viene generata un'istanza GoogleAdsException
quando si verifica un errore dell'API. La pagina contiene
dettagli utili per capire cosa non ha funzionato:
// 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}");
}