دليل البدء

يقدّم هذا الدليل نظرة عامّة مختصرة حول كيفية بدء استخدام مكتبة Google Ads API .NET.

تثبيت

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

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

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

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

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

إذا أردت إنشاء بيانات اعتماد...

• اتّبِع دليل الرمز المميّز للمطوِّر للحصول على الرمز المميّز للمطوِّر، إذا لم يكن لديك رمز مميز.
• اتّبِع دليل تدفق تطبيق 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.V16.CampaignService);

// Make more calls to service class.

إنشاء مثيل GoogleAdsClient

أهم الفئات في مكتبة Google Ads API .NET هي فئة 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.V16.CampaignService);
// Now make calls to CampaignService.

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

يمكن أن تتسبب الطرق المتزامنة في تجميد بعض تطبيقات .NET Level. ومن الأمثلة الشائعة على ذلك إجراء استدعاءات واجهة برمجة التطبيقات من طريقة معالج الأحداث في تطبيق WinForm.

هناك طريقتان لمعالجة هذه المشكلة:

1. استخدام مكتبة GRpc القديمة

   يمكنك ضبط السمة UseGrpcCore في GoogleAdsConfig لاستخدام مكتبة Grpc.Core القديمة بدلاً من مكتبة Grpc.Net.Client التلقائية. لم يتم اختبار هذه الطريقة بشكل مكثف على تطبيقات .NET Builder ، لذا قد لا تحل المشكلة. في ما يلي مقتطف نموذجي:

   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.V16.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());
   }
   

   ميزانية الحملة

   يتم إنشاء طلب ميزانية الحملة، ويتم عرض اسم المورد للميزانية الجديدة باستخدام تنبيه MessageBox.

   private async void button2_Click(object sender, EventArgs e)
   {
   // Get the BudgetService.
   CampaignBudgetServiceClient budgetService = client.GetService(
       Services.V16.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);
   }
   

إلغاء الطرق غير المتزامنة

بالنسبة إلى البرمجة غير المتزامنة، يمكنك استخدام المَعلمة callSettings لتمرير CancellationToken:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

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

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

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

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