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ęźleconfigSections
z plikuApp.config
na GitHubie do plikuApp.config
/Web.config
. Jeśli do zainstalowania pakietu użyjesz NuGeta, te węzły zostaną automatycznie wstawione do plikuApp.config
/Web.config
. - Umieść token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania aplikacji w sekcji
App.config
/Web.config
. PlikApp.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ęźleconfigSections
z plikuApp.config
na GitHubie do plikuApp.config
/Web.config
. Jeśli do zainstalowania pakietu użyjesz NuGeta, te węzły zostaną automatycznie wstawione do plikuApp.config
/Web.config
. - Umieść token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania aplikacji w sekcji
App.config
/Web.config
. PlikApp.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:
Użyj starszej biblioteki Grpc.
Możesz skonfigurować właściwość
UseGrpcCore
elementuGoogleAdsConfig
w taki sposób, aby używała starszej bibliotekiGrpc.Core
zamiast domyślnej bibliotekiGrpc.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);
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}");
}