In diesem Leitfaden erhalten Sie einen kurzen Überblick über die ersten Schritte mit der Google Ads API-Bibliothek für .NET.
Installation
Die Binärdateien der Clientbibliothek werden über NuGet verteilt. Fügen Sie dem Google.Ads.GoogleAds
-Paket in Ihrem Projekt einen NuGet-Verweis hinzu, um die Clientbibliothek zu verwenden.
Autorisierung einrichten
Um Ihre API-Aufrufe zu autorisieren, müssen Sie der Bibliothek Ihre Client-ID, Ihren Clientschlüssel, Ihr Aktualisierungstoken und Ihr Entwicklertoken angeben.
Anmeldedaten generieren
- Folgen Sie der Anleitung zum Entwicklertoken, um Ihr Entwicklertoken zu erhalten, falls Sie noch keines haben.
- Folgen Sie der Anleitung zum OAuth-Ablauf für Desktop-Apps, um eine Client-ID, ein Client-Secret und ein Aktualisierungstoken zu generieren.
Wenn Sie bereits Anmeldedaten haben
- Kopieren Sie den
GoogleAdsApi
-Knoten und denGoogleAdsApi
-Abschnitt unter demconfigSections
-Knoten aus der DateiApp.config
auf GitHub in Ihre DateiApp.config
/Web.config
. Wenn Sie das Paket mit NuGet installiert haben, werden diese Knoten automatisch in Ihre DateiApp.config
/Web.config
eingefügt. - Fügen Sie das Entwicklertoken, die Client-ID, den Clientschlüssel und das Aktualisierungstoken in die
App.config
/Web.config
Ihrer App ein.
Die Datei App.config
auf GitHub ist gut dokumentiert. Sie können aber auch den Konfigurationsleitfaden lesen, um mehr zu erfahren und alternative Möglichkeiten zur Konfiguration der Clientbibliothek zu nutzen, z. B. Umgebungsvariablen.
API aufrufen
Die grundlegende Verwendung der Clientbibliothek sieht so aus:
// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();
// Create the required service.
CampaignServiceClient campaignService =
client.GetService(Services.V20.CampaignService);
// Make more calls to service class.
GoogleAdsClient-Instanz erstellen
Die wichtigsten Klassen in der Google Ads API-Bibliothek für .NET sind die GoogleAdsClient
-Klassen. Damit können Sie eine vorkonfigurierte Dienstklasse erstellen, die für API-Aufrufe verwendet werden kann. GoogleAdsClient
bietet einen Standardkonstruktor, der ein Nutzerobjekt mit den in der App.config
/ Web.config
Ihrer App angegebenen Einstellungen erstellt. Informationen zu Konfigurationsoptionen finden Sie in der Konfigurationsanleitung.
// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();
Dienste erstellen
GoogleAdsClient
bietet eine GetService
-Methode, mit der ein Ads-Dienst erstellt werden kann.
CampaignServiceClient campaignService = client.GetService(Services.V20.CampaignService);
// Now make calls to CampaignService.
Wir stellen eine Services
-Klasse bereit, in der alle unterstützten API-Versionen und ‑Dienste aufgeführt sind. Die Methode GetService
akzeptiert diese Enumerationsobjekte als Argument beim Erstellen des Dienstes. Wenn Sie beispielsweise eine Instanz von CampaignServiceClient
für Version V20
der Google Ads API erstellen möchten, müssen Sie die Methode GoogleAdsClient.GetService
mit Services.V20.CampaignService
als Argument aufrufen, wie im vorherigen Beispiel gezeigt.
Threadsicherheit
Es ist nicht sicher, eine GoogleAdsClient
-Instanz für mehrere Threads freizugeben, da sich die Konfigurationsänderungen, die Sie an einer Instanz in einem Thread vornehmen, auf die Dienste auswirken können, die Sie in anderen Threads erstellen. Vorgänge wie das Abrufen neuer Dienstinstanzen aus einer GoogleAdsClient
-Instanz und das parallele Aufrufen mehrerer Dienste sind threadsicher.
Eine Multithread-Anwendung würde in etwa so aussehen:
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.
...
}
Einfrieren von .NET Framework-Anwendungen vermeiden
Synchrone Methoden können dazu führen, dass einige Ihrer .NET Framework-Anwendungen einfrieren. Ein häufiges Beispiel ist das Ausführen von API-Aufrufen über eine Ereignishandlermethode einer WinForm-Anwendung.
Es gibt zwei Möglichkeiten, dieses Problem zu beheben:
Alte Grpc-Bibliothek verwenden
Sie können die Property
UseGrpcCore
vonGoogleAdsConfig
festlegen, um die alteGrpc.Core
-Bibliothek anstelle der StandardbibliothekGrpc.Net.Client
zu verwenden. Diese Methode wurde nicht ausführlich mit .NET Framework-Anwendungen getestet und löst das Problem möglicherweise nicht. Hier ein Beispiel-Snippet:GoogleAdsConfig config = new GoogleAdsConfig(); config.UseGrpcCore = true; GoogleAdsClient client = new GoogleAdsClient(config);
Asynchrone Methoden verwenden:
Mit asynchronen Methoden können Sie verhindern, dass die App einfriert. Hier einige Beispiele:
SearchStream
Ein Aufruf von
SearchStream()
wird ausgeführt und die Ergebnisse werden in einer Listenansicht angezeigt.private async void button1_Click(object sender, EventArgs e) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V20.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()); } Kampagnenbudget
Ein CampaignBudget-Aufruf wird erstellt und der Ressourcenname des neuen Budgets wird mit einer
MessageBox
-Benachrichtigung angezeigt.private async void button2_Click(object sender, EventArgs e) { // Get the BudgetService. CampaignBudgetServiceClient budgetService = client.GetService( Services.V20.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); }
Fehlerbehandlung
Nicht jeder API-Aufruf ist erfolgreich. Der Server kann Fehler ausgeben, wenn Ihre API-Aufrufe aus irgendeinem Grund fehlschlagen. Es ist wichtig, API-Fehler zu erfassen und angemessen zu behandeln.
Eine GoogleAdsException
-Instanz wird ausgelöst, wenn ein API-Fehler auftritt. Sie enthält Details, die Ihnen helfen, herauszufinden, was schiefgelaufen ist:
// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V20.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}");
}