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

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

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

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

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

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

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

الفهرس

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

الجمهور

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

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

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

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

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

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

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

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

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

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

ولجعلها أكثر واقعية، توضح هذه الأمثلة كيفية التفاعل مع خدمة معينة: تقويم Google. سنوضح الأماكن التي يختلف فيها التقويم عن خدمات Google الأخرى، وذلك لمساعدتك على تهيئة هذه الأمثلة لاستخدامها مع الخدمات الأخرى. لمزيد من المعلومات حول التقويم، راجع وثائق واجهة برمجة التطبيقات لبيانات تقويم Google.

إنشاء العميل وتشغيله

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

using Google.GData.Client;

طلب خلاصة

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

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

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

يجب أيضًا تقديم المصادقة المناسبة. لاحظ أن نظام المصادقة الذي نستخدمه هنا (المعروف باسم "مصادقة 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" "للتقويم") واسم تطبيقك (بالشكل companyName-applicationName-versionID).
  4. اضبط بيانات الاعتماد المناسبة.
  5. اتصل بإحدى الطرق لإرسال الطلب وتلقي أي نتائج.

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

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

على غرار الطرق الأخرى للفئة Service، يعالج Query المصادقة وعمليات إعادة التوجيه عند الضرورة.

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

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

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 والبيانات الثنائية.

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

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

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

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

طلب إدخال محدد

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

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

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

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

بعد ذلك، ما عليك سوى استدعاء طريقة الخدمة 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 جديد للإدخال الجديد لهذا الإدخال. (لمزيد من المعلومات عن إصدارات الإدخالات، راجع قسم التزامن المتفائل من المستند المرجعي لبروتوكول v1.)

تعادل الرمز الوارد تقريبًا إرسال 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. تتم إضافة العناصر التالية:

طلب البحث للحدث
فئة فرعية من FeedQuery، تتيح لك ضبط معلّمتَين مخصّصتَين لخدمة "تقويم Google" (بدء-الحدّ الأدنى وبداية-الحدّ الأقصى).
خدمة التقويم
فئة فرعية من الخدمة يمكنها عرض خلاصة حدث.
خلاصة الحدث
فئة فرعية من AtomFeed، تعرض EventEntries.
الدخول إلى الفعالية
فئة فرعية من AtomEntry، والتي لديها خصائص إضافية مرتبطة ببيانات التقويم.

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

مَراجع

للحصول على معلومات مرجعية حول مكتبة عملاء C#، راجع الوثائق المرجعية.

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