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

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

การติดตั้ง

ระบบจะกระจายไบนารีไลบรารีของไคลเอ็นต์โดยใช้ 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.V17.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.V17.CampaignService);
// Now make calls to CampaignService.

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

   คุณตั้งค่าพร็อพเพอร์ตี้ UseGrpcCore ของ GoogleAdsConfig เพื่อใช้พร็อพเพอร์ตี้ได้ ไลบรารี 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.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());
   }
   

   งบประมาณแคมเปญ

   มีการสร้างการเรียกใช้ CampaignBudget และชื่อทรัพยากรของงบประมาณใหม่คือ แสดงโดยใช้การแจ้งเตือน 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);
   }
   

การจัดการข้อผิดพลาด

การเรียก API บางรายการอาจไม่ประสบความสำเร็จ เซิร์ฟเวอร์อาจแสดงข้อผิดพลาดหากการเรียก API ล้มเหลวเพราะเหตุผลบางอย่าง คุณต้องจับข้อผิดพลาด API และจัดการกับข้อผิดพลาดเหล่านั้น อย่างเหมาะสม

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

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