راهنمای توسعه دهنده کتابخانه مشتری دات نت

این سند نحوه استفاده از کتابخانه سرویس گیرنده دات نت برای ارسال پرس و جوهای Google Data API ("GData") و تفسیر پاسخ های برگشتی را توضیح می دهد.

Google مجموعه‌ای از کتابخانه‌های سرویس گیرنده را برای تعامل با سرویس‌های دارای قابلیت GData در انواع زبان‌های برنامه‌نویسی ارائه می‌کند. با استفاده از این کتابخانه ها، می توانید درخواست های GData را بسازید، آنها را به یک سرویس ارسال کنید و پاسخ ها را دریافت کنید.

این سند مجموعه‌ای از نمونه‌هایی از استفاده‌های متداول از نسخه سی شارپ کتابخانه سرویس گیرنده و به دنبال آن اطلاعات دیگری درباره نوشتن کلاینت‌های GData را ارائه می‌کند. در انتهای این سند پیوندی به مستندات مرجع برای کتابخانه مشتری C#، در قالب NDoc وجود دارد.

برای استفاده از این کتابخانه سرویس گیرنده، به زمان اجرا .NET 1.1 نیاز دارید و همچنین باید در تمام وصله ها فعال باشید.

کتابخانه مشتری دات نت را دانلود کنید.

مثال‌های این راهنما به Google Calendar API اشاره دارد، اما این راهنما راهنمای دقیق یا به‌روزی برای استفاده از Calendar API نیست. برای اطلاعات در مورد استفاده از کتابخانه سرویس گیرنده دات نت با Data API یک سرویس خاص، به مستندات خاص سرویس مراجعه کنید. برای مثال، اگر با Calendar کار می‌کنید، راهنمای برنامه‌نویس Calendar Data API را بخوانید.

فهرست

  1. حضار
  2. نمای کلی مدل داده
  3. آموزش و مثال
  4. ارجاع

حضار

این سند برای برنامه نویسان C# در نظر گرفته شده است که می خواهند برنامه های مشتری بنویسند که می توانند با سرویس های GData تعامل داشته باشند.

این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs را درک می‌کنید. همچنین فرض می‌کند که می‌دانید چگونه در سی شارپ برنامه‌نویسی کنید.

نمای کلی مدل داده

کتابخانه مشتری C# مجموعه ای از کلاس ها را ارائه می دهد که با عناصر و انواع داده های مورد استفاده توسط Google Data API مطابقت دارد. به عنوان مثال، یک کلاس Feed وجود دارد که با عنصر <atom:feed> مطابقت دارد. دارای روش هایی برای ایجاد ورودی، دریافت و تنظیم مقادیر عناصر فرعی مختلف و غیره است. همچنین یک کلاس Entry وجود دارد که با عنصر <atom:entry> مطابقت دارد. هر عنصری که در Google Data API تعریف شده است کلاس خاص خود را ندارد. برای جزئیات، به مستندات مرجع مراجعه کنید.

کتابخانه می تواند به طور خودکار محتوای Atom را تجزیه کند و مقادیر عناصر Atom را در اشیاء مناسب قرار دهد. به عنوان مثال، متد getFeed یک فید دریافت می کند، آن را تجزیه می کند و یک شی Feed را با مقادیر حاصل برمی گرداند.

برای ارسال یک فید یا ورودی به یک سرویس، یک شیء Feed یا Entry ایجاد می‌کنید، سپس یک متد کتابخانه‌ای (مانند روش insert ) را فراخوانی می‌کنید تا به طور خودکار آن شی را به XML ترجمه کرده و ارسال کنید.

در صورت تمایل می توانید خودتان XML را تجزیه و/یا تولید کنید. ساده ترین راه برای انجام این کار با یک کتابخانه شخص ثالث مناسب است.

همانطور که سینتکس XML Google Data API قابل توسعه است، مدل شیء مربوطه نیز قابل توسعه است. به عنوان مثال، کتابخانه سرویس گیرنده کلاس‌های مربوط به عناصر تعریف‌شده در فضای نام Google Data را ارائه می‌کند.

آموزش و مثال

مثال‌های زیر نحوه ارسال درخواست‌های مختلف GData را با استفاده از کتابخانه مشتری C# نشان می‌دهند.

برای ملموس‌تر کردن آنها، این مثال‌ها نحوه تعامل با یک سرویس خاص را نشان می‌دهند: Google Calendar. ما به مکان‌هایی اشاره می‌کنیم که تقویم با سایر سرویس‌های Google متفاوت است تا به شما در تطبیق این نمونه‌ها برای استفاده با سرویس‌های دیگر کمک کنیم. برای اطلاعات بیشتر درباره تقویم، به مستندات API داده تقویم Google مراجعه کنید.

ساخت و اجرای مشتری شما

برای جمع‌آوری مثال‌های موجود در این سند، باید از دستور استفاده زیر استفاده کنید:

using Google.GData.Client;

درخواست فید

همانطور که در مستندات Google Calendar Data API توضیح داده شده است، می توانید با ارسال درخواست HTTP زیر به Calendar، فید Calendar را درخواست کنید:

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

البته باید userID با آدرس ایمیل کاربر جایگزین کنید. برای جزئیات به سند تقویم مراجعه کنید. در عوض، می‌توانید از نشانی اینترنتی پیش‌فرض ویژه برای تعامل با تقویم (همانطور که در سند تقویم توضیح داده شده است) استفاده کنید، اما در این سند از URL فید کامل خصوصی که حاوی شناسه کاربر است استفاده می‌کنیم.

همچنین باید احراز هویت مناسب را ارائه دهید. توجه داشته باشید که سیستم احراز هویتی که ما در اینجا استفاده می‌کنیم (معروف به «تأیید هویت Google برای برنامه‌های نصب‌شده») فقط برای استفاده در برنامه‌های کلاینت نصب‌شده مانند کلاینت‌های دسکتاپ مناسب است، نه برای استفاده در برنامه‌های وب. برای اطلاعات بیشتر در مورد احراز هویت، به مستندات تأیید اعتبار حساب Google مراجعه کنید.

برای درخواست فید Calendar با استفاده از کتابخانه مشتری 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" برای Calendar) و نام برنامه خود را (به شکل companyName - applicationName - versionID ) تنظیم کنید.
  4. اعتبار مناسب را تنظیم کنید.
  5. برای ارسال درخواست و دریافت هر گونه نتیجه با روشی تماس بگیرید.

متد service.setUserCredentials ویژگی service.Credentials را با یک شی استاندارد .NET Network credentials تنظیم می کند. اعتبارنامه ها روی شناسه و رمز عبور کاربری که مشتری شما از طرف او درخواست ارسال می کند تنظیم می شود. نمونه‌های موجود در این سند از سیستم احراز هویت "Authentication for Installed Applications" استفاده می‌کنند. برای اطلاعات بیشتر در مورد سایر سیستم های احراز هویت، به مستندات تأیید اعتبار حساب 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 و داده های باینری را در خود جای دهد.

هر نویسنده به عنوان یک نام، یک URI و یک آدرس ایمیل نشان داده می شود. (در این مثال، ما URI را کنار می گذاریم.) شما با افزودن یک شی AtomAuthor به مجموعه Authors ورودی، نویسنده ای را به ورودی اضافه می کنید.

ما از همان شیء Service استفاده می کنیم که در مثال قبلی ایجاد کردیم. در این مورد، روش فراخوانی Insert است که یک مورد را به URL درج مشخص شده ارسال می کند.

این سرویس ورودی جدید ایجاد شده را برمی گرداند، که ممکن است حاوی عناصر اضافی ایجاد شده توسط سرور باشد، مانند URL ویرایش برای ورودی.

کد بالا معادل ارسال POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (با احراز هویت مناسب) و ارائه یک ورودی است.

درخواست یک ورودی خاص

کد زیر به شما امکان می دهد ورودی خاصی را که در مثال قبلی وارد کرده اید درخواست کنید.

در زمینه این سری از مثال‌ها، بازیابی آن ورودی واقعاً ضروری نیست، زیرا Calendar قبلاً ورودی درج شده را برگردانده است. اما هر زمان که 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 را با تنها یک ورودی در مجموعه Entries دریافت کنیم.

کد بالا معادل ارسال GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/ entryID به Calendar با احراز هویت مناسب است.

جستجو برای ورودی

برای بازیابی اولین مورد در جستجوی متن کامل، از کد زیر استفاده کنید:

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 به Calendar است.

پرس و جو بر اساس دسته بندی

توجه : Google Calendar برچسب‌ها را با رویدادها مرتبط نمی‌کند، بنابراین این مثال با Calendar کار نمی‌کند.

برای بازیابی فید متشکل از تمام ورودی‌هایی که با جستجوی متن کامل قبلی مطابقت دارند و در یک دسته خاص قرار دارند یا برچسب خاصی دارند، از کد زیر استفاده کنید:

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

کلاس AtomCategory ، البته، یک دسته را نشان می دهد که در فیلتر دسته بندی استفاده می شود. کلاس QueryCategory می تواند شامل چندین دسته باشد، اما در این مورد ما یک فیلتر تنها با یک دسته می سازیم.

سپس آن فیلتر را به پرس و جوی موجود اضافه می کنیم، که همچنان شامل رشته پرس و جوی متن کامل از مثال قبلی است.

ما دوباره از روش Query برای ارسال پرس و جو به سرویس استفاده می کنیم.

اگر تقویم اجازه جستجوی دسته بندی را می داد، کد بالا معادل ارسال GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis به تقویم خواهد بود.

به روز رسانی یک مورد

برای به روز رسانی یک مورد موجود، از کد زیر استفاده کنید. در مثال زیر، عنوان ورودی بازیابی شده قبلی را از متن قدیمی آن ("تنیس با بث") به "جلسه مهم" تغییر می دهیم.

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 ویرایش است، بنابراین این مثال بسیار شبیه نمونه قبلی است، البته با این تفاوت که به جای Update روش Delete را فراخوانی می کنیم.

کد بالا تقریباً معادل ارسال DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/ entryID به سرویس است.

کار با فیدهای تقویم Google

مثال‌های بالا نحوه استفاده از Google Data C# API را برای کار با فیدهای GData عمومی نشان می‌دهند. با این حال، هنگامی که به طور خاص با فید تقویم Google کار می کنید، فید حاوی بسیاری از داده های مربوط به تقویم است که با استفاده از اشیاء استاندارد اتم گرا در کتابخانه پایه API به راحتی قابل دسترسی نیستند. برای کمک به شما در تعامل با آن فیدها، افزونه‌های زیر را ارائه می‌کنیم:

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

فضای نام Extensions به طور کلی با پسوندها سروکار دارد. فضای نام Calendar به شما امکان دسترسی به یک سرویس تقویم سفارشی، فید و شی پرس و جو را می دهد. می‌توانید نمونه‌ای دقیق‌تر از نحوه استفاده از آن افزونه‌ها در زیر شاخه /Samples نصب C# API پیدا کنید. اشیاء زیر اضافه می شوند:

EventQuery
یک زیر کلاس از FeedQuery که به شما امکان می دهد دو پارامتر سفارشی را برای سرویس Calendar تنظیم کنید (start-min و start-max).
Calendar Service
یک زیر کلاس از خدمات، که می تواند فید رویداد را برگرداند.
فید رویداد
یک زیر کلاس از AtomFeed که رویدادهای Entries را نشان می دهد.
ورود رویداد
یک زیر کلاس از AtomEntry که دارای ویژگی های اضافی مربوط به داده های تقویم است.

برای جزئیات بیشتر در مورد آن کلاس های ویژه، به مستندات API و برنامه نمونه ها مراجعه کنید.

ارجاع

برای اطلاعات مرجع در مورد کتابخانه مشتری C#، به مستندات مرجع مراجعه کنید.

بازگشت به بالا