In diesem Leitfaden erhalten Sie einen kurzen Überblick über die ersten Schritte mit der .NET-Bibliothek der Google Ads API.
Installation
Die Binärdateien der Clientbibliothek werden mithilfe von NuGet verteilt. Fügen Sie dem Paket Google.Ads.GoogleAds
in Ihrem Projekt eine Nuget-Referenz hinzu, um die Clientbibliothek zu verwenden.
Autorisierung einrichten
Zum Autorisieren Ihrer API-Aufrufe müssen Sie Ihre Client-ID, Ihren Clientschlüssel, ein Aktualisierungstoken und ein Entwicklertoken für die Bibliothek angeben.
Wenn Sie bereits Anmeldedaten haben...
- Kopieren Sie den Knoten
GoogleAdsApi
und den AbschnittGoogleAdsApi
unter dem KnotenconfigSections
aus der DateiApp.config
in GitHub in die DateiApp.config
/Web.config
. Wenn Sie zum Installieren des Pakets NuGet verwendet haben, werden diese Knoten automatisch in die DateiApp.config
/Web.config
eingefügt. - Fügen Sie das Entwicklertoken, die Client-ID, den Clientschlüssel und das Aktualisierungstoken in die Datei
App.config
/Web.config
Ihrer Anwendung ein. Die in GitHub enthaltene DateiApp.config
ist gut dokumentiert. Weitere Informationen und die Verwendung alternativer Konfigurationseinstellungen finden Sie im Konfigurationsleitfaden.
Wenn Sie Anmeldedaten generieren müssen...
- Falls Sie noch kein Entwicklertoken haben, folgen Sie der Anleitung für Entwicklertokens.
- Folge der Anleitung unter OAuth-Desktopanwendung, um eine Client-ID, einen Clientschlüssel und ein Aktualisierungstoken zu generieren.
- Kopieren Sie den Knoten
GoogleAdsApi
und den AbschnittGoogleAdsApi
unter dem KnotenconfigSections
aus der DateiApp.config
in GitHub in die DateiApp.config
/Web.config
. Wenn Sie zum Installieren des Pakets NuGet verwendet haben, werden diese Knoten automatisch in die DateiApp.config
/Web.config
eingefügt. - Fügen Sie das Entwicklertoken, die Client-ID, den Clientschlüssel und das Aktualisierungstoken in die Datei
App.config
/Web.config
Ihrer Anwendung ein. Die in GitHub enthaltene DateiApp.config
ist gut dokumentiert. Weitere Informationen und die Verwendung alternativer Konfigurationseinstellungen finden Sie im Konfigurationsleitfaden.
API aufrufen
Im Folgenden wird die grundlegende Verwendung der Clientbibliothek dargestellt:
// 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.
GoogleAdsClient-Instanz erstellen
Die wichtigste Klasse in der .NET-Bibliothek der Google Ads API ist die Klasse GoogleAdsClient
. Sie können damit eine vorkonfigurierte Dienstklasse erstellen, die für API-Aufrufe verwendet werden kann. GoogleAdsClient
stellt einen Standardkonstruktor bereit, der ein Nutzerobjekt anhand der Einstellungen erstellt, die in App.config
/ Web.config
Ihrer App festgelegt sind. In der Konfigurationsanleitung finden Sie verschiedene Konfigurationsoptionen.
// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();
Dienste erstellen
GoogleAdsClient
bietet eine GetService
-Methode, mit der ein Google Ads-Dienst erstellt werden kann.
CampaignServiceClient campaignService = client.GetService(Services.V17.CampaignService);
// Now make calls to CampaignService.
Wir stellen eine Services
-Klasse zur Verfügung, die alle unterstützten API-Versionen und -Dienste auflistet. Beim Erstellen des Dienstes akzeptiert die Methode GetService
diese Aufzählungsobjekte als Argument. Wenn Sie beispielsweise eine Instanz von CampaignServiceClient
für Version V17
der Google Ads API erstellen möchten, müssen Sie die Methode GoogleAdsClient.GetService
mit Services.V17.CampaignService
als Argument aufrufen, wie oben gezeigt.
Threadsicherheit
Es ist nicht sicher, eine GoogleAdsClient
-Instanz zwischen mehreren Threads zu teilen, da Konfigurationsänderungen, die Sie an einer Instanz in einem Thread vornehmen, sich auf die Dienste auswirken können, die Sie in anderen Threads erstellen. Vorgänge wie das Abrufen neuer Dienstinstanzen von einer GoogleAdsClient
-Instanz, das parallele Aufrufen mehrerer Dienste usw. 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 gängiges Beispiel sind API-Aufrufe über eine Event-Handler-Methode einer WinForm-Anwendung.
Es gibt zwei Möglichkeiten, dieses Problem zu beheben:
Legacy-GRPC-Bibliothek verwenden
Sie können das Attribut
UseGrpcCore
vonGoogleAdsConfig
festlegen, um die Legacy-BibliothekGrpc.Core
anstelle der StandardbibliothekGrpc.Net.Client
zu verwenden. Diese Methode wurde noch nicht umfassend in .NET Framework-Anwendungen getestet, sodass das Problem möglicherweise nicht behoben wird. Hier ist ein Beispiel-Snippet:GoogleAdsConfig config = new GoogleAdsConfig(); config.UseGrpcCore = true; GoogleAdsClient client = new GoogleAdsClient(config);
Verwenden Sie asynchrone Methoden.
Sie können asynchrone Methoden verwenden, um ein "Fixieren" zu vermeiden. Hier einige Beispiele:
SearchStream
Es wird ein Aufruf von
SearchStream()
ausgeführt und die Ergebnisse werden in eine Listenansicht dargestellt.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()); } Kampagnenbudget
Es wird ein CampaignBudget-Aufruf erstellt und der Ressourcenname des neuen Budgets wird in der Benachrichtigung
MessageBox
angezeigt.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); }
Asynchrone Methoden abbrechen
Für die asynchrone Programmierung können Sie den Parameter callSettings
verwenden, um CancellationToken
zu übergeben:
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
);
Fehlerbehandlung
Nicht jeder API-Aufruf ist erfolgreich. Der Server kann Fehler ausgeben, wenn Ihre API-Aufrufe aus irgendeinem Grund fehlschlagen. API-Fehler müssen erfasst und entsprechend behandelt werden.
Eine GoogleAdsException
-Instanz wird ausgelöst, wenn ein API-Fehler auftritt. Es enthält Details, mit denen Sie herausfinden können, was schiefgelaufen ist:
// 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}");
}