الخطوات الأولى

يقدّم هذا الدليل نظرة عامة موجزة حول كيفية بدء استخدام مكتبة ‎.NET الخاصة بواجهة برمجة التطبيقات مع "إعلانات Google".

تثبيت

يتم توزيع ملفات المكتبة الثنائية للعميل باستخدام NuGet. أضِف مرجع NuGet إلى حزمة Google.Ads.GoogleAds في مشروعك لاستخدام مكتبة البرامج.

إعداد التفويض

لتفويض طلبات البيانات من واجهة برمجة التطبيقات، عليك تحديد معرّف العميل وسر العميل ورمز التحديث ورمز المطوّر في المكتبة.

إذا كنت بحاجة إلى إنشاء بيانات اعتماد

• اتّبِع دليل الرمز المميز للمطوِّر للحصول على الرمز المميز للمطوِّر إذا لم يكن لديك رمز.
• اتّبِع دليل مسار تطبيق OAuth على الكمبيوتر لإنشاء معرّف عميل وسر عميل ورمز مميّز لإعادة التحميل.

إذا كانت لديك بيانات اعتماد

• انسخ عقدة GoogleAdsApi وقسم GoogleAdsApi ضمن عقدة configSections من ملف App.config فيGitHub إلى ملف App.config / Web.config. إذا كنت قد استخدمت NuGet لتثبيت الحزمة، سيتم إدراج هذه العُقد تلقائيًا في ملف App.config / Web.config.
• أدرِج الرمز المميّز للمطوّر ومعرّف العميل وسر العميل ورمز التحديث في App.config / Web.config في تطبيقك.

إنّ ملف App.config المضمّن في GitHub موثّق بشكل جيد، ولكن يمكنك أيضًا الرجوع إلى دليل الإعداد للحصول على مزيد من المعلومات، بالإضافة إلى استخدام طرق بديلة لإعداد مكتبة البرامج، مثل متغيّرات البيئة.

تقديم طلب بيانات من واجهة برمجة التطبيقات

في ما يلي الاستخدام الأساسي لمكتبة البرامج:

// 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. تتيح لك إنشاء فئة خدمة تم ضبطها مسبقًا يمكن استخدامها لإجراء طلبات من واجهة برمجة التطبيقات. توفّر السمة GoogleAdsClient دالة إنشاء تلقائية تنشئ عنصر مستخدم باستخدام الإعدادات المحدّدة في App.config / Web.config في تطبيقك. راجِع دليل الإعداد للاطّلاع على خيارات الإعداد.

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

إنشاء خدمة

توفّر GoogleAdsClient طريقة GetService يمكن استخدامها لإنشاء خدمة "إعلانات Google".

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

نوفّر الفئة Services التي تسرد جميع إصدارات واجهة برمجة التطبيقات والخدمات المتوافقة. تقبل الطريقة GetService عناصر التعداد هذه كمعلَمة عند إنشاء الخدمة. على سبيل المثال، لإنشاء مثيل من CampaignServiceClient للإصدار V20 من Google Ads API، عليك استدعاء طريقة 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 عن العمل. ومن الأمثلة الشائعة على ذلك إجراء طلبات بيانات من واجهة برمجة التطبيقات من طريقة معالجة الأحداث لتطبيق WinForm.

هناك طريقتان لحلّ هذه المشكلة:

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

معالجة الأخطاء

لن تنجح جميع طلبات البيانات من واجهة برمجة التطبيقات. يمكن أن يعرض الخادم أخطاءً إذا تعذّرت معالجة طلبات البيانات من واجهة برمجة التطبيقات لسبب ما. من المهم تسجيل أخطاء واجهة برمجة التطبيقات والتعامل معها بشكل مناسب.

يتم عرض مثيل GoogleAdsException عند حدوث خطأ في واجهة برمجة التطبيقات. ويتضمّن تفاصيل لمساعدتك في معرفة المشكلة التي حدثت:

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