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 API Google Ads Thư viện .NET.

Cài đặt

Các tệp nhị phân của thư viện ứng dụng được phân phối qua NuGet. Thêm tài liệu tham khảo NuGet vào Google.Ads.GoogleAds gói trong dự án của bạn để sử dụng thư viện ứng dụng.

Thiết lập yêu cầu uỷ quyền

Để cho phép 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ần tạo thông tin đăng nhập

Nếu bạn đã có thông tin đăng nhập

  • 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 các nút này sẽ được tự động chèn vào App.config / Web.config tệp.
  • Bao gồm 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 trong App.config / Web.config của ứng dụng.

App.config tệp có trong GitHub đều được ghi nhận đầ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 cách thay thế để định cấu hình thư viện ứng dụng, chẳng hạn như các biến môi trường.

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.V17.CampaignService);

// Make more calls to service class.

Tạo một bản sao GoogleAdsClient

Các lớp quan trọng nhất trong thư viện .NET của API Google Ads là Lớp GoogleAdsClient. Lớp 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 giá trị mặc định hàm khởi tạo sẽ tạo đối tượng người dùng bằng các chế độ cài đặt được chỉ định trong App.config / Web.config của ứng dụng. Tham khảo Cấu hình hướng dẫn về 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 phương thức GetService có thể dùng để tạo một Dịch vụ quảng cáo.

CampaignServiceClient campaignService = client.GetService(Services.V17.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 API được hỗ trợ và luôn miễn phí. 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 phiên bản của CampaignServiceClient cho phiên bản V17 của API Google Ads, bạn cần gọi phương thức GoogleAdsClient.GetService bằng Services.V17.CampaignService làm đối số, như minh hoạ trong ví dụ trước.

Độ an toàn cho chuỗi

Việc chia sẻ một thực thể GoogleAdsClient giữa nhiều luồng là không an toàn, vì việc thay đổi cấu hình mà bạn thực hiện trên một thực thể trong một chuỗi có thể ảnh hưởng đến các dịch vụ bạn tạo trên các luồng khác. Các thao tác như lấy dữ liệu các bản sao dịch vụ mới từ bản sao GoogleAdsClient và thực hiện lệnh gọi đến nhiều dịch vụ song song sẽ an toàn cho luồng.

Một ứ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 bị treo trong .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:

  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 pháp này chưa được thử nghiệm rộng rãi trên các ứng dụng .NET Framework, nên 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);

    Trang hỗ trợ gRPC đã cung cấp thêm thông tin chi tiết về sự khác biệt giữa thư viện Grpc.Core cũ và thư viện Grpc.Net.Client mặc định.

  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

    Lệnh gọi đến SearchStream() được thực hiện và kết quả được được điền sẵ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.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());
}

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

    Lệnh gọi Ngân sách chiến dịch sẽ được tạo và tên tài nguyên của ngân sách mới là được hiển thị bằng thông báo 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);
}

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 đó. Bạn cần phải ghi lại và xử lý các lỗi API một cách phù hợp.

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

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