استفاده از کتابخانه مشتری جاوا اسکریپت (نسخه 2.0)

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

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

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

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

حضار

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

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

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

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

شرایط استفاده

هنگام استفاده از کتابخانه سرویس گیرنده جاوا اسکریپت، موافقت می کنید که از شرایط استفاده از کتابخانه سرویس گیرنده Google JavaScript پیروی کنید.

مدل داده و نمای کلی جریان کنترل

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

توجه : نمایش زیربنایی داده‌ها JSON است، اما کتابخانه مشتری یک لایه انتزاعی ارائه می‌کند، بنابراین نیازی نیست مستقیماً با داده‌های JSON کار کنید. اگر می‌خواهید مستقیماً با JSON کار کنید، بدون کتابخانه سرویس گیرنده، به استفاده از JSON با Google Data API مراجعه کنید.

این کتابخانه روش هایی را ارائه می دهد که به شما امکان می دهد داده ها را به صورت ناهمزمان به سرویسی که دارای API داده است ارسال و از آن دریافت کنید. برای مثال، متد google.gdata.calendar.CalendarService.getEventsFeed() درخواستی را برای فید به Google Calendar ارسال می کند. یکی از پارامترهایی که شما ارسال می کنید یک تابع ادامه است که به عنوان برگشت تماس نیز شناخته می شود. این سرویس با فراخوانی تابع ادامه، فید را در قالب JSON برمی گرداند. سپس کلاینت می تواند روش های مختلف get برای استفاده از داده ها در قالب اشیاء جاوا اسکریپت فراخوانی کند.

برای افزودن یک ورودی جدید، ورودی را با استفاده از کلاس‌ها و متدهای کتابخانه مشتری ایجاد می‌کنید، سپس متد feed.insertEntry() را فراخوانی می‌کنید تا ورودی جدید به سرویس ارسال شود. مجدداً یک تابع ادامه ارائه می‌دهید که وقتی ورودی با موفقیت اضافه شد، سرویس آن را فراخوانی می‌کند.

اگر با جاوا اسکریپت تازه کار هستید، جریان کنترل ممکن است کمی گیج کننده باشد. پس از فراخوانی متدی مانند getEventsFeed() یا insertEntry() ، در اکثر موارد اسکریپت شما به پایان می رسد. زمانی که سرویس داده های درخواستی را برمی گرداند، اجرا در تابع Continuation از سر گرفته می شود. بنابراین، هر کاری که مشتری شما با داده های برگشتی انجام می دهد باید در تابع Continuation انجام شود یا از آن تابع فراخوانی شود. ممکن است لازم باشد برخی از متغیرها را به منظور استفاده در چندین توابع جهانی کنید.

برای اطلاعات بیشتر در مورد این سبک از برنامه نویسی، به " سبک ادامه عبور " در ویکی پدیا مراجعه کنید.

درباره محیط های پشتیبانی شده

در حال حاضر، ما فقط از برنامه های سرویس گیرنده جاوا اسکریپت که در یک صفحه وب در مرورگر اجرا می شوند، پشتیبانی می کنیم. مرورگرهایی که در حال حاضر پشتیبانی می شوند عبارتند از:

  • فایرفاکس 2.x و 3.x
  • اینترنت اکسپلورر 6، 7، و 8
  • سافاری 3.x و 4.x
  • گوگل کروم (همه نسخه ها)

کتابخانه سرویس گیرنده جاوا اسکریپت تمام ارتباطات با سرور سرویس را مدیریت می کند. اگر یک توسعه دهنده باتجربه JS هستید، ممکن است فکر کنید، "اما در مورد همان سیاست مبدا چطور؟" کتابخانه سرویس گیرنده جاوا اسکریپت به مشتری شما اجازه می دهد تا درخواست های Google Data را از هر دامنه ای ارسال کند در حالی که با مدل امنیتی مرورگر سازگار است.

برای بررسی اجمالی احراز هویت با Google Data API، به نمای کلی احراز هویت Google Data APIs مراجعه کنید. بقیه این سند فرض می کند که شما با اصول اولیه نحوه کار این سیستم آشنا هستید.

نمونه برنامه های مشتری

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

آموزش و مثال

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

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

در حال بارگیری کتابخانه

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

با استفاده از تگ <script> در بخش <head> سند HTML خود برای واکشی Google AJAX API loader شروع کنید:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

می‌توانید با بارگیری پیش‌بارگذاری کتابخانه، رفت‌وآمدها به سرورهای Google را به حداقل برسانید و تأخیر را کاهش دهید. برای پیش بارگیری بسته های خاص به طور مستقیم از بارگذار AJAX API Google (بدون استفاده از google.load() به زیر مراجعه کنید)، از موارد زیر استفاده کنید:

<script type="text/javascript"
      src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>

توجه : URL src اسکریپت باید به طور کامل urlencod شده باشد. به عنوان مثال، مثال قبلی است
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script> .

اگر ماژول‌ها را خودکار بارگیری نمی‌کنید، می‌توانید کتابخانه سرویس گیرنده Google Data را با استفاده از مثال بعدی در کد راه‌اندازی جاوا اسکریپت خود، پس از واکشی بارگذار معمولی بارگیری کنید. این تماس باید از بخش <head> سند HTML شما (یا از یک فایل جاوا اسکریپت که با استفاده از تگ <script> در بخش <head> سند HTML شما گنجانده شده است) انجام شود:

google.load("gdata", "2");

از طرف دیگر، می توانید خدمات خاصی را به جای کل کتابخانه درخواست کنید. این مثال فقط بسته‌های Blogger و Contacts را دانلود می‌کند:

google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});

دومین پارامتر برای google.load() شماره نسخه درخواستی کتابخانه مشتری جاوا اسکریپت است. طرح شماره‌گذاری نسخه ما بر اساس طرحی که توسط Google Maps API استفاده می‌شود، مدل‌سازی شده است. در اینجا شماره نسخه های احتمالی و معنای آنها آمده است:

"1"
نسخه دوم به آخرین نسخه اصلی 1.
"1.x"
آخرین ویرایش نسخه اصلی 1.
"1.s"
آخرین ویرایش پایدار نسخه اصلی 1. ما گهگاه بر اساس بازخوردی که از توسعه دهندگان دریافت می کنیم، نسخه خاصی از کتابخانه سرویس گیرنده را "پایدار" اعلام می کنیم. با این حال، آن نسخه ممکن است آخرین ویژگی ها را نداشته باشد.
"1.0" ، "1.1 " و غیره
یک نسخه خاص از کتابخانه، با شماره ویرایش اصلی و فرعی مشخص شده.

بعد از اینکه google.load() را فراخوانی کردید، باید به لودر بگویید صبر کند تا بارگذاری صفحه تمام شود و سپس کد شما را فراخوانی کند:

google.setOnLoadCallback(getMyFeed);

جایی که getMyFeed() تابعی است که در بخش بعدی این سند تعریف شده است. به جای اینکه یک onload handler متصل به عنصر <body> داشته باشید، از این رویکرد استفاده کنید.

درخواست فید احراز هویت نشده

برای درخواست فید احراز هویت نشده، کد زیر را به فایل جاوا اسکریپت خود یا به تگ <script> در فایل HTML خود اضافه کنید.

در کد زیر ابتدا getMyFeed() فراخوانی می شود (توسط AJAX API loader همانطور که در قسمت قبل توضیح داده شد).

این برنامه setupMyService() را برای ایجاد یک اتصال (که توسط یک شی CalendarService نشان داده می شود) به تقویم Google فراخوانی می کند. ما کد ایجاد سرویس را در یک تابع جداگانه برای مدولار بودن بیرون آورده ایم. بعداً، تابع setupMyService() را بسته به انتخاب‌های احراز هویت شما تغییر می‌دهیم.

پس از راه اندازی سرویس، getMyFeed() متد getEventsFeed() کتابخانه مشتری را برای درخواست فید فراخوانی می کند.

ما URL فید را در یک متغیر سراسری مشخص می کنیم تا بتوان از آن در توابع بعدی استفاده کرد. در این مثال، ما از نشانی اینترنتی فید عمومی (غیر احراز هویت) برای کاربری به نام liz@gmail.com استفاده می‌کنیم. همچنین می‌توانید default به جای آدرس ایمیل کاربر برای نشان دادن کاربر تأیید شده استفاده کنید.

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";

function setupMyService() {
  var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
  return myService;
}

function getMyFeed() {
  myService = setupMyService();

  myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}

توجه داشته باشید که ما در حال تبدیل کردن myService به یک متغیر جهانی برای سهولت استفاده در توابع بعدی هستیم.

برای اینکه کد بالا در کلاینت خود کار کند، باید از آدرس ایمیل یک کاربر واقعی برای یک حساب Calendar با یک تقویم به اشتراک گذاشته شده عمومی استفاده کنید.

توجه : هنگامی که یک شی CalendarService جدید ایجاد می کنید، کتابخانه سرویس گیرنده متدی به نام google.gdata.client.init() را فراخوانی می کند که بررسی می کند مرورگری که کلاینت در آن اجرا می شود پشتیبانی می شود. اگر خطایی وجود داشته باشد، کتابخانه سرویس گیرنده پیام خطا را به کاربر نمایش می دهد. اگر می‌خواهید این نوع خطا را خودتان مدیریت کنید، می‌توانید قبل از ایجاد سرویس، google.gdata.client.init(handleInitError) handleInitError() تابع شما است، به صراحت تماس بگیرید. اگر یک خطای init رخ دهد، تابع شما یک شی استاندارد Error دریافت می کند. شما می توانید هر کاری که می خواهید با آن شی انجام دهید.

در فراخوانی getEventsFeed() آرگومان دوم handleMyFeed است که یک تابع callback است. زیر را ببینید. Google Calendar درخواست را پردازش می‌کند و سپس، در صورت موفقیت‌آمیز بودن درخواست، یک شیء "ریشه فید" حاوی فید درخواستی را به پاسخ تماس ارسال می‌کند. ریشه خوراک یک شی ظرفی است که حاوی خوراک است.

آرگومان سوم برای getEventsFeed() یک تابع مدیریت خطای اختیاری است. اگر کتابخانه سرویس گیرنده با خطا مواجه شود، به جای تابع callback موفقیت، کنترل کننده خطای مشخص شده را فراخوانی می کند. شیئی که کتابخانه سرویس گیرنده به عنوان آرگومان به کنترل کننده خطا ارسال می کند، نمونه ای از شیء Error جاوا اسکریپت است که دارای ویژگی cause اضافی است.

در اینجا نسخه های ساده تابع تماس و کنترل کننده خطا آمده است:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}

function handleError(e) {
  alert("There was an error!");
  alert(e.cause ? e.cause.statusText : e.message);
}

ما خطاها را به سادگی با نمایش آنها به کاربر مدیریت می کنیم. کنترل کننده خطای مشتری شما احتمالاً باید پیچیده تر باشد. در برخی زمینه ها، ممکن است هیچ دلیلی مشخص نشده باشد، بنابراین در این موارد، کنترل کننده خطای مثال ما به نمایش ویژگی message استاندارد بازمی گردد.

توجه داشته باشید که از آنجایی که این کد احراز هویت را انجام نمی دهد، می توانید از آن فقط برای دریافت فید عمومی استفاده کنید.

احراز هویت

کتابخانه سرویس گیرنده جاوا اسکریپت را می توان در دو حالت استفاده کرد. اگر در حال نوشتن یک ابزار هستید، پس از آن از یک ویژگی به نام پروکسی OAuth برای احراز هویت استفاده می کند. اگر از یک برنامه جاوا اسکریپت مستقل به آن دسترسی داشته باشید، از سیستم احراز هویت AuthSub استفاده می کند. برای کسب اطلاعات در مورد احراز هویت، به سند مرور کلی احراز هویت APIs Google مراجعه کنید. بقیه این بخش فرض می کند که شما با اصول اولیه نحوه کار این سیستم آشنا هستید.

قبل از استفاده از احراز هویت با کد نمونه ارائه شده در این سند، URL فید را از عمومی به خصوصی تغییر دهید:

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";

احراز هویت در یک سرویس گیرنده وب با AuthSub

سیستم مجوز Google "AuthSub for JavaScript" دیگر در دسترس نیست.

در عوض، توصیه می‌کنیم از OAuth 2.0 برای برنامه‌های سمت سرویس گیرنده استفاده کنید.

احراز هویت در یک ابزارک با پروکسی OAuth

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

  1. اسبابک شما برای اولین بار بارگیری می شود و سعی می کند با استفاده از یکی از APIهای Google Data به داده های کاربر دسترسی پیدا کند.
  2. درخواست ناموفق است زیرا کاربر هنوز اجازه دسترسی به داده‌های خود را نداده است. شی پاسخ حاوی یک URL (در response.oauthApprovalUrl ) برای صفحه تأیید OAuth است. ابزار شما باید روشی برای راه اندازی یک پنجره جدید با آن URL ارائه دهد.
  3. در صفحه تأیید، کاربر انتخاب می‌کند که دسترسی به ابزار شما را اعطا یا رد کند. در صورت موفقیت، کاربر به صفحه oauth_callback که شما مشخص کرده اید منتقل می شود. برای بهترین تجربه کاربری، از http://oauth.gmodules.com/gadgets/oauthcallback استفاده کنید.
  4. در مرحله بعد، کاربر پنجره بازشو را می بندد. برای کمک به اطلاع دادن به اسبابک شما مبنی بر اینکه کاربر تأیید را صادر کرده است، یک کنترلر بازشو ارائه کرده ایم که می توانید از آن برای تشخیص بسته شدن پنجره تأیید استفاده کنید. از طرف دیگر، ابزار شما می‌تواند پیوندی (به عنوان مثال " من دسترسی را تایید کرده‌ام ") را برای کاربر نمایش دهد تا پس از بسته شدن این پنجره به صورت دستی روی آن کلیک کند.
  5. ابزار شما برای بار دوم با درخواست مجدد داده‌های کاربر، سعی می‌کند به Google Data API دسترسی پیدا کند. این تلاش موفقیت آمیز است.
  6. ابزار شما احراز هویت شده است و می تواند به طور معمول شروع به کار کند.

در ابزار خود، یک عنصر <OAuth> را در بخش <ModulePrefs> اضافه کنید:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" /> 
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" /> 
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" /> 
  </Service>
</OAuth>
...
</ModulePrefs>

در این بخش، پارامترهای کوئری زیر را تغییر دهید:

  • scope

    یک پارامتر مورد نیاز در URL درخواست. ابزار شما فقط می‌تواند از scope (های) مورد استفاده در این پارامتر به داده‌ها دسترسی داشته باشد. در این مثال، این ابزار به داده‌های Blogger و Calendar شما دسترسی خواهد داشت. یک اسبابک می‌تواند داده‌ها را برای یک محدوده یا چند دامنه درخواست کند (همانطور که این مثال انجام می‌دهد).

  • oauth_callback

    یک پارامتر اختیاری در URL مجوز. صفحه تأیید OAuth پس از تأیید دسترسی کاربر به داده های خود، به این URL هدایت می شود. می توانید انتخاب کنید که این پارامتر را کنار بگذارید، آن را روی "صفحه تایید شده" خود تنظیم کنید، یا ترجیحاً از http://oauth.gmodules.com/gadgets/oauthcallback استفاده کنید. زمانی که کاربران برای اولین بار اسبابک شما را نصب می کنند، نسخه بعدی بهترین تجربه کاربری را ارائه می دهد. آن صفحه یک قطعه از جاوا اسکریپت را ارائه می دهد که به طور خودکار پنجره بازشو را می بندد.

سپس، کتابخانه سرویس گیرنده جاوا اسکریپت را در بخش <Content> ابزار خود بارگیری کنید. تابع setupMyService() را از مثال های قبلی تغییر دهید تا متد useOAuth() شیء سرویس را فراخوانی کنید. این به ابزارک می‌گوید به جای AuthSub از پروکسی OAuth برای احراز هویت استفاده کند. این الگوی زیر باید شما را شروع کند:

<Content type="html">
<![CDATA[
  ...
  <script src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">
    var myService = null;
    
    function setupMyService() {
      myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
      myService.useOAuth('google');
      fetchData();
    }
    
    function initGadget() {
      google.load('gdata', '2.x');
      google.setOnLoadCallback(setupMyService);
    }

    function fetchData() {            
      var callback = function(response) {
        if (response.oauthApprovalUrl) {
        
          // TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL) 
          
        } else if (response.feed) {
        
          // TODO: show results
          
        } else {
        
          // TODO: handle the error
          
        }
      };

      myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
    }
    
    gadgets.util.registerOnLoadHandler(initGadget);
  </script>
  ...
]]> 
</Content>

توجه داشته باشید که تماس با google.accounts.user.login(scope) حذف شده است. پروکسی احراز هویت را برای شما انجام می دهد.

برای اطلاعات بیشتر در مورد نوشتن اسبابک‌های Google Data API، از جمله جزئیات آنچه که fetchData() باید داشته باشد، به مقاله ما در مورد ایجاد ابزارک داده Google مراجعه کنید یا مستندات کامل Writing OAuth Gadgets را بررسی کنید.

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

برای ایجاد یک رویداد تقویم جدید، با تغییر انتهای تابع handleMyFeed() برای فراخوانی یک تابع جدید، اجرای را از مثال قبلی ادامه دهید:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
  insertIntoMyFeed(myResultsFeedRoot);
}

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

function insertIntoMyFeed(feedRoot) {
  var newEntry = new google.gdata.calendar.CalendarEventEntry({
      authors: [{
        name: "Elizabeth Bennet",
        email: "liz@gmail.com"
      }],
      title: {
        type: 'text', 
        text: 'Tennis with Darcy'
      },
      content: {
        type: 'text', 
        text: 'Meet for a quick lesson'
      },
      locations: [{
        rel: "g.event",
        label: "Event location",
        valueString: "Netherfield Park tennis court"
      }],
      times: [{
        startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
        endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
      }]
  });
  feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}

توجه داشته باشید که نام هر ویژگی شی مورد استفاده در سازنده با نام متد setter استفاده شده برای آن ویژگی مطابقت دارد. (به جای اینکه مثلاً با نام فیلد JSON مربوطه مطابقت داشته باشد.)

همچنین توجه داشته باشید که نمی‌توانید فقط رشته‌های تاریخ و زمان ISO 8601 را برای startTime و endTime ارائه دهید. ابتدا باید چنین رشته هایی را از طریق متد fromIso8601() اجرا کنید.

این سرویس یک کپی از ورودی درج شده را به عنوان یک شی entryRoot برمی گرداند و آن شی را به callback ارسال می کند:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}

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

برای درخواست یک ورودی خاص، ابتدا تابع handleMyInsertedEntry() را برای فراخوانی یک تابع درخواست ورودی جدید تغییر دهید:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
  requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}

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

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

function requestMySpecificEntry(entryURI) {
  myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}

این مثال اساساً مشابه مثال getEventsFeed() است، با این تفاوت که ما متد getEventEntry() سرویس را برای دریافت یک ورودی خاص فراخوانی می کنیم، و URI کمی متفاوت است—از «پیش فرض» برای ارجاع به تقویم اصلی استفاده می کند. برای کاربر احراز هویت شده، و یک شناسه ورودی در انتهای آن دارد.

همچنین، ما باید بتوانیم بعداً از ورودی بازیابی شده استفاده کنیم، بنابراین آن را در یک متغیر سراسری کپی می کنیم.

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

برای انجام یک جستجوی متن کامل، ابتدا تابع handleMySpecificEntry() را برای فراخوانی یک تابع جستجوی جدید تغییر دهید:

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
  searchMyFeed();
}

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

function searchMyFeed() {
  var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
  myQuery.setFullTextQuery("Tennis");
  myQuery.setMaxResults(10);
  myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}

function handleMyQueryResults(myResultsFeedRoot) {
  if (myResultsFeedRoot.feed.getEntries()[0]) {
    alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
  }
  else {
    alert("There are no entries that match the search query.");
  }
}

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

برای به‌روزرسانی یک مورد موجود، ابتدا یک خط به انتهای handleMyQueryResults() اضافه کنید تا یک تابع به‌روزرسانی جدید را فراخوانی کنید:

  updateMyEntry();

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

function updateMyEntry() {
  myEntryRoot.entry.getTitle().setText("Important meeting");
  myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}

function handleMyUpdatedEntry(updatedEntryRoot) {
  alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}

مانند تمام متدهای Calendar، متد updateEntry() به طور خودکار URI ویرایش صحیح را برای استفاده در به‌روزرسانی ورودی تعیین می‌کند، بنابراین شما مجبور نیستید آن URI را به طور صریح ارائه دهید.

حذف یک مورد

برای حذف ورودی به روز شده، ابتدا یک خط به handleMyUpdatedEntry() اضافه کنید:

 deleteMyEntry(updatedEntryRoot);

سپس از کد زیر استفاده کنید:

function deleteMyEntry(updatedEntryRoot) {
  updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}

function handleMyDeletedEntry() {
  alert("Entry deleted");
}

مجدداً، متد deleteEntry() به طور خودکار URI ویرایش صحیح را برای استفاده در حذف ورودی تعیین می کند.

توجه داشته باشید که هیچ ورودی برگردانده نمی شود. اگر تماس برگشتی فراخوانی شود، می دانیم که حذف با موفقیت انجام شده است. اگر حذف نشد، deleteEntry() به جای فراخوانی handleMyDeletedEntry() handleError() را فراخوانی می کند.

استفاده از ETags

توجه : تگ‌های ET را فقط می‌توان با سرویس‌هایی که پروتکل داده‌های Google نسخه ۲.۰ را اجرا می‌کنند استفاده کرد.

معرفی

نسخه 2 Google Data JavaScript Client پشتیبانی از ETags را معرفی می کند. ETag ها شناسه هایی هستند که نسخه خاصی از یک ورودی خاص را مشخص می کنند. این در دو مورد مهم است:

  • انجام یک "بازیابی مشروط"، که در آن یک کلاینت یک ورودی را درخواست می کند، و سرور تنها در صورتی ورودی را ارسال می کند که ورودی از آخرین باری که مشتری آن را درخواست کرده تغییر کرده باشد.
  • اطمینان از اینکه چندین مشتری سهواً تغییرات یکدیگر را بازنویسی نمی کنند. APIهای داده این کار را با عدم موفقیت به‌روزرسانی‌ها و حذف‌ها انجام می‌دهند، اگر مشتری یک ETag قدیمی برای ورودی مشخص کند.

دو نوع ETag وجود دارد: ضعیف و قوی. یک ETag ضعیف همیشه با W/ شروع می شود، به عنوان مثال: W/"D08FQn8-eil7ImA9WxZbFEw" . تگ های ضعیف ET تضمینی برای تغییر در هنگام تغییر ورودی نیستند، بنابراین HTTP اجازه می دهد تا آنها را فقط برای بازیابی مشروط استفاده کنید. ETag های قوی یک نسخه خاص از یک ورودی خاص را شناسایی می کنند و می توانند هم برای بازیابی مشروط و هم در حین به روز رسانی یا حذف استفاده شوند تا از بازنویسی تغییرات سایر مشتریان جلوگیری شود. به دلیل این تمایز، کتابخانه مشتری به شما اجازه نمی‌دهد تگ‌های ضعیف ET را با درخواست به‌روزرسانی یا حذف ارسال کنید.

تگ های ET را می توان در دو مکان در پاسخ سرور یافت:

  • در هدر ETag HTTP.
  • در فید/ورودی، به عنوان ویژگی gd:etag .

اگر سرویسی از نسخه 2 پشتیبانی کند، هر شیء ورودی و خوراک دارای یک متد getEtag() برای بازیابی مقدار ETag خواهد بود.

کلاینت جاوا اسکریپت از دو روش برای گنجاندن ETag با یک درخواست پشتیبانی می کند. اولی شیء جدید opt_params است. همه توابع get/update/insert در نسخه 2 کتابخانه مشتری دارای یک پارامتر opt_params جدید هستند. این شیء برای تعیین پارامترهای اختیاری هنگام درخواست استفاده می شود. در حال حاضر، 'etag' تنها پارامتر اختیاری پشتیبانی شده است (اگرچه ممکن است پارامترهای دیگری در آینده معرفی شوند). به عنوان مثال، می توانید یک ETag به درخواست GET مانند این اضافه کنید:

var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);

همچنین می توانید با فراخوانی متد setEtag() در feed/entry، یک ETag را مستقیماً به یک فید یا شی ورودی اضافه کنید.

می توانید از مرجع پروتکل GData درباره ETag ها بیشتر بیاموزید.

استفاده از ETags برای بازیابی داده ها

ETag ها می توانند به کاهش پهنای باند و زمان اجرا در هنگام بازیابی داده ها کمک کنند. یک ETag ممکن است در یک درخواست GET با هدر If-None-Match header:

If-None-Match: ETAG GOES HERE

اگر ETag با نسخه فعلی فید یا ورودی مطابقت داشته باشد، سرور با یک پاسخ 304 NOT MODIFIED و بدنه خالی پاسخ می دهد. در غیر این صورت، سرور با یک پاسخ 200 OK و داده های خوراک یا ورودی پاسخ می دهد.

می‌توانید از ETags در سرویس گیرنده جاوا اسکریپت با گنجاندن یک پارامتر 'etag' هنگام درخواست استفاده کنید:

var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);

بازیابی های مشروط با ETag های قوی و ضعیف کار می کنند. اگر ETag مطابقت داشته باشد، کنترل کننده خطا با یک پاسخ 304 فراخوانی می شود:

function successHandler(feedRoot) {
  // 200 response
  // Update UI to display updates
}

function errorHandler(errorObj) {
  if (errorObj.cause.getStatus() == 304) {
    // 304 response, do nothing
  }
  // otherwise the response is some other error
}

نگاهی به نمونه Conditional Retrieval Using Blogger بیندازید تا نمونه کاربردی تر استفاده از ETags در کلاینت جاوا اسکریپت را ببینید. این نمونه نظرسنجی Blogger را در فواصل 5 ثانیه ای به دنبال به روز رسانی وبلاگ شما می کند. هنگامی که تغییراتی وجود دارد، نمونه فهرستی از پست ها را به روز می کند.

استفاده از ETags برای به روز رسانی و حذف داده ها

استفاده از ETags در درخواست‌های به‌روزرسانی/حذف، تضمین می‌کند که چندین کلاینت سهواً تغییرات یکدیگر را بازنویسی نمی‌کنند. در این مورد، یک ETag با هدر If-Match اضافه می شود:

If-Match: ETAG GOES HERE

اگر ETag در درخواست با ETag در سرور مطابقت داشته باشد، به روز رسانی/حذف با موفقیت انجام می شود. با این حال، عدم تطابق ETag نشان می دهد که ورودی تغییر کرده است، و به روز رسانی/حذف ناموفق است. در این مورد، برنامه باید یک نمونه جدید از داده ها را درخواست کند و سپس دوباره به روز رسانی/حذف را امتحان کند.

در موارد خاص، ممکن است بخواهید تغییرات خود را بدون در نظر گرفتن هر تغییر دیگری در ورودی اعمال کنید. می توانید این کار را با ارسال یک * به هدر If-Match انجام دهید:

If-Match: *

به خاطر داشته باشید که این کار تغییرات ایجاد شده توسط سایر مشتریان را لغو می کند، بنابراین با دقت از آن استفاده کنید.

شما فقط می توانید یک ورودی را با ETag قوی به روز کنید/حذف کنید. تعیین یک ETag ضعیف منجر به خطا می شود. برای محافظت در برابر این مورد، سرویس گیرنده جاوا اسکریپت تگ های ضعیفی را در درخواست های به روز رسانی و حذف تنظیم نمی کند.

تگ‌های ET به همان شیوه بازیابی مشروط استفاده می‌شوند:

function updateData(entry, service) {
  var etag = entry.getEtag();
  var opt_params = {};
  opt_params['etag'] = etag; // Or use '*' to force an update.
  service.updateEntry(successHandler, errorHandler, opt_params);
}

function successHandler(response) {
  // Successful update
}

function errorHandler(errorObj) {
  // ERROR - Update failed. Could be due to an ETag mismatch, but check the
  // error message to make sure. An ETag error will be in the format:
  // Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}

هنگام به روز رسانی، یک ETag را می توان در دو مکان مشخص کرد:

  1. در خود ورودی با استفاده از متدهای getEtag() و setEtag() .
  2. در هدر، با استفاده از شی opt_params (همانطور که در بالا نشان داده شد).

ورودی بارگیری شده از درخواست قبلی GET از قبل دارای یک فیلد ETag است. بنابراین تعیین ETag یکسان در شی opt_params اضافی است. در صورتی که یک ETag هم در متن ورودی و هم در opt_params مشخص شده باشد، ETag در opt_params اولویت خواهد داشت. این می تواند کمی گیج کننده باشد، بنابراین اگر با به روز رسانی های مشروط مشکل دارید، حتماً ETag را هم در ورودی و هم در شی opt_params بررسی کنید.

برای آسان‌تر کردن کارها، کلاس‌های google.gdata.Entry نیز متدهای updateEntry() و deleteEntry() خود را دارند. اگر کلاس ورودی قبلاً دارای ETag باشد، لازم نیست آن را به درخواست اضافه کنید. کتابخانه مشتری این کار را به طور خودکار برای شما انجام می دهد. مثلا:

// entry was loaded from a previous request.  No need to specify
// an ETag in opt_params here, it is added automatically.
entry.deleteEntry(successHandler, errorHandler);

این به شما مزایای ETags را می دهد، اگر آنها را به درستی تنظیم کنید، بدون نگرانی. اما اگر می‌خواهید با استفاده از '*' به‌روزرسانی را مجبور کنید، همیشه باید شی opt_params را با 'etag' = '*' وارد کنید.

می‌توانید به‌روزرسانی‌های مشروط را در «به‌روزرسانی‌های مشروط» در «مخاطبین» مشاهده کنید. نمونه ابتدا یک گروه تماس آزمایشی ایجاد می کند که در آن تمام داده های استفاده شده توسط این نمونه ایجاد می شود. پس از اتمام کار با نمونه، این گروه تماس را حذف کنید. سپس نمونه دو iframe را با محتوای گروه تماس بارگیری می کند. می‌توانید به‌روزرسانی‌ها را در یک iframe انجام دهید و ببینید که چگونه روی به‌روزرسانی‌ها در iframe دیگر تأثیر می‌گذارد. برای جزئیات بیشتر در مورد نحوه استفاده از آن به نمونه مراجعه کنید.

نمونه ها

  • بازیابی مشروط در بلاگر - هر 5 ثانیه یک بار Blogger را نظرسنجی می کند و به روز رسانی ها را بررسی می کند.
  • به‌روزرسانی مشروط در مخاطبین - دو iframe جداگانه را با داده‌های مخاطبین نشان می‌دهد، بنابراین می‌توانید نحوه تعامل دو کلاینت هنگام ایجاد/به‌روزرسانی/حذف مخاطبین را دوباره ایجاد کنید.

ارجاع

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

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