Hướng dẫn này cung cấp thông tin tổng quan ngắn gọn về cách bắt đầu sử dụng thư viện API .NET của Google Ads.
Cài đặt
Các tệp nhị phân của thư viện ứng dụng được phân phối bằng NuGet. Thêm một tệp tham chiếu Nuget vào gói Google.Ads.GoogleAds
trong dự án của bạn để sử dụng thư viện ứng dụng.
Thiết lập tính năng uỷ quyền
Để cho phép các lệnh gọi API, bạn cần chỉ định mã ứng dụng khách, mật khẩu ứng dụng khách, mã làm mới và mã của nhà phát triển vào thư viện.
Nếu bạn đã có thông tin đăng nhập...
- Sao chép nút
GoogleAdsApi
và phầnGoogleAdsApi
trong nútconfigSections
từ tệpApp.config
trong GitHub vào tệpApp.config
/Web.config
. Nếu bạn đã sử dụng NuGet để cài đặt gói này, thì các nút này sẽ tự động được chèn vào tệpApp.config
/Web.config
. - Đưa mã của nhà phát triển, mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới vào
App.config
/Web.config
của ứng dụng. TệpApp.config
có trong GitHub được ghi lại đầy đủ, nhưng bạn cũng có thể tham khảo Hướng dẫn về cấu hình để tìm hiểu thêm cũng như sử dụng các chế độ cài đặt cấu hình thay thế.
Nếu bạn cần tạo thông tin đăng nhập...
- Làm theo Hướng dẫn về mã thông báo của nhà phát triển để lấy mã của nhà phát triển nếu bạn chưa có.
- Làm theo hướng dẫn quy trình ứng dụng OAuth dành cho máy tính để tạo mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới.
- Sao chép nút
GoogleAdsApi
và phầnGoogleAdsApi
trong nútconfigSections
từ tệpApp.config
trong GitHub vào tệpApp.config
/Web.config
. Nếu bạn đã sử dụng NuGet để cài đặt gói này, thì các nút này sẽ tự động được chèn vào tệpApp.config
/Web.config
. - Đưa mã của nhà phát triển, mã ứng dụng khách, mật khẩu ứng dụng khách và mã làm mới vào
App.config
/Web.config
của ứng dụng. TệpApp.config
có trong GitHub được ghi lại đầy đủ, nhưng bạn cũng có thể tham khảo Hướng dẫn về cấu hình để tìm hiểu thêm cũng như sử dụng các chế độ cài đặt cấu hình thay thế.
Thực hiện lệnh gọi API
Dưới đây là cách sử dụng cơ bản của thư viện ứng dụng:
// 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.
Tạo một phiên bản GoogleAdsClient
Các lớp quan trọng nhất trong thư viện .NET của API Google Ads là
lớp GoogleAdsClient
. API này cho phép bạn tạo một lớp dịch vụ được định cấu hình sẵn có thể dùng để thực hiện lệnh gọi API. GoogleAdsClient
cung cấp một hàm khởi tạo mặc định để tạo đối tượng người dùng bằng cách sử dụng các chế độ cài đặt được chỉ định trong App.config
/ Web.config
của ứng dụng. Tham khảo Hướng dẫn cấu hình để biết nhiều lựa chọn cấu hình.
// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();
Tạo một dịch vụ
GoogleAdsClient
cung cấp phương thức GetService
có thể dùng để tạo dịch vụ Google Ads.
CampaignServiceClient campaignService = client.GetService(Services.V16.CampaignService);
// Now make calls to CampaignService.
Chúng tôi cung cấp một lớp Services
liệt kê tất cả phiên bản và dịch vụ API được hỗ trợ. Phương thức GetService
chấp nhận các đối tượng liệt kê này làm đối số khi tạo dịch vụ. Ví dụ: để tạo một bản sao của
CampaignServiceClient
cho phiên bản V16
của API Google Ads,
bạn cần gọi phương thức GoogleAdsClient.GetService
với đối số
Services.V16.CampaignService
như minh hoạ ở trên.
Độ an toàn cho chuỗi
Việc chia sẻ thực thể GoogleAdsClient
giữa nhiều luồng là không an toàn, vì thay đổi về cấu hình bạn thực hiện trên một thực thể trong một luồng có thể ảnh hưởng đến những dịch vụ bạn tạo trên các luồng khác. Các thao tác như lấy thực thể dịch vụ mới từ một thực thể GoogleAdsClient
, thực hiện lệnh gọi song song đến nhiều dịch vụ, v.v. đều an toàn cho luồng.
Ứng dụng đa luồng sẽ có dạng như sau:
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.
...
}
Tránh tình trạng treo trong các ứng dụng .NET Framework
Các phương thức đồng bộ có thể khiến một số ứng dụng .NET Framework của bạn bị treo. Một ví dụ phổ biến là thực hiện lệnh gọi API từ phương thức trình xử lý sự kiện của ứng dụng WinForm.
Có hai cách để giải quyết vấn đề này:
Sử dụng thư viện Grpc cũ.
Bạn có thể đặt thuộc tính
UseGrpcCore
làGoogleAdsConfig
để sử dụng thư việnGrpc.Core
cũ thay vì thư việnGrpc.Net.Client
mặc định. Phương thức này chưa được thử nghiệm rộng rãi trên các ứng dụng .NET Framework, vì vậy có thể không giải quyết được vấn đề. Dưới đây là đoạn mã mẫu:GoogleAdsConfig config = new GoogleAdsConfig(); config.UseGrpcCore = true; GoogleAdsClient client = new GoogleAdsClient(config);
Sử dụng các phương thức không đồng bộ.
Bạn có thể sử dụng các phương thức không đồng bộ để tránh bị treo. Sau đây là một số ví dụ:
SearchStream
Lệnh gọi đến
SearchStream()
được thực hiện và kết quả được điền vào chế độ xem danh sách.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()); } Ngân sách chiến dịch
Lệnh gọi CampaignBudget được tạo và tên tài nguyên của ngân sách mới sẽ hiển thị bằng cảnh báo
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); }
Huỷ các phương thức không đồng bộ
Đối với tính năng lập trình không đồng bộ, bạn có thể dùng tham số callSettings
để truyền một 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
);
Xử lý lỗi
Không phải lệnh gọi API nào cũng thành công. Máy chủ có thể báo lỗi nếu lệnh gọi API của bạn không thành công vì lý do nào đó. Điều quan trọng là bạn phải nắm bắt được các lỗi API và xử lý các lỗi đó một cách phù hợp.
Một thực thể GoogleAdsException
sẽ được gửi khi xảy ra lỗi API. Trợ lý có thông tin chi tiết để giúp bạn tìm ra lỗi:
// 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}");
}