Bắt đầu

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 .NET của API Google Ads.

Cài đặt

Tệp nhị phân thư viện ứng dụng được phân phối bằng NuGet. Thêm tệp tham chiếu NuGet vào gói Google.Ads.GoogleAds trong dự án để sử dụng thư viện ứng dụng.

Thiết lập quyền uỷ quyền

Để uỷ quyền cho các lệnh gọi API, bạn cần chỉ định mã ứng dụng, khoá ứng dụng, mã thông báo làm mới và mã thông báo nhà phát triển cho thư viện.

Nếu bạn cần tạo thông tin xác thực

• Làm theo Hướng dẫn về mã 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, mật khẩu ứng dụng và mã làm mới.

Nếu bạn đã có thông tin xác thực

• Sao chép nút GoogleAdsApi và phần GoogleAdsApi trong nút configSections từ tệp App.config trong GitHub vào tệp App.config / Web.config. Nếu bạn đã sử dụng NuGet để cài đặt gói, các nút này sẽ tự động được chèn vào tệp App.config / Web.config.
• Thêm mã thông báo dành cho nhà phát triển, mã ứng dụng khách, mật khẩu ứng dụng khách và mã thông báo làm mới vào App.config / Web.config của ứng dụng.

Tệp App.config trong GitHub được ghi nhận đầy đủ, nhưng bạn cũng có thể tham khảo Hướng dẫn cấu hình để tìm hiểu thêm cũng như sử dụng các cách khác để định cấu hình thư viện ứng dụng, chẳng hạn như biến môi trường.

Thực hiện lệnh gọi API

Sau đâ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.V18.CampaignService);

// Make more calls to service class.

Tạo một thực thể GoogleAdsClient

Lớp quan trọng nhất trong thư viện Google Ads API .NET là lớp GoogleAdsClient. Thư viện này cho phép bạn tạo một lớp dịch vụ được định cấu hình trước 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. Hãy tham khảo Hướng dẫn cấu hình để biết các tuỳ chọn cấu hình.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Tạo dịch vụ

GoogleAdsClient cung cấp một phương thức GetService có thể dùng để tạo dịch vụ Google Ads.

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

Chúng tôi cung cấp một lớp Services liệt kê tất cả cá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 thực thể của CampaignServiceClient cho phiên bản V18 của API Google Ads, bạn cần gọi phương thức GoogleAdsClient.GetService với đối số là Services.V18.CampaignService, như trong ví dụ trước.

Độ an toàn cho chuỗi

Bạn không nên chia sẻ một thực thể GoogleAdsClient giữa nhiều luồng, vì các thay đổi về cấu hình mà bạn thực hiện trên một thực thể trong một luồng có thể ảnh hưởng đến các dịch vụ mà bạn tạo trên các luồng khác. Các thao tác như lấy bản sao dịch vụ mới từ bản sao GoogleAdsClient và thực hiện các lệnh gọi đến nhiều dịch vụ song song đều an toàn với 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 ứng dụng .NET Framework bị treo

Các phương thức đồng bộ có thể khiến một số ứng dụng Khung .NET 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:

1. Sử dụng thư viện Grpc cũ.

   Bạn có thể đặt thuộc tính UseGrpcCore của GoogleAdsConfig để sử dụng thư viện Grpc.Core cũ thay vì thư viện Grpc.Net.Client mặc định. Phương thức này chưa được kiểm thử rộng rãi trên các ứng dụng Khung .NET, vì vậy, phương thức này có thể không giải quyết được vấn đề. Dưới đây là một đoạn mã mẫu:

   GoogleAdsConfig config = new GoogleAdsConfig();
   config.UseGrpcCore = true;
   GoogleAdsClient client = new GoogleAdsClient(config);
   

2. 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. Dưới đây là một số ví dụ:

   SearchStream

   Hệ thống sẽ thực hiện lệnh gọi đến SearchStream() và điền kết quả vào chế độ xem danh sách.

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

   Ngân Sách Chiến dịch

   Hệ thống sẽ tạo một lệnh gọi CampaignBudget và tên tài nguyên của ngân sách mới sẽ được 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.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);
   }

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ể gửi 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 ghi lại lỗi API và xử lý các lỗi đó một cách thích hợp.

Một thực thể GoogleAdsException sẽ được gửi khi xảy ra lỗi API. Thông báo này có thông tin chi tiết để giúp bạn tìm hiểu xem đã xảy ra sự cố gì:

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