Pierwsze kroki

Z tego przewodnika dowiesz się, jak zacząć korzystać z biblioteki .NET interfejsu Google Ads API.

Instalacja

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

Autoryzacja konfiguracji

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

Jeśli masz już dane logowania...

  • Skopiuj węzeł GoogleAdsApi i sekcję GoogleAdsApi w węźle configSections z pliku App.config na GitHubie do pliku App.config / Web.config. Jeśli do zainstalowania pakietu użyjesz NuGeta, te węzły zostaną automatycznie wstawione do pliku App.config / Web.config.
  • Umieść token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania aplikacji w sekcji App.config / Web.config. Plik App.config dołączony do GitHuba jest dobrze udokumentowany, ale możesz też zajrzeć do przewodnika po konfiguracji, aby dowiedzieć się więcej i skorzystać z alternatywnych ustawień konfiguracji.

Jeśli musisz wygenerować dane logowania...

  • Aby uzyskać token programisty, postępuj zgodnie z przewodnikiem po tokenach programisty, jeśli jeszcze go nie masz.
  • Wykonaj instrukcje przebiegu procesu aplikacji komputerowej OAuth, aby wygenerować identyfikator klienta, tajny klucz klienta i token odświeżania.
  • Skopiuj węzeł GoogleAdsApi i sekcję GoogleAdsApi w węźle configSections z pliku App.config na GitHubie do pliku App.config / Web.config. Jeśli do zainstalowania pakietu użyjesz NuGeta, te węzły zostaną automatycznie wstawione do pliku App.config / Web.config.
  • Umieść token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania aplikacji w sekcji App.config / Web.config. Plik App.config dołączony do GitHuba jest dobrze udokumentowany, ale możesz też zajrzeć do przewodnika po konfiguracji, aby dowiedzieć się więcej i skorzystać z alternatywnych ustawień konfiguracji.

Wywoływanie interfejsu API

Podstawowe informacje o korzystaniu z biblioteki klienta zostały przedstawione poniżej:

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

Tworzenie wystąpienia GoogleAdsClient

Najważniejsze klasy w bibliotece .NET interfejsu Google Ads API to klasa GoogleAdsClient. Pozwala utworzyć wstępnie skonfigurowaną klasę usługi, której można używać do wykonywania wywołań interfejsu API. GoogleAdsClient udostępnia domyślny konstruktor, który tworzy obiekt użytkownika przy użyciu ustawień określonych w App.config / Web.config Twojej aplikacji. Informacje o różnych opcjach 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 Google Ads.

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

Udostępniamy klasę Services, która zawiera listę wszystkich obsługiwanych wersji interfejsu API i usług. Metoda GetService akceptuje te obiekty wyliczenia jako argumenty podczas tworzenia usługi. Aby np. utworzyć wystąpienie CampaignServiceClient w przypadku wersji V16 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService z argumentem Services.V16.CampaignService, jak pokazano powyżej.

Bezpieczeństwo wątków

Udostępnianie instancji GoogleAdsClient między wieloma wątkami nie jest bezpieczne, ponieważ zmiany konfiguracji wprowadzone w jednym wątku mogą mieć wpływ na usługi tworzone w innych wątkach. Operacje takie jak uzyskiwanie nowych instancji usługi z instancji GoogleAdsClient, równoległe wywoływanie wielu usług itp. są bezpieczne w wątkach.

Aplikacja wielowątkowa wyglądałaby 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ę w aplikacjach .NET Framework

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

Problem ten można rozwiązać na 2 sposoby:

  1. Użyj starszej biblioteki Grpc.

    Możesz skonfigurować właściwość UseGrpcCore elementu GoogleAdsConfig w taki sposób, aby używała starszej biblioteki Grpc.Core zamiast domyślnej biblioteki Grpc.Net.Client. Ta metoda nie została dokładnie przetestowana w aplikacjach .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żywanie metod asynchronicznych.

    Aby uniknąć blokady, możesz użyć metod asynchronicznych. Oto przykłady:

    SearchStream

    Stosowane jest wywołanie funkcji SearchStream(), a wyniki wyświetlają się w widoku listy.

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

    Budżet kampanii

    Zostanie utworzone wywołanie CampaignBudget, a nazwa zasobu nowego budżetu jest wyświetlana w alercie MessageBox.

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

Anulowanie metod asynchronicznych

W przypadku programowania asynchronicznego możesz użyć parametru callSettings, aby przekazać CancellationToken:

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

Obsługa błędów

Nie każde wywołanie interfejsu API kończy się powodzeniem. Serwer może zgłosić błędy, jeśli z jakiegoś powodu wywołania interfejsu API się nie udają. Ważne jest, aby wykrywać błędy interfejsu API i odpowiednio je naprawiać.

W przypadku błędu interfejsu API wywoływane jest wystąpienie GoogleAdsException. Znajdziesz tam szczegółowe informacje, które pomogą Ci ustalić, co poszło nie tak:

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