Grundlegende Nutzung

Die grundlegende Verwendung der .NET-Clientbibliothek sieht so aus:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V26.CampaignService);

// Make calls to the service client.

Client und Dienste initialisieren

Wenn Sie mit der Google Ads API interagieren möchten, müssen Sie zuerst einen GoogleAdsClient konfigurieren und instanziieren. Anschließend können Sie damit die spezifischen API-Service-Clients erstellen, die Sie benötigen.

GoogleAdsClient-Instanz erstellen

Die wichtigste Klasse in der Google Ads API .NET-Bibliothek ist die Klasse GoogleAdsClient. Damit können Sie einen vorkonfigurierten Service-Client erstellen, der für API-Aufrufe verwendet werden kann. Wenn Sie ein GoogleAdsClient-Objekt konfigurieren möchten, erstellen Sie ein GoogleAdsConfig-Objekt und legen Sie die erforderlichen Eigenschaften fest. Weitere Informationen finden Sie im Konfigurationsleitfaden.

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Modify the GoogleAdsClient configuration afterwards if needed.
client.Config.LoginCustomerId = "INSERT_UPDATED_LOGIN_CUSTOMER_ID_HERE";

Dienste erstellen

GoogleAdsClient bietet eine GetService-Methode, mit der ein API-Service-Client erstellt werden kann.

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

Die Bibliothek enthält eine Services-Klasse, in der alle unterstützten API -Versionen (wobei für Nebenversionen wie v25.1 die Enum-Klasse der Hauptversion, Services.V25, verwendet wird) und ‑Dienste aufgeführt sind. Die GetService-Methode akzeptiert diese Enumerationsobjekte als Argument beim Erstellen des Dienstes. Wenn Sie beispielsweise eine Instanz von CampaignServiceClient für Version V26 der Google Ads API erstellen möchten, rufen Sie die Methode GoogleAdsClient.GetService mit Services.V26.CampaignService als Argument auf, wie im vorherigen Beispiel gezeigt.

Fehlerbehandlung

Nicht jeder API-Aufruf ist erfolgreich. Der Server kann Fehler zurückgeben, wenn Ihre API-Aufrufe aus irgendeinem Grund fehlschlagen. Es ist wichtig, API-Fehler zu erfassen und entsprechend zu behandeln.

Bei einem API-Fehler wird eine GoogleAdsException-Instanz ausgelöst. Sie enthält Details, die Ihnen helfen, die Ursache des Fehlers zu ermitteln:

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

Threadsicherheit

Das Ändern des Konfigurationsstatus einer freigegebenen GoogleAdsClient-Instanz über mehrere Threads hinweg ist nicht threadsicher, 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. Schreibgeschützte Vorgänge wie das Abrufen neuer Dienstinstanzen aus einer unveränderlichen GoogleAdsClient-Instanz und das parallele Ausführen von Aufrufen an mehrere Dienste sind jedoch threadsicher.

Wenn Sie Konfigurationsänderungen pro Thread isolieren möchten, instanziieren Sie für jede Worker-Aufgabe oder jeden Thread einen separaten GoogleAdsClient:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Task task1 = Task.Run(() => AddAdGroups(client1));
Task task2 = Task.Run(() => AddAdGroups(client2));

await Task.WhenAll(task1, task2);

public void AddAdGroups(GoogleAdsClient client)
{
    // Perform operations with client.
}

Reaktionsfähigkeit der Anwendung beibehalten

Google Ads API-Methodenaufrufe können je nach Größe der Anfragen einige Zeit dauern. So sorgen Sie dafür, dass Ihre Anwendung reaktionsfähig bleibt:

Grpc.Core-Bibliothek für Legacy-UI-Frameworks verwenden

Wenn Sie eine Anwendung entwickeln, die auf .NET Framework ausgerichtet ist und eine Legacy-UI-Technologie wie ASP.NET Web Forms oder WinForms verwendet, können Sie die Legacy-Transportbibliothek Grpc.Core so aktivieren:

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

Asynchrone Methoden verwenden

Sie können asynchrone Methoden verwenden, um die Reaktionsfähigkeit Ihrer Anwendung zu erhalten. Hier sind einige Beispiele.

Liste der Kampagnen abrufen und ListView füllen

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the GoogleAdsService.
        GoogleAdsServiceClient googleAdsService = client.GetService(
            Services.V26.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<ListViewItem> items = new List<ListViewItem>();
        await googleAdsService.SearchStreamAsync(
            customerId.ToString(),
            query,
            (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);
                }
            }
        );
        listView1.Items.AddRange(items.ToArray());
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}

Kampagnenbudget aktualisieren und eine Meldungsbox-Warnung anzeigen

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V26.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 asynchronously.
        MutateCampaignBudgetsResponse response =
            await budgetService.MutateCampaignBudgetsAsync(
                customerId.ToString(),
                new CampaignBudgetOperation[] { budgetOperation });

        MessageBox.Show(response.Results[0].ResourceName);
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}