Wprowadzenie

Ten przewodnik zawiera krótkie omówienie tego, jak zacząć korzystać z interfejsu Google Ads API. .NET.

Instalacja

Pliki binarne biblioteki klienta są rozpowszechniane za pomocą NuGet. Dodaj odwołanie do NuGet do Google.Ads.GoogleAds pakiet do użycia w projekcie z biblioteki klienta.

Autoryzacja konfiguracji

Aby autoryzować wywołania interfejsu API, musisz podać swój identyfikator klienta, tajny klucz klienta token odświeżania i token programisty do biblioteki.

Jeśli musisz wygenerować dane logowania

Jeśli masz już dane logowania

  • Skopiuj węzeł GoogleAdsApi i sekcję GoogleAdsApi w sekcji configSections węzeł z pliku App.config w GitHub do pliku App.config / Web.config. Jeśli do zainstalowania te węzły zostaną automatycznie wstawione Plik App.config / Web.config.
  • Dołącz token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania w App.config / Web.config aplikacji.

App.config który znajduje się w serwisie GitHub, ale możesz również skorzystać Przewodnik po konfiguracji aby dowiedzieć się więcej i korzystać z alternatywnych sposobów konfigurowania biblioteki klienta, np. zmiennych środowiskowych.

Wywoływanie interfejsu API

Podstawowe wykorzystanie biblioteki klienta jest następujące:

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

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

// Make more calls to service class.

Tworzenie wystąpienia GoogleAdsClient

Najważniejszymi klasami w bibliotece .NET interfejsu Google Ads API są GoogleAdsClient zajęcia. Pozwala na utworzenie wstępnie skonfigurowanej klasy usługi które mogą być używane do wywoływania interfejsu API. GoogleAdsClient udostępnia domyślną wartość konstruktorem, który tworzy obiekt użytkownika, korzystając z ustawień określonych w App.config / Web.config aplikacji. Zapoznaj się z sekcją Konfiguracja przewodnika 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ługa Google Ads.

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

Udostępniamy klasę Services, która wylicza wszystkie obsługiwane wersje interfejsu API oraz usług Google. Metoda GetService akceptuje te obiekty wyliczenia jako argument podczas tworzenia usługi. Aby na przykład utworzyć instancję CampaignServiceClient w przypadku wersji V17 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService z Services.V17.CampaignService jako argument, jak pokazano na ilustracji z poprzedniego przykładu.

Bezpieczeństwo wątku

Udostępnianie wystąpienia GoogleAdsClient między wieloma wątkami nie jest bezpieczne, bo zmiany konfiguracji wprowadzone w instancji w jednym wątku mogą na usługi tworzone w innych wątkach. Operacje takie jak pozyskiwanie nowych instancji usługi z instancji GoogleAdsClient oraz wywołujących wiele usług równolegle jest bezpiecznych w wątku.

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ą spowodować, że niektóre aplikacje .NET Framework zablokować. Typowym przykładem są wywołania interfejsu API za pomocą 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 ustawić właściwość UseGrpcCore elementu GoogleAdsConfig tak, aby starsza wersja Grpc.Core zamiast domyślnej biblioteki Grpc.Net.Client. Metoda nie została dogłębnie przetestowana w aplikacjach .NET Framework, więc problem może nie rozwiązać. Oto przykładowy fragment kodu:

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

    Na stronie pomocy gRPC znajdziesz więcej na temat różnic między biblioteką starszego typu Grpc.Core a domyślną bibliotekę Grpc.Net.Client.

  2. Używaj metod asynchronicznych.

    Aby uniknąć zawieszenia urządzenia, możesz zastosować metody asynchroniczne. Oto przykłady:

    SearchStream

    Następuje wywołanie numeru SearchStream(), a wyniki są pojawi się w widoku listy.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V17.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 budżetu CampaignBudget, a nazwa zasobu nowego budżetu to wyświetlane przy użyciu alertu MessageBox.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V17.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ę sukcesem. Serwer może zgłaszać błędy, jeśli Twoje wywołania interfejsu API z jakiegoś powodu. Ważne jest rejestrowanie błędów interfejsu API i ich obsługa w odpowiedni sposób.

W przypadku błędu interfejsu API jest zgłaszane wystąpienie GoogleAdsException. Zawiera szczegółowe informacje, które pomogą Ci znaleźć przyczynę problemu:

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