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. 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ć 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 pod węzłem configSections z pliku App.config w GitHubzie do pliku App.config / Web.config. Jeśli pakiet został zainstalowany za pomocą NuGet, te węzły zostaną automatycznie wstawione do pliku App.config / Web.config.
  • Dołącz token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania w App.config / Web.config aplikacji.

Plik App.config z GitHuba jest dobrze udokumentowany, ale więcej informacji znajdziesz w przewodniku po konfiguracji. Możesz też użyć innych sposobów konfiguracji biblioteki klienta, na przykład zmiennych środowiskowych.

Wywoływanie interfejsu API

Podstawowe zastosowanie biblioteki klienta:

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

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

// Make more calls to service class.

Tworzenie wystąpienia GoogleAdsClient

Najważniejszymi klasami w bibliotece Google Ads API dla .NET są klasy GoogleAdsClient. 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. 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 Google Ads.

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

Udostępniamy klasę Services, która wylicza wszystkie obsługiwane wersje interfejsu API i usługi. Metoda GetService akceptuje te obiekty zbioru jako argument podczas tworzenia usługi. Aby na przykład utworzyć instancję CampaignServiceClient w przypadku wersji V18 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService z Services.V18.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 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ć zablokowanie niektórych aplikacji .NET Framework. 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.

    Aby użyć starszej biblioteki Grpc.Core zamiast domyślnej biblioteki Grpc.Net.Client, możesz ustawić właściwość UseGrpcCore obiektu GoogleAdsConfig. Ta metoda nie została dokładnie przetestowana w przypadku aplikacji .NET Framework, więc może się okazać, że nie rozwiąże ona problemu. 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ąć zawieszania się, możesz używać metod asynchronicznych. Oto przykłady:

    SearchStream

    Wywołanie funkcji SearchStream() powoduje wypełnienie widoku listy wynikami.

    private async void button1_Click(object sender, EventArgs e)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V18.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 za pomocą alertu MessageBox.

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V18.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 Twoje wywołania interfejsu API z jakiegoś powodu. Ważne jest, aby rejestrować błędy interfejsu API i odpowiednio je obsługiwać.

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

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