دليل البدء

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

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

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

تجنب تجميد البيانات في تطبيقات NETframe.

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

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

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

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

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