หน้านี้ได้รับการแปลโดย Cloud Translation API

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

คู่มือนี้จะให้ภาพรวมคร่าวๆ เกี่ยวกับวิธีเริ่มต้นใช้งาน 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.V18.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.V18.CampaignService);
// Now make calls to CampaignService.

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

ปัญหานี้มี 2 วิธีดังนี้

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

คุณตั้งค่าพร็อพเพอร์ตี้ 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

ใช้เมธอดแบบไม่พร้อมกัน

คุณสามารถใช้เมธอดแบบไม่พร้อมกันเพื่อหลีกเลี่ยงการหยุดทำงาน ตัวอย่างเช่น

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 และจัดการอย่างเหมาะสม

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

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