Informationen für Einsteiger

Dieser Leitfaden bietet einen kurzen Überblick über die ersten Schritte mit der .NET-Bibliothek für die Google Ads API.

Installation

Die Binärdateien der Clientbibliotheken 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, das Aktualisierungstoken und das Entwickler-Token für die Bibliothek angeben.

Wenn Sie bereits über Anmeldedaten verfügen...

• Kopieren Sie den Knoten GoogleAdsApi und den Abschnitt GoogleAdsApi unter dem Knoten configSections aus der Datei App.config in GitHub in die Datei App.config oder Web.config. Wenn Sie das Paket mit NuGet installiert haben, werden diese Knoten automatisch in Ihre App.config- oder Web.config-Datei eingefügt.
• Gib das Entwickler-Token, die Client-ID, den Clientschlüssel und das Aktualisierungstoken im App.config / Web.config deiner App an. Die in GitHub enthaltene Datei App.config ist gut dokumentiert. Im Konfigurationsleitfaden finden Sie weitere Informationen und können alternative Konfigurationseinstellungen verwenden.

Anmeldedaten generieren

• Folgen Sie der Anleitung im Leitfaden zu Entwicklertokens, um ein Entwicklertoken zu erhalten, falls Sie noch keines haben.
• Folgen Sie dem Leitfaden für den OAuth-Desktop-App-Vorgang, um eine Client-ID, einen Clientschlüssel und ein Aktualisierungstoken zu generieren.
• Kopieren Sie den Knoten GoogleAdsApi und den Abschnitt GoogleAdsApi unter dem Knoten configSections aus der Datei App.config in GitHub in die Datei App.config oder Web.config. Wenn Sie das Paket mit NuGet installiert haben, werden diese Knoten automatisch in Ihre App.config- oder Web.config-Datei eingefügt.
• Gib das Entwickler-Token, die Client-ID, den Clientschlüssel und das Aktualisierungstoken im App.config / Web.config deiner App an. Die in GitHub enthaltene Datei App.config ist gut dokumentiert. Im Konfigurationsleitfaden finden Sie weitere Informationen und können alternative Konfigurationseinstellungen verwenden.

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.V16.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. Damit können Sie eine vorkonfigurierte Dienstklasse erstellen, die für API-Aufrufe verwendet werden kann. GoogleAdsClient stellt einen Standardkonstruktor bereit, der ein Nutzerobjekt mithilfe der Einstellungen erstellt, die in den App.config / Web.config Ihrer Anwendung 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 stellt eine GetService-Methode bereit, mit der ein Anzeigendienst erstellt werden kann.

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

Wir stellen eine Services-Klasse bereit, die alle unterstützten API-Versionen und -Dienste auflistet. Die Methode GetService akzeptiert diese Aufzählungsobjekte beim Erstellen des Dienstes als Argument. Wenn Sie beispielsweise eine Instanz von CampaignServiceClient für Version V16 der Google Ads API erstellen möchten, müssen Sie wie oben gezeigt die Methode GoogleAdsClient.GetService mit Services.V16.CampaignService als Argument aufrufen.

Threadsicherheit

Die gemeinsame Nutzung einer GoogleAdsClient-Instanz durch mehrere Threads ist nicht sicher, da die Konfigurationsänderungen, die Sie an einer Instanz in einem Thread vornehmen, sich auf die Dienste auswirken, die Sie in anderen Threads erstellen. Vorgänge wie das Abrufen neuer Dienstinstanzen von einer GoogleAdsClient-Instanz, das parallele Aufrufen mehrerer Dienste usw. sind Thread-sicher.

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 von einer Event-Handler-Methode einer WinForm-Anwendung.

Es gibt zwei Möglichkeiten, dieses Problem zu beheben:

1. Legacy-GRPC-Bibliothek verwenden

   Sie können das Attribut UseGrpcCore von GoogleAdsConfig so festlegen, dass die Legacy-Bibliothek Grpc.Core anstelle der Standardbibliothek Grpc.Net.Client verwendet wird. Diese Methode wurde nicht ausgiebig mit .NET Framework-Anwendungen getestet, sodass sie das Problem möglicherweise nicht löst. Hier ist ein Beispiel-Snippet:

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

2. Verwenden Sie asynchrone Methoden.

   Mit asynchronen Methoden können Sie Einfrierungen vermeiden. Hier sind einige Beispiele:

   SearchStream

   Ein Aufruf von SearchStream() wird ausgeführt und die Ergebnisse werden in einer Listenansicht dargestellt.

   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());
   }
   

   Kampagnenbudget

   Ein CampaignBudget-Aufruf wird erstellt und der Ressourcenname des neuen Budgets wird mithilfe einer MessageBox-Benachrichtigung angezeigt.

   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);
   }
   

Asynchrone Methoden abbrechen

Bei asynchroner Programmierung können Sie mit dem Parameter callSettings ein CancellationToken ü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.V16.GoogleAdsService);

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

Fehlerbehandlung

Nicht jeder API-Aufruf ist erfolgreich. Wenn Ihre API-Aufrufe aus irgendeinem Grund fehlschlagen, kann der Server Fehler ausgeben. Es ist wichtig, API-Fehler zu erfassen und entsprechend zu behandeln.

Eine GoogleAdsException-Instanz wird ausgegeben, 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.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}");
}