البدء

يقدّم هذا الدليل نظرة عامة مختصرة حول كيفية بدء استخدام مكتبة 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.V14.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 يمكن استخدامها لإنشاء خدمة إعلانات.

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

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

   private async void button1_Click(object sender, EventArgs e)
   {
   // Get the GoogleAdsService.
   GoogleAdsServiceClient googleAdsService = client.GetService(
       Services.V14.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.V14.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.V14.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.V14.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}");
}