開始使用

本指南簡要說明如何開始使用 Google Ads API .NET 程式庫。

安裝

用戶端程式庫二進位檔會使用 NuGet 發行。將 NuGet 參照新增至專案中的 Google.Ads.GoogleAds 套件，即可使用用戶端程式庫。

設定授權

如要授權 API 呼叫，您必須向程式庫指定用戶端 ID、用戶端密碼、更新憑證和開發人員憑證。

如需產生憑證

• 如果您還沒有開發人員權杖，請按照開發人員權杖指南取得。
• 請按照 OAuth 電腦版應用程式流程指南產生用戶端 ID、用戶端密鑰和更新權杖。

如果您已擁有憑證

• 從 GitHub 的 App.config 檔案複製 GoogleAdsApi 節點和 configSections 節點下方的 GoogleAdsApi 部分，並貼到 App.config / Web.config 檔案中。如果您使用 NuGet 安裝套件，這些節點會自動插入 App.config / Web.config 檔案。
• 在應用程式的 App.config / Web.config 中加入開發人員權杖、用戶端 ID、用戶端密碼和更新權杖。

GitHub 中提供的 App.config 檔案有詳細說明，但您也可以參閱設定指南，進一步瞭解如何使用其他方式設定用戶端程式庫，例如使用環境變數。

發出 API 呼叫

用戶端程式庫的基本用法如下：

// 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.

建立 GoogleAdsClient 例項

Google Ads API .NET 程式庫中最重要的類別是 GoogleAdsClient 類別。可讓您建立可用於發出 API 呼叫的預先設定服務類別。GoogleAdsClient 提供預設的建構函式，可使用應用程式 App.config / Web.config 中指定的設定建立使用者物件。如要瞭解設定選項，請參閱設定指南。

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

建立服務

GoogleAdsClient 提供可用於建立廣告服務的 GetService 方法。

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

我們提供 Services 類別，列舉所有支援的 API 版本和服務。GetService 方法在建立服務時，會將這些列舉物件做為引數。舉例來說，如要為 Google Ads API 版本 V18 建立 CampaignServiceClient 的例項，您需要呼叫 GoogleAdsClient.GetService 方法，並將 Services.V18.CampaignService 做為引數，如前述範例所示。

執行緒安全

在多個執行緒之間共用 GoogleAdsClient 例項並不安全，因為您在一個執行緒中對例項所做的設定變更，可能會影響您在其他執行緒中建立的服務。從 GoogleAdsClient 執行個體取得新的服務執行個體，以及並行呼叫多個服務等作業，皆屬於執行緒安全的作業。

多執行緒應用程式如下所示：

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.
  ...
}

避免 .NET Framework 應用程式凍結

同步處理方法可能會導致部分 .NET Framework 應用程式凍結。常見的例子是從 WinForm 應用程式的事件處理常式方法發出 API 呼叫。

解決這個問題的方法有兩種：

1. 使用舊版 Grpc 程式庫。

   您可以設定 GoogleAdsConfig 的 UseGrpcCore 屬性，以便使用舊版 Grpc.Core 程式庫，而非預設的 Grpc.Net.Client 程式庫。這個方法尚未在 .NET Framework 應用程式上進行廣泛測試，因此可能無法解決問題。以下是程式碼片段範例：

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

2. 使用非同步方法。

   您可以使用非同步方法避免畫面凍結。以下舉幾個例子說明：

   SearchStream

   系統會呼叫 SearchStream()，並將結果填入清單檢視畫面。

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

   廣告活動預算

   系統會建立 CampaignBudget 呼叫，並使用 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);
   }
   

處理錯誤

並非所有 API 呼叫都會成功。如果您的 API 呼叫因某些原因失敗，伺服器就會擲回錯誤。請務必擷取 API 錯誤並妥善處理。

發生 API 錯誤時，系統會擲回 GoogleAdsException 例項。其中包含詳細資料，可協助您找出問題所在：

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