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 ein GoogleAdsClient konfigurieren und instanziieren. Anschließend können Sie damit die erforderlichen API-Dienstclients erstellen.

GoogleAdsClient-Instanz erstellen

Die wichtigste Klasse in der .NET-Bibliothek der Google Ads API ist die Klasse GoogleAdsClient. Damit können Sie einen vorkonfigurierten Dienstclient 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 Attribute 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-Dienstclient erstellt werden kann.

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

Die Bibliothek stellt eine Services-Klasse bereit, die alle unterstützten API-Versionen (wobei Nebenversionen wie v25.1 ihre Hauptversionsaufzählung Services.V25 verwenden) und Dienste auflistet. Die Methode GetService akzeptiert diese Aufzählungsobjekte als Argument, wenn der Dienst erstellt wird. 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 angemessen zu behandeln.

Eine GoogleAdsException-Instanz wird ausgelöst, wenn ein API-Fehler auftritt. Sie enthält Details, die Ihnen helfen, das Problem zu finden:

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 Aufrufen mehrerer Dienste sind jedoch threadsicher.

Wenn Sie Konfigurationsänderungen pro Thread isolieren möchten, instanziieren Sie für jede Worker-Aufgabe oder jeden Worker-Thread eine separate 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.
}

Anwendung reaktionsfähig halten

Je nach Größe der Anfragen kann es einige Zeit dauern, bis die Methodenaufrufe der Google Ads API abgeschlossen sind. So sorgen Sie dafür, dass Ihre Anwendung reaktionsschnell bleibt:

Bibliothek Grpc.Core 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, damit Ihre Anwendung reaktionsfähig bleibt. Hier sind ein paar Beispiele.

Rufen Sie die Liste der Kampagnen ab und füllen Sie ein ListView-Objekt aus.

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