Informationen für Einsteiger

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 Google.Ads.GoogleAds-Paket 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 Aktualisierungstoken und Entwicklertoken für die Bibliothek.

Wenn Sie Anmeldedaten generieren müssen

Wenn Sie bereits Anmeldedaten haben

  • Kopieren Sie den Knoten GoogleAdsApi und den Abschnitt GoogleAdsApi unter dem Knoten configSections aus der Datei App.config in GitHub in Ihre Datei App.config/Web.config. Wenn Sie zur Installation des werden diese Knoten automatisch in Ihren App.config / Web.config Datei.
  • Entwickler-Token, Client-ID, Clientschlüssel und Aktualisierungstoken angeben in der App.config / Web.config Ihrer App.

Die App.config der in GitHub enthaltenen Datei ist gut dokumentiert. Sie können aber auch Konfigurationsanleitung um mehr zu erfahren und alternative Möglichkeiten zur Konfiguration der Clientbibliothek zu nutzen. wie 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.V18.CampaignService);

// Make more calls to service class.

GoogleAdsClient-Instanz erstellen

Die wichtigsten Klassen in der Google Ads API-.NET-Bibliothek sind die Klasse GoogleAdsClient. Damit können Sie eine vorkonfigurierte Dienstklasse erstellen, die für API-Aufrufe verwendet werden kann. GoogleAdsClient bietet einen Standardkonstruktor, mit dem ein Nutzerobjekt mit den in App.config/Web.config Ihrer App angegebenen Einstellungen erstellt wird. Informationen zu den Konfigurationsoptionen finden Sie im Konfigurationsleitfaden.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Dienste erstellen

GoogleAdsClient bietet eine GetService-Methode zum Erstellen eines Anzeigendienst

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

Wir stellen eine Services-Klasse bereit, in der alle unterstützten API-Versionen und ‑Dienste aufgelistet sind. Die Methode GetService akzeptiert diese Aufzählungsobjekte als Argument wenn Sie den Dienst erstellen. Um beispielsweise eine Instanz von CampaignServiceClient für Version V18 der Google Ads API müssen Sie die Methode GoogleAdsClient.GetService mit Services.V18.CampaignService als Argument, wie gezeigt aus dem vorherigen Beispiel.

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 die Beschaffung neue Dienstinstanzen von einer GoogleAdsClient-Instanz erstellen und Aufrufe an mehrere Dienste gleichzeitig Thread-sicher sind.

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 der .NET Framework-Anwendungen vermeiden

Synchrone Methoden können dazu führen, dass einige Ihrer .NET Framework-Anwendungen einfrieren. Ein häufiges Beispiel sind API-Aufrufe aus einer Ereignishandlermethode einer WinForm-Anwendung.

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

  1. Verwenden Sie die alte Grpc-Bibliothek.

    Sie können das Attribut UseGrpcCore von GoogleAdsConfig festlegen, um die Methode alte Grpc.Core-Bibliothek anstelle der Grpc.Net.Client-Standardbibliothek. Diese Methode wurde noch nicht eingehend an .NET Framework-Anwendungen getestet, sodass das Problem möglicherweise nicht behoben wird. Hier ein Beispiel-Snippet:

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

    Auf der gRPC-Supportseite finden Sie weitere Informationen zu den Unterschieden zwischen der alten Grpc.Core-Bibliothek und der StandardGrpc.Net.Client-Bibliothek.

  2. Verwenden Sie asynchrone Methoden.

    Sie können asynchrone Methoden verwenden, um Einfrieren zu vermeiden. Hier einige Beispiele:

    SearchStream

    Es wird ein Aufruf von SearchStream() ausgeführt und die Ergebnisse werden in eine Listenansicht eingefügt.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V18.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 einer MessageBox-Benachrichtigung angezeigt.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V18.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 zu beheben. angemessen.

Eine GoogleAdsException-Instanz wird ausgelöst, wenn ein API-Fehler auftritt. Sie enthält um herauszufinden, was schiefgelaufen ist:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V18.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}");
}