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.
Konfigurowanie autoryzacji
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ęźleconfigSections
z plikuApp.config
w GitHubie do plikuApp.config
/Web.config
. Jeśli do zainstalowania pakietu użyjesz NuGet, 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 w
App.config
/Web.config
aplikacji. PlikApp.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ęźleconfigSections
z plikuApp.config
w GitHubie do plikuApp.config
/Web.config
. Jeśli do zainstalowania pakietu użyjesz NuGet, 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 w
App.config
/Web.config
aplikacji. PlikApp.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:
Użyj starszej biblioteki GRPC.
Możesz ustawić właściwość
UseGrpcCore
usługiGoogleAdsConfig
, aby używać 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ż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}");
}