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 korzystać z biblioteki klienta, dodaj odwołanie 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 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.
  • W elementach App.config / Web.config aplikacji podaj token dewelopera, identyfikator klienta, klucz klienta i token odświeżania.

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 instancji GoogleAdsClient

Najważniejszymi klasami w bibliotece .NET interfejsu Google Ads API jest klasa GoogleAdsClient. Umożliwia ona utworzenie wstępnie skonfigurowanej klasy usługi, której można używać do wywoływania interfejsów API. GoogleAdsClient udostępnia domyślny konstruktor tworzący obiekt użytkownika zgodnie z ustawieniami określonymi 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 wyliczenia jako argument podczas tworzenia usługi. Aby np. utworzyć instancję interfejsu CampaignServiceClient w wersji V18 interfejsu Google Ads API, musisz wywołać metodę GoogleAdsClient.GetService, podając jako argument wartość Services.V18.CampaignService, jak pokazano w poprzednim przykładzie.

Bezpieczeństwo wątków

Nie należy udostępniać instancji GoogleAdsClient w kilku wątkach, ponieważ zmiany konfiguracji wprowadzone 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 i równoległe wywoływanie wielu usług są bezpieczne w przypadku wątków.

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 jest wywoływanie interfejsu API z metody obsługi zdarzenia w aplikacji WinForm.

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

    Więcej informacji o różnicach między starą biblioteką Grpc.Core a domyślną biblioteką Grpc.Net.Client znajdziesz na stronie pomocy gRPC.

  2. Używaj metod asynchronicznych.

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

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

    Tworzony jest wywołanie 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.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. Jeśli wywołania interfejsu API nie powiedzie się z jakiegoś powodu, serwer może zwrócić błędy. Ważne jest rejestrowanie błędów interfejsu API i odpowiednie reagowanie na nie.

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