เริ่มต้นใช้งาน

คู่มือนี้จะให้ภาพรวมโดยย่อเกี่ยวกับวิธีเริ่มต้นใช้งานไลบรารี .NET ของ Google Ads API

การติดตั้ง

ไบนารีของไลบรารีของไคลเอ็นต์จะกระจายโดยใช้ NuGet เพิ่มการอ้างอิง NuGet ไปยังGoogle.Ads.GoogleAds แพ็กเกจในโปรเจ็กต์เพื่อใช้ ไลบรารีของไคลเอ็นต์

ตั้งค่าการให้สิทธิ์

หากต้องการให้สิทธิ์การเรียก API คุณต้องระบุรหัสไคลเอ็นต์ ข้อมูลลับของไคลเอ็นต์ โทเค็นการรีเฟรช และโทเค็นนักพัฒนาซอฟต์แวร์ให้กับไลบรารี

หากต้องการสร้างข้อมูลเข้าสู่ระบบ

• ทำตามคู่มือโทเค็นของนักพัฒนาแอปเพื่อรับโทเค็นของนักพัฒนาแอป หากยังไม่มี
• ทำตามคำแนะนำขั้นตอนของแอปเดสก์ท็อป OAuth เพื่อสร้างรหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ และโทเค็นการรีเฟรช

หากคุณมีข้อมูลเข้าสู่ระบบอยู่แล้ว

• คัดลอกโหนด GoogleAdsApi และส่วน GoogleAdsApi ภายใต้โหนด configSections จากไฟล์ App.config ใน GitHub ลงในไฟล์ App.config / Web.config หากคุณใช้ NuGet เพื่อติดตั้งแพ็กเกจ ระบบจะแทรกโหนดเหล่านี้ลงในไฟล์ App.config / Web.config โดยอัตโนมัติ
• ใส่โทเค็นนักพัฒนาแอป รหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ และโทเค็นการรีเฟรช ใน App.config / Web.config ของแอป

ไฟล์ App.config ที่รวมอยู่ใน GitHub มีเอกสารประกอบอย่างละเอียด แต่คุณยังดูข้อมูลเพิ่มเติมได้ในคู่มือการกำหนดค่า รวมถึงใช้วิธีอื่นในการกำหนดค่าไลบรารีของไคลเอ็นต์ เช่น ตัวแปรสภาพแวดล้อม

ทำการเรียก API

การใช้งานไลบรารีของไคลเอ็นต์ขั้นพื้นฐานมีดังนี้

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V20.CampaignService);

// Make more calls to service class.

สร้างอินสแตนซ์ GoogleAdsClient

คลาสที่สำคัญที่สุดในไลบรารี .NET ของ Google Ads API คือคลาส 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.V20.CampaignService);
// Now make calls to CampaignService.

เรามีคลาส Services ที่แจกแจงเวอร์ชัน API และบริการทั้งหมดที่รองรับ GetService เมธอดจะยอมรับออบเจ็กต์การแจงนับเหล่านี้เป็นอาร์กิวเมนต์ เมื่อสร้างบริการ เช่น หากต้องการสร้างอินสแตนซ์ของ CampaignServiceClient สำหรับ Google Ads API เวอร์ชัน V20 คุณต้องเรียกใช้เมธอด GoogleAdsClient.GetService โดยมี Services.V20.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 บางรายการหยุดทำงาน ตัวอย่างที่พบบ่อยคือการเรียก API จากเมธอดตัวแฮนเดิลเหตุการณ์ ของแอปพลิเคชัน WinForm

คุณแก้ไขปัญหานี้ได้ 2 วิธีดังนี้

1. ใช้ไลบรารี Grpc รุ่นเดิม

   คุณตั้งค่าพร็อพเพอร์ตี้ UseGrpcCore ของ GoogleAdsConfig เพื่อใช้ไลบรารี 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.V20.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.V20.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 และจัดการข้อผิดพลาดเหล่านั้น อย่างเหมาะสม

ระบบจะส่งGoogleAdsExceptionเมื่อเกิดข้อผิดพลาดของ API โดยมี รายละเอียดที่จะช่วยให้คุณทราบว่าเกิดข้อผิดพลาดใดขึ้น

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V20.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}");
}