開始使用

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

安裝

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

設定授權

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

如果您需要產生憑證

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

如果您已擁有憑證

• 將 GoogleAdsApi 節點和 configSections 節點下方的 GoogleAdsApi 區段從 GitHub 中的 App.config 檔案複製到 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.

建立 Google AdsClient 執行個體

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

   gRPC 支援頁面進一步說明舊版 Grpc.Core 程式庫與預設 Grpc.Net.Client 程式庫的差異。

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