Pierwsze kroki

Ten przewodnik zawiera krótkie omówienie tego, 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 odwołanie do Nuget do pakietu Google.Ads.GoogleAds w projekcie.

Autoryzacja konfiguracji

Aby autoryzować wywołania interfejsu API, musisz podać w bibliotece swój 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 w GitHubie do pliku App.config / Web.config. Jeśli do zainstalowania pakietu użyjesz NuGet, 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 w App.config / Web.config aplikacji. Plik App.config dołączony do GitHuba jest dobrze udokumentowany, ale możesz również skorzystać z przewodnika po konfiguracji, aby dowiedzieć się więcej i użyć alternatywnych ustawień konfiguracji.

Jeśli musisz wygenerować dane logowania...

  • Wykonaj instrukcje z przewodnika dla programistów, aby uzyskać swój token programisty, jeśli jeszcze go nie masz.
  • Postępuj zgodnie z przewodnikiem po przepływie 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 w GitHubie do pliku App.config / Web.config. Jeśli do zainstalowania pakietu użyjesz NuGet, 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 w App.config / Web.config aplikacji. Plik App.config dołączony do GitHuba jest dobrze udokumentowany, ale możesz również skorzystać z przewodnika po konfiguracji, aby dowiedzieć się więcej i użyć alternatywnych ustawień konfiguracji.

Wywoływanie interfejsu API

Poniżej przedstawiliśmy podstawowe informacje o korzystaniu z biblioteki klienta:

// 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żniejsze klasy w bibliotece .NET interfejsu Google Ads API to klasa GoogleAdsClient. Umożliwia utworzenie wstępnie skonfigurowanej klasy usługi, której można używać do wywołań interfejsu API. GoogleAdsClient udostępnia domyślny konstruktor tworzący obiekt użytkownika zgodnie z ustawieniami określonymi w App.config / Web.config 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.V17.CampaignService);
// Now make calls to CampaignService.

Udostępniamy klasę Services, która wylicza wszystkie obsługiwane wersje i usługi interfejsu API. Metoda GetService akceptuje te obiekty wyliczenia jako argument podczas tworzenia usługi. Aby np. utworzyć instancję CampaignServiceClient dla wersji V17 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService z argumentem Services.V17.CampaignService, jak pokazano powyżej.

Bezpieczeństwo wątku

Udostępnianie instancji GoogleAdsClient między wieloma wątkami nie jest bezpieczne, ponieważ zmiany konfiguracji wprowadzane w instancji w jednym wątku mogą mieć wpływ na usługi tworzone w innych wątkach. Operacje takie jak pozyskiwanie nowych instancji usługi z instancji GoogleAdsClient, równoległe wywołania wielu usług itp. są bezpieczne w przypadku 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ć blokowanie niektórych aplikacji .NET Framework. Typowym przykładem są wywołania interfejsu API za pomocą metody 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 usługi GoogleAdsConfig, aby używać 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żywaj metod asynchronicznych.

    Aby uniknąć zawieszenia urządzenia, możesz zastosować metody asynchroniczne. Oto kilka przykładów:

    SearchStream

    Wywoływanie funkcji SearchStream() powoduje wyświetlenie wyników 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 jest wyświetlana za pomocą 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);
}

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.V17.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 zakończy się sukcesem. Serwer może zgłaszać błędy, jeśli z jakiegoś powodu wywołania interfejsu API nie zostaną zrealizowane. Ważne jest rejestrowanie błędów interfejsu API i odpowiednie reagowanie na nie.

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

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