با استفاده از Java Client Library

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

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

این سند اطلاعات کلی در مورد استفاده از کتابخانه سرویس گیرنده جاوا را به همراه مجموعه ای از نمونه هایی از کاربردهای رایج ارائه می دهد.

برای استفاده از این کتابخانه مشتری، باید جاوا 1.5 را اجرا کنید.

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

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

فهرست

  1. حضار
  2. نمای کلی مدل داده
  3. آموزش و مثال
    1. ساخت و اجرای مشتری شما
    2. درخواست فید
    3. درج یک مورد جدید
    4. درخواست یک ورودی خاص
    5. جستجوی ورودی ها
    6. پرس و جو بر اساس دسته بندی
    7. به روز رسانی یک مورد
    8. حذف یک مورد
  4. ارجاع

حضار

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

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

برای اطلاعات مرجع در مورد کلاس ها و روش های ارائه شده توسط کتابخانه مشتری، به مرجع API کتابخانه مشتری Java (در قالب جاوادوک) مراجعه کنید.

این سند برای خواندن به ترتیب طراحی شده است. هر مثال بر روی نمونه های قبلی استوار است.

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

کتابخانه سرویس گیرنده جاوا از مجموعه ای از کلاس ها برای نمایش عناصر استفاده شده توسط 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 را ارائه می‌کند.

آموزش و مثال

مثال‌های زیر نحوه ارسال درخواست‌های API مختلف داده با استفاده از کتابخانه سرویس گیرنده جاوا را نشان می‌دهند.

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

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

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

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

درخواست فید

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

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

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

همچنین باید احراز هویت مناسب را ارائه دهید. تفاوت اصلی بین این مثال و اولین مثال در سند Calendar این است که (1) این مثال شامل احراز هویت است و (2) این مثال از کلاس عمومی تر GoogleService به جای کلاس CalendarService ویژه Calendar استفاده می کند.

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

برای درخواست فید تقویم با استفاده از کتابخانه مشتری جاوا، برای کاربری با آدرس ایمیل "liz@gmail.com" و رمز عبور "mypassword"، از کد زیر استفاده کنید:

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

کلاس GoogleService یک اتصال مشتری (با احراز هویت) به یک سرویس GData را نشان می دهد. روال کلی برای ارسال پرس و جو به یک سرویس با استفاده از کتابخانه مشتری شامل مراحل زیر است:

  1. URL مناسب را بدست آورید یا بسازید.
  2. اگر داده‌ها را به یک سرویس ارسال می‌کنید (به عنوان مثال، اگر یک ورودی جدید را وارد می‌کنید)، سپس داده‌های خام را با استفاده از کلاس‌های کتابخانه مشتری به اشیا تبدیل کنید. (اگر فقط درخواست فید می کنید، همانطور که در این مثال انجام می دهیم، این مرحله اعمال نمی شود.)
  3. یک نمونه GoogleService جدید ایجاد کنید، نام سرویس (مانند "cl" برای Calendar) و نام برنامه خود را (به شکل companyName - applicationName - versionID ) تنظیم کنید.
  4. اعتبار مناسب را تنظیم کنید.
  5. به کتابخانه سرویس گیرنده نشان دهید که فید از چه پسوندهایی استفاده می کند، تا کتابخانه بتواند فیدهای برگشتی را به درستی تجزیه کند.
  6. برای ارسال درخواست و دریافت هر گونه نتیجه با روشی تماس بگیرید.

متد setUserCredentials شناسه و رمز عبور کاربری را مشخص می کند که مشتری شما از طرف او پرس و جو را ارسال می کند. نمونه‌های موجود در این سند از سیستم احراز هویت "Authentication for Installed Applications" استفاده می‌کنند. برای اطلاعات بیشتر در مورد سیستم های احراز هویت، به مستندات احراز هویت حساب Google مراجعه کنید.

پس از تنظیم اعتبار، با فراخوانی متد declareExtensions مشخص می‌کنید که فید از کدام افزونه‌ها استفاده خواهد کرد. در این مورد، ما می گوییم که فید یک فید رویداد است، و بنابراین از پسوندهای تعریف شده توسط نوع رویداد استفاده می کند.

برای درخواست یک فید کامل، شما با متد getFeed تماس می گیرید، که یک URL را می گیرد و کل فید موجود در آن URL را برمی گرداند. نحوه ارسال درخواست‌های خاص‌تر را بعداً در این سند نشان خواهیم داد.

مانند سایر روش‌های کلاس GoogleService ، getFeed احراز هویت و در صورت لزوم تغییر مسیر می‌دهد.

درج یک مورد جدید

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

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

پس از تنظیم URL، یک شی EventEntry می سازیم. EventEntry از کلاس پایه انتزاعی BaseEntry مشتق شده است، که همچنین کلاس والد برای کلاس Entry است که یک عنصر <atom:entry> را نشان می دهد.

کلاس EventEntry یک نوع Event را نشان می دهد. برای اطلاعات بیشتر، به سند Kinds مراجعه کنید. برای خدماتی غیر از Calendar، ممکن است ورودی برگشتی را به یک شیء Entry به جای یک شیء EventEntry اختصاص دهید.

عنوان ورودی یک TextConstruct است، کلاسی که متن را به اشکال مختلف (متن ساده، HTML یا XHTML) نگه می‌دارد. محتوای ورودی با یک شی Content نشان داده می شود، کلاسی که می تواند متن ساده یا سایر اشکال محتوا، از جمله XML و داده های باینری را در خود جای دهد. (اما متد setContent می تواند یک TextConstruct نیز بپذیرد.)

هر نویسنده به عنوان یک نام، یک URI و یک آدرس ایمیل نشان داده می شود. (در این مثال، ما URI را کنار می گذاریم.) شما با فراخوانی متد getAuthors ().add ورودی، یک نویسنده را به ورودی اضافه می کنید.

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

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

کدهای وضعیت HTTP به عنوان استثنا برگردانده می شوند.

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

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

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

در چارچوب این سری مثال‌ها، بازیابی آن ورودی واقعاً ضروری نیست، زیرا Calendar قبلاً ورودی درج شده را برگردانده است. اما هر زمان که URI یک ورودی را بشناسید می توانید از همین تکنیک استفاده کنید.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

مدخل درج شده دارای روشی است، getSelfLink ، که یک شی Link که شامل URL ورودی است را برمی گرداند. کلاس Link دارای یک متد getHref است که URL را به عنوان یک String برمی گرداند، که از آن می توانیم یک شی URL ایجاد کنیم.

سپس ما فقط باید با متد getEntry سرویس تماس بگیریم تا ورودی را دریافت کنیم.

توجه داشته باشید که ما EventEntry.class به‌عنوان پارامتری به getEntry می‌دهیم، که نشان می‌دهد به‌طور خاص انتظار داریم که این سرویس به‌جای یک ورودی ساده، یک رویداد را برگرداند. برای سرویس‌هایی غیر از Calendar، می‌توانید Entry.class به جای آن پاس کنید.

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

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

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

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

این مثال با ساختن یک آبجکت Query که بیشتر از یک URL به اضافه پارامترهای پرس و جو مرتبط است، شروع می شود. هر یک از پارامترهای پرس و جوی استاندارد GData یک متد تنظیم کننده دارد. همچنین می توانید با استفاده از روش addCustomParameter ، پارامترهای پرس و جوی سفارشی را برای یک سرویس خاص تنظیم کنید.

پس از ساخت Query ، آن را به متد query سرویس ارسال می کنیم، که فید حاوی نتایج پرس و جو را برمی گرداند. یک رویکرد جایگزین این است که خودتان یک URL بسازید (با افزودن پارامترهای پرس و جو به URL فید) و سپس متد getFeed را فراخوانی کنید، اما روش query لایه مفیدی از انتزاع را فراهم می کند تا مجبور نباشید URL را خودتان بسازید.

متد getEntries فید لیستی از ورودی های فید را برمی گرداند. getEntries().size تعداد ورودی‌های موجود در فید را برمی‌گرداند.

در این حالت، اگر پرس و جو نتایجی را برگرداند، اولین نتیجه مطابق را به یک شیء Entry اختصاص می دهیم. سپس از متد getTitle ().getPlainText کلاس Entry برای بازیابی عنوان ورودی و تبدیل آن به متن استفاده می کنیم.

کد بالا معادل ارسال GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis به Calendar است.

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

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

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

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

البته کلاس Category یک دسته را نشان می دهد که در فیلتر دسته بندی استفاده می شود. کلاس Query.CategoryFilter می تواند شامل چندین دسته باشد، اما در این مورد ما یک فیلتر تنها با یک دسته می سازیم.

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

ما دوباره از روش query برای ارسال درخواست به سرویس استفاده می کنیم.

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

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

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

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

ابتدا یک عنوان جدید برای ورودی که قبلا واکشی کردیم تعیین می کنیم. سپس با استفاده از روش getEditLink URL ویرایش ورودی را دریافت می کنیم. سپس روش update سرویس را فراخوانی می کنیم تا ورودی به روز شده ارسال شود.

این سرویس ورودی به روز شده را باز می گرداند، از جمله URL جدید برای نسخه جدید این ورودی. (برای اطلاعات بیشتر در مورد نسخه های ورودی، به بخش همزمانی خوش بینانه سند مرجع پروتکل مراجعه کنید.)

کد بالا تقریباً معادل ارسال PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/ entryID به سرویس به همراه ورودی جدید (در قالب Atom) برای جایگزینی است. ورودی اصلی

حذف یک مورد

برای حذف ورودی به روز شده، از کد زیر استفاده کنید:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

URL مورد استفاده برای حذف مانند URL ویرایش است، بنابراین این مثال بسیار شبیه نمونه قبلی است، البته با این تفاوت که به جای update روش delete را فراخوانی می کنیم.

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

ارجاع

برای اطلاعات مرجع در مورد کلاس ها و روش های ارائه شده توسط کتابخانه سرویس گیرنده، به مرجع API کتابخانه مشتری Java (در فرمت Javadoc) مراجعه کنید.

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