Pierwsze kroki

Ten przewodnik zawiera krótkie wprowadzenie do korzystania z biblioteki interfejsu Google Ads API w języku .NET.

Instalacja

Pliki binarne biblioteki klienta są rozpowszechniane za pomocą NuGet. Aby używać biblioteki klienta, dodaj odwołanie do pakietu NuGet Google.Ads.GoogleAds package w projekcie.

Autoryzacja konfiguracji

Aby autoryzować wywołania interfejsu API, musisz podać w bibliotece identyfikator klienta, klucz tajny klienta, token odświeżania i token dewelopera.

Jeśli musisz wygenerować dane logowania

Jeśli masz już dane logowania

  • Skopiuj węzeł GoogleAdsApi i sekcję GoogleAdsApi w węźle configSections z pliku App.config wGitHubie do pliku App.config / Web.config. Jeśli do zainstalowania pakietu użyto NuGet, te węzły zostaną automatycznie wstawione do pliku App.config / Web.config.
  • Uwzględnij w aplikacji token dewelopera, identyfikator klienta, klucz klienta i token odświeżania w pliku App.config / Web.config.

Plik App.config w GitHubie jest dobrze udokumentowany, ale możesz też zapoznać się z przewodnikiem po konfiguracji i dowiedzieć się więcej o alternatywnych sposobach konfigurowania biblioteki klienta, np. za pomocą zmiennych środowiskowych.

Wywoływanie interfejsu API

Podstawowe użycie biblioteki klienta wygląda tak:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

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

// Make more calls to service class.

Tworzenie instancji GoogleAdsClient

Najważniejszą klasą w bibliotece .NET interfejsu Google Ads API jest klasa GoogleAdsClient. Umożliwia utworzenie wstępnie skonfigurowanej klasy usługi, której można używać do wywoływania interfejsu API. GoogleAdsClient udostępnia domyślny konstruktor, który tworzy obiekt użytkownika na podstawie ustawień określonych w pliku App.config / Web.config aplikacji. Opcje konfiguracji znajdziesz w przewodniku po konfiguracji.

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

Utwórz usługę

GoogleAdsClient udostępnia metodę GetService, której można użyć do utworzenia usługi Ads.

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

Udostępniamy klasę Services, która zawiera listę wszystkich obsługiwanych wersji interfejsów API i usług. Metoda GetService akceptuje te obiekty wyliczeniowe jako argument podczas tworzenia usługi. Aby na przykład utworzyć instancję CampaignServiceClient dla wersji V20 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService z argumentem Services.V20.CampaignService, jak pokazano w poprzednim przykładzie.

Bezpieczeństwo wątków

Udostępnianie instancji GoogleAdsClient wielu wątkom nie jest bezpieczne, ponieważ zmiany konfiguracji wprowadzone w instancji w jednym wątku mogą wpływać na usługi tworzone w innych wątkach. Operacje takie jak uzyskiwanie nowych instancji usługi z instancji GoogleAdsClient i wykonywanie wywołań do wielu usług równolegle są bezpieczne dla wątków.

Aplikacja wielowątkowa wyglądałaby mniej więcej tak:

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.
  ...
}

Unikanie zawieszania się aplikacji .NET Framework

Metody synchroniczne mogą powodować zawieszanie się niektórych aplikacji .NET Framework. Częstym przykładem jest wywoływanie interfejsu API z metody obsługi zdarzeń aplikacji WinForm.

Ten problem można rozwiązać na 2 sposoby:

  1. Użyj starszej biblioteki Grpc.

    Możesz ustawić właściwość UseGrpcCore obiektu GoogleAdsConfig, aby używać starszej biblioteki Grpc.Core zamiast domyślnej biblioteki Grpc.Net.Client. Ta metoda nie została dokładnie przetestowana w przypadku aplikacji .NET Framework, więc może nie rozwiązać problemu. Oto przykładowy fragment kodu:

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

  2. Używaj metod asynchronicznych.

    Aby uniknąć zawieszania się aplikacji, możesz używać metod asynchronicznych. Oto przykłady:

    SearchStream

    Wywoływana jest funkcja SearchStream(), a wyniki są wyświetlane w widoku listy.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V20.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());
}

    Budżet kampanii

    Zostanie utworzone wywołanie CampaignBudget, a nazwa zasobu nowego budżetu zostanie wyświetlona za pomocą alertu MessageBox.

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

Obsługa błędów

Nie każde wywołanie interfejsu API zakończy się powodzeniem. Serwer może zgłaszać błędy, jeśli wywołania interfejsu API z jakiegoś powodu się nie powiodą. Ważne jest, aby rejestrować błędy interfejsu API i odpowiednio je obsługiwać.

Gdy wystąpi błąd interfejsu API, zgłaszana jest instancja GoogleAdsException. Zawiera ona szczegółowe informacje, które pomogą Ci ustalić, co poszło nie tak:

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