راهنمای توسعه دهنده: جاوا اسکریپت

Blogger Data API به برنامه های مشتری اجازه می دهد تا محتوای Blogger را در قالب فیدهای Google Data API مشاهده و به روز کنند.

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

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

فهرست

  1. حضار
  2. شرایط استفاده
  3. درباره محیط های پشتیبانی شده
  4. شروع شدن
    1. ایجاد حساب بلاگر
    2. در اختیار گرفتن کتابخانه
  5. احراز هویت در سرویس بلاگر
    1. احراز هویت پروکسی AuthSub

حضار

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

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

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

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

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

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

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

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

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

شروع شدن

قبل از اینکه بتوانید یک برنامه کلاینت جاوا اسکریپت بنویسید، باید تنظیماتی را برای به دست آوردن کتابخانه انجام دهید.

ایجاد حساب بلاگر

ممکن است بخواهید برای اهداف آزمایشی برای یک حساب Blogger ثبت نام کنید . Blogger از حساب‌های Google استفاده می‌کند، بنابراین اگر از قبل یک حساب Google دارید، همه چیز آماده است.

در اختیار گرفتن کتابخانه

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

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

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

برای به دست آوردن کتابخانه سرویس گیرنده Google Data API پس از واکشی بارگذار، از خط زیر در کد تنظیم جاوا اسکریپت خود استفاده کنید، که باید از بخش <head> سند HTML خود (یا از یک فایل جاوا اسکریپت که با استفاده از یک <script> گنجانده شده است فراخوانی شود. در بخش <head> سند HTML خود را تگ کنید:

google.load("gdata", "1.x");

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

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

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

google.setOnLoadCallback(getMyBlogFeed);

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

احراز هویت در سرویس بلاگر

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

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

احراز هویت پروکسی AuthSub

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

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

  1. برنامه سرویس گیرنده متد google.accounts.user.login() ارائه شده توسط کتابخانه سرویس گیرنده را فراخوانی می کند و یک مقدار "scope" به آن ارسال می کند که نشان می دهد از کدام سرویس Google استفاده شود. برای Blogger، محدوده "http://www.blogger.com/feeds/" است.
  2. کتابخانه مشتری مرورگر را به صفحه "درخواست دسترسی" گوگل می فرستد، جایی که کاربر می تواند اعتبار خود را برای ورود به سرویس وارد کند.
  3. اگر کاربر با موفقیت وارد سیستم شود، سیستم AuthSub مرورگر را به URL مشتری وب ارسال می‌کند و رمز احراز هویت را ارسال می‌کند.
  4. کتابخانه سرویس گیرنده جاوا اسکریپت رمز را در یک کوکی ذخیره می کند و کنترل را به تابع برنامه مشتری که google.accounts.user.login() نامیده می شود، برمی گرداند.
  5. هنگامی که برنامه سرویس گیرنده متعاقباً روش های کتابخانه مشتری را که با بلاگر تعامل دارند فراخوانی می کند، کتابخانه سرویس گیرنده به طور خودکار رمز را به همه درخواست ها متصل می کند.

توجه : برای اینکه کتابخانه سرویس گیرنده جاوا اسکریپت درخواست های تأیید شده بلاگر را در یک مرورگر وب انجام دهد، صفحه شما باید حاوی تصویری باشد که در همان دامنه صفحه شما میزبانی می شود. این می تواند هر تصویری باشد، حتی یک تصویر شفاف تک پیکسلی، اما باید یک تصویر در صفحه وجود داشته باشد. اگر می خواهید تصویر در صفحه شما نمایش داده نشود، می توانید از ویژگی style تگ <img> برای قرار دادن تصویر در خارج از ناحیه رندر استفاده کنید. به عنوان مثال: style="position:absolute; top: -1000px;"

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

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

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

نکته : اکیداً توصیه می‌کنیم که یک دکمه ورود به سیستم یا مکانیزم ورودی کاربر دیگر را ارائه کنید تا از کاربر بخواهد فرآیند ورود به سیستم را به صورت دستی شروع کند. اگر در عوض، بلافاصله پس از بارگیری، بدون انتظار تعامل کاربر، google.accounts.user.login() را فراخوانی کنید، اولین چیزی که کاربر هنگام ورود به صفحه شما می بیند یک صفحه ورود به سیستم گوگل است. اگر کاربر تصمیم گرفت وارد سیستم نشود، گوگل آنها را به صفحه شما هدایت نمی کند. بنابراین از نظر کاربر، آنها سعی کردند از صفحه شما بازدید کنند اما فرستاده شدند و هرگز برنگشتند. این سناریو ممکن است برای کاربران گیج کننده و خسته کننده باشد. در کد مثال در این سند، ما بلافاصله پس از بارگیری با google.accounts.user.login() تماس می گیریم تا مثال را ساده نگه داریم، اما ما این روش را برای برنامه های کاربردی کلاینت در دنیای واقعی توصیه نمی کنیم.

توجه داشته باشید که لازم نیست کاری با متغیری به نام token انجام دهید. کتابخانه سرویس گیرنده رمز را ردیابی می کند، بنابراین شما مجبور نیستید.

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

رمز تا زمانی که با فراخوانی google.accounts.user.logout() آن را لغو نکنید معتبر باقی می ماند:

function logMeOut() {
  google.accounts.user.logout();
}

اگر logout() را فراخوانی نکنید، کوکی که توکن را ذخیره می‌کند دو سال باقی می‌ماند، مگر اینکه کاربر آن را حذف کند. کوکی در تمام جلسات مرورگر حفظ می شود، بنابراین کاربر می تواند مرورگر خود را ببندد و سپس آن را دوباره باز کند و به مشتری شما بازگردد و همچنان وارد سیستم می شود.

با این حال، شرایط غیرعادی خاصی وجود دارد که در آن یک توکن می‌تواند در طول یک جلسه نامعتبر شود. اگر Blogger یک نشانه را رد کرد، مشتری شما باید با فراخوانی logout() برای حذف کوکی حاوی نشانه فعلی، و سپس فراخوانی مجدد login() برای بدست آوردن یک رمز جدید و معتبر، شرایط خطا را کنترل کند.

دو روش دیگر AuthSub وجود دارد که ممکن است در زمینه‌های مختلف مفید باشند:

  • google.accounts.user.checkLogin(scope) به شما می گوید که آیا مرورگر در حال حاضر یک نشانه احراز هویت برای محدوده داده شده دارد یا خیر.
  • google.accounts.user.getInfo() اطلاعات دقیقی در مورد رمز فعلی برای استفاده در اشکال زدایی ارائه می دهد.

برای جزئیات در مورد استفاده از جاوا اسکریپت برای تعامل با AuthSub، از جمله اطلاعات مربوط به مدیریت توکن و checkLogin() و getInfo() ، به استفاده از احراز هویت "AuthSub" با سند کتابخانه مشتری جاوا اسکریپت مراجعه کنید.

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