البدء

يقدّم هذا الدليل نظرة عامة مختصرة حول كيفية تنفيذ الخطوات الأولى في مكتبة إعلانات Google 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.V13.CampaignService);

// Make more calls to service class.

إنشاء مثيل GoogleAdsClient

أهم الفئات في مكتبة إعلانات Google 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.V13.CampaignService);
// Now make calls to CampaignService.

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

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