دليل المطوّر لمكتبة برامج .NET

يوضّح هذا المستند كيفية استخدام مكتبة برامج العميل ‎ .NET لإرسال طلبات بحث إلى Google Data API‏ ("GData") وتفسير الردود التي يتم تلقّيها.

توفّر Google مجموعة من مكتبات البرامج للتفاعل مع الخدمات المتوافقة مع GData، وذلك بلغات برمجة مختلفة. باستخدام هذه المكتبات، يمكنك إنشاء طلبات GData وإرسالها إلى إحدى الخدمات وتلقّي الردود.

يقدّم هذا المستند مجموعة من الأمثلة على الاستخدامات الشائعة لإصدار C# من مكتبة البرامج، يليها معلومات أخرى حول كتابة برامج GData. في نهاية هذا المستند، ستجد رابطًا يؤدي إلى المستندات المرجعية لمكتبة برامج C#، بتنسيق NDoc.

لاستخدام مكتبة البرامج هذه، يجب أن يتوفّر لديك وقت تشغيل .NET 1.1، ويجب أيضًا أن تكون على علم بجميع التصحيحات.

نزِّل مكتبة برامج ‎ .NET.

تشير الأمثلة الواردة في هذا الدليل إلى Google Calendar API، ولكن هذا الدليل ليس دقيقًا أو محدّثًا لاستخدام Calendar API. للحصول على معلومات حول استخدام مكتبة برامج ‎ .NET مع Data API لخدمة معيّنة، يُرجى الاطّلاع على المستندات الخاصة بالخدمة. على سبيل المثال، إذا كنت تعمل مع "تقويم Google"، اطّلِع على دليل مطوّري برامج واجهة برمجة التطبيقات لبيانات "تقويم Google".

المحتويات

  1. الجمهور
  2. نظرة عامة على نموذج البيانات
  3. برنامج تعليمي وأمثلة
  4. Reference

الجمهور

هذا المستند مخصّص لمبرمجي C# الذين يريدون كتابة تطبيقات عملاء يمكنها التفاعل مع خدمات GData.

يفترض هذا المستند أنّك على دراية بالأفكار العامة التي يستند إليها بروتوكول Google Data APIs. ويفترض أيضًا أنّك تعرف كيفية البرمجة بلغة C#.

نظرة عامة على نموذج البيانات

توفّر مكتبة برامج C# للعميل مجموعة من الفئات التي تتوافق مع العناصر وأنواع البيانات التي تستخدمها Google Data APIs. على سبيل المثال، هناك فئة Feed تتوافق مع العنصر <atom:feed>، وتتضمّن طرقًا لإنشاء إدخال والحصول على قيم العناصر الفرعية المختلفة وتحديدها وما إلى ذلك. هناك أيضًا فئة Entry تتوافق مع العنصر <atom:entry>. لا يحتوي كل عنصر محدّد في Google Data APIs على فئته الخاصة. للحصول على التفاصيل، يُرجى الاطّلاع على المستندات المرجعية.

يمكن للمكتبة تحليل محتوى Atom تلقائيًا ووضع قيم عناصر Atom في الكائنات المناسبة. على سبيل المثال، يحصل الإجراء getFeed على خلاصة ويحلّلها ويعرض كائن خلاصة يتضمّن القيم الناتجة.

لإرسال خلاصة أو إدخال إلى خدمة، عليك إنشاء عنصر "خلاصة" أو "إدخال"، ثم استدعاء طريقة مكتبة (مثل الطريقة insert) لترجمة العنصر تلقائيًا إلى XML وإرساله.

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

وكما أنّ بنية XML في Google Data API قابلة للتوسيع، فإنّ نموذج العناصر المقابل قابل للتوسيع أيضًا. على سبيل المثال، توفّر مكتبة البرامج المساعدة فئات تتوافق مع العناصر المحدّدة في مساحة اسم Google Data.

البرنامج التعليمي والأمثلة

توضّح الأمثلة التالية كيفية إرسال طلبات GData مختلفة باستخدام مكتبة برامج C# للعملاء.

لجعلها أكثر واقعية، توضّح هذه الأمثلة كيفية التفاعل مع خدمة معيّنة، وهي "تقويم Google". سنشير إلى المواضع التي يختلف فيها "تقويم Google" عن خدمات Google الأخرى لمساعدتك في تكييف هذه الأمثلة لاستخدامها مع خدمات أخرى. لمزيد من المعلومات عن "تقويم Google"، يُرجى الاطّلاع على مستندات Google Calendar Data API.

إنشاء البرنامج وتشغيله

لتجميع الأمثلة في هذا المستند، عليك استخدام عبارة using التالية:

using Google.GData.Client;

طلب خلاصة

كما هو موضّح في مستندات Google Calendar Data API، يمكنك طلب خلاصة "تقويم" من خلال إرسال طلب HTTP التالي إلى "تقويم Google":

GET http://www.google.com/calendar/feeds/userID/private/full

بالطبع، عليك استبدال userID بعنوان البريد الإلكتروني للمستخدم. راجِع مستند "تقويم Google" للحصول على التفاصيل. يمكنك بدلاً من ذلك استخدام عنوان URL التلقائي الخاص للتفاعل مع "تقويم Google" (كما هو موضّح في مستند "تقويم Google")، ولكن في هذا المستند سنستخدم عنوان URL الخاص بالخلاصة الكاملة الذي يحتوي على رقم تعريف المستخدم.

عليك أيضًا تقديم مستندات المصادقة المناسبة. يُرجى العِلم أنّ نظام المصادقة الذي نستخدمه هنا (المعروف باسم "مصادقة Google للتطبيقات المثبَّتة") مناسب فقط للاستخدام في تطبيقات العميل المثبَّتة، مثل برامج العميل على الكمبيوتر المكتبي، وليس للاستخدام في تطبيقات الويب. لمزيد من المعلومات عن المصادقة، يُرجى الاطّلاع على مستندات مصادقة حساب Google.

لطلب خلاصة "تقويم Google" باستخدام مكتبة برامج C#، لمستخدم عنوان بريده الإلكتروني هو "jo@gmail.com" وكلمة المرور هي "mypassword"، استخدِم الرمز التالي:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

يمثّل الفئة Service اتصال عميل (مع المصادقة) بخدمة GData. يتضمّن الإجراء العام لإرسال طلب بحث إلى إحدى الخدمات باستخدام مكتبة برامج العميل الخطوات التالية:

  1. الحصول على عنوان URL المناسب أو إنشاؤه
  2. إذا كنت سترسل بيانات إلى إحدى الخدمات (على سبيل المثال، إذا كنت ستُدرج إدخالاً جديدًا)، عليك تحويل البيانات الأولية إلى عناصر باستخدام فئات مكتبة البرامج. (لا تنطبق هذه الخطوة إذا كنت تطلب خلاصة فقط، كما نفعل في هذا المثال).
  3. أنشئ مثيلاً جديدًا من Service، مع ضبط اسم الخدمة (مثل "cl" لتقويم Google) واسم تطبيقك (بالتنسيق companyName-applicationName-versionID).
  4. اضبط بيانات الاعتماد المناسبة.
  5. استدعِ إحدى الطرق لإرسال الطلب وتلقّي أي نتائج.

تضبط الطريقة service.setUserCredentials السمة service.Credentials باستخدام عنصر بيانات اعتماد شبكة .NET العادي. يتم ضبط بيانات الاعتماد على رقم التعريف وكلمة المرور للمستخدم الذي يرسل البرنامج طلب البحث نيابةً عنه. تستخدِم الأمثلة الواردة في هذا المستند نظام المصادقة "المصادقة للتطبيقات المثبَّتة". لمزيد من المعلومات عن أنظمة المصادقة الأخرى، يُرجى الاطّلاع على مستند مصادقة حساب Google.

لطلب خلاصة كاملة، عليك استدعاء الطريقة service.Query التي تأخذ الكائن FeedQuery وتعرض الخلاصة الكاملة المتوفّرة في عنوان URL هذا. سنوضّح كيفية إرسال طلبات بحث أكثر تحديدًا في وقت لاحق من هذا المستند.

مثل الطرق الأخرى في الفئة Service، تعالج الدالة Query عمليات المصادقة وعمليات إعادة التوجيه حسب الحاجة.

إدراج عنصر جديد

لإدراج عنصر في خلاصة "تقويم Google"، يمكنك استخدام الرمز التالي:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

بعد ضبط عنوان URL، ننشئ عنصر AtomEntry.

عنوان الإدخال هو AtomTextConstruct، وهو فئة تحتوي على نص بأشكال مختلفة (نص عادي أو HTML أو XHTML). يتم تمثيل محتوى الإدخال بواسطة كائن AtomContent، وهو فئة يمكنها الاحتفاظ بنص عادي أو أشكال أخرى من المحتوى، بما في ذلك XML والبيانات الثنائية.

يتم تمثيل كل مؤلف باسم ومعرّف موارد منتظم (URI) وعنوان بريد إلكتروني. (في هذا المثال، لن ندرج عنوان URI). يمكنك إضافة مؤلف إلى إدخال من خلال إضافة عنصر AtomAuthor إلى مجموعة Authors الخاصة بالإدخال.

نحن نستخدم كائن Service نفسه الذي أنشأناه في المثال السابق. في هذه الحالة، تكون الطريقة المطلوب استدعاؤها هي Insert، والتي ترسل عنصرًا إلى عنوان URL المحدّد للإدراج.

تعرض الخدمة الإدخال الذي تم إنشاؤه حديثًا، والذي قد يحتوي على عناصر إضافية من إنشاء الخادم، مثل عنوان URL لتعديل الإدخال.

الرمز أعلاه يعادل إرسال POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (مع المصادقة المناسبة) وتقديم إدخال.

طلب إدخال معيّن

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

في سياق هذه السلسلة من الأمثلة، ليس من الضروري استرداد هذا الإدخال، لأنّ "تقويم Google" سبق أن عرض الإدخال الذي تم إدراجه، ولكن يمكن تطبيق الأسلوب نفسه كلما عرفت عنوان URL الخاص بإدخال معيّن.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

يحتوي الإدخال المُدرَج على السمة SelfUri التي تعرض العنصر AtomUri الذي يمكن استخدامه لإنشاء عنصر URI جديد باستخدام الطريقة ToString().

بعد ذلك، ما علينا سوى استدعاء طريقة Query الخاصة بالخدمة للحصول على كائن AtomFeed جديد، مع إدخال واحد فقط في مجموعة الإدخالات.

الرمز أعلاه يعادل إرسال GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID إلى "تقويم Google" مع المصادقة المناسبة.

البحث عن إدخال

لاسترداد أول نتيجة مطابقة في بحث بنص كامل، استخدِم الرمز التالي:

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

يبدأ هذا المثال بإنشاء عنصر FeedQuery يتألف في الغالب من عنوان URL بالإضافة إلى مَعلمات طلب البحث المرتبطة به. تحتوي كل مَعلمة من مَعلمات طلب البحث القياسية في GData على سمة.

بعد إنشاء FeedQuery، نمرّره إلى طريقة Query في الخدمة، والتي تعرض خلاصة تحتوي على نتائج طلب البحث. يمكنك بدلاً من ذلك إنشاء عنوان URL بنفسك (عن طريق إلحاق مَعلمات طلب البحث بعنوان URL الخاص بالخلاصة) ثم استدعاء الطريقة Query، ولكن الطريقة FeedQuery توفّر طبقة تجريد مفيدة حتى لا تضطر إلى إنشاء عنوان URL بنفسك.

تعرض مجموعة Entries للخلاصة قائمة بالإدخالات في الخلاصة، بينما تعرض Entries.Count عدد الإدخالات في الخلاصة.

في هذه الحالة، إذا عرض الاستعلام أي نتائج، سنعيّن النتيجة الأولى المطابقة لكائن AtomEntry. بعد ذلك، نستخدم السمة Title للفئة AtomEntry من أجل استرداد عنوان الإدخال.

الرمز أعلاه مكافئ لإرسال GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis إلى "تقويم Google".

الاستعلام حسب الفئة

ملاحظة: لا يربط "تقويم Google" التصنيفات بالأحداث، لذا لا يعمل هذا المثال مع "تقويم Google".

لاسترداد خلاصة تتضمّن جميع الإدخالات التي تتطابق مع البحث السابق عن النص الكامل والتي تنتمي إلى فئة معيّنة أو تحمل تصنيفًا معيّنًا، استخدِم الرمز التالي:

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

تمثّل الفئة AtomCategory بالطبع فئة سيتم استخدامها في فلتر الفئات. يمكن أن يحتوي الصف QueryCategory على فئات متعددة، ولكن في هذه الحالة، سننشئ فلترًا بفئة واحدة فقط.

بعد ذلك، نضيف عامل التصفية هذا إلى طلب البحث الحالي الذي لا يزال يحتوي على سلسلة طلب البحث بالنص الكامل من المثال السابق.

نستخدم مرة أخرى الطريقة Query لإرسال طلب البحث إلى الخدمة.

إذا كان "تقويم Google" يسمح بالبحث عن فئة، سيكون الرمز أعلاه مكافئًا لإرسال GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis إلى "تقويم Google".

تعديل عنصر

لتعديل عنصر حالي، استخدِم الرمز التالي. في المثال التالي، سنغيّر عنوان الإدخال الذي تم استرجاعه سابقًا من النص القديم ("لعب التنس مع بيث") إلى "اجتماع مهم".

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

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

تعرض الخدمة الإدخال المعدَّل، بما في ذلك عنوان URL جديد للإصدار الجديد من هذا الإدخال. (لمزيد من المعلومات عن إصدارات الإدخالات، يُرجى الاطّلاع على قسم التزامن المتفائل في المستند المرجعي لبروتوكول الإصدار 1).

إنّ الرمز أعلاه يعادل تقريبًا إرسال PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID إلى الخدمة، بالإضافة إلى الإدخال الجديد (بتنسيق Atom) لاستبدال الإدخال الأصلي.

حذف عنصر

لحذف عنصر حالي، استخدِم الرمز التالي:

updateEntry.Delete();

عنوان URL الذي سيتم استخدامه للحذف هو نفسه عنوان URL للتعديل، لذا فإنّ هذا المثال يشبه المثال السابق إلى حد كبير، باستثناء أنّنا نستدعي الطريقة Delete بدلاً من Update.

الرمز أعلاه يعادل تقريبًا إرسال DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID إلى الخدمة.

العمل باستخدام خلاصات "تقويم Google"

توضّح الأمثلة أعلاه كيفية استخدام واجهة برمجة تطبيقات Google Data C# للتعامل مع خلاصات GData العامة. عند العمل مع خلاصة "تقويم Google" على وجه الخصوص، تحتوي الخلاصة على الكثير من البيانات الخاصة بالتقويم والتي لا يمكن الوصول إليها بسهولة باستخدام العناصر العادية المستندة إلى Atom في مكتبة واجهة برمجة التطبيقات الأساسية. لمساعدتك في التفاعل مع هذه الخلاصات، نقدّم لك الإضافات التالية:

using Google.GData.Extensions;
using Google.GData.Calendar;

يتعامل مساحة الاسم "الإضافات" مع الإضافات بشكل عام، بينما تتيح لك مساحة الاسم "التقويم" الوصول إلى خدمة تقويم مخصّصة وعنصر خلاصة وعنصر طلب بحث. يمكنك العثور على مثال أكثر تفصيلاً حول كيفية استخدام هذه الإضافات في الدليل الفرعي /Samples ضمن عملية تثبيت C# API. تتم إضافة العناصر التالية:

EventQuery
فئة فرعية من FeedQuery، تتيح لك ضبط مَعلمتَين مخصّصتَين لخدمة "تقويم Google" (start-min وstart-max).
CalendarService
فئة فرعية من الخدمة، يمكنها عرض خلاصة أحداث.
EventFeed
فئة فرعية من AtomFeed، تعرض EventEntries.
EventEntry
فئة فرعية من AtomEntry، تحتوي على سمات إضافية ذات صلة ببيانات التقويم.

لمزيد من التفاصيل حول هذه الفئات الخاصة، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات وبرنامج العيّنات.

مراجع

للحصول على معلومات مرجعية حول مكتبة برامج C#، يُرجى الاطّلاع على المستندات المرجعية.

الرجوع إلى الأعلى