המדריך למפתחים: JavaScript

ממשק ה-API של Blogger Data מאפשר לאפליקציות לקוח להציג ולעדכן תוכן של Blogger בצורת פידים של Google Data API.

בעזרת אפליקציית הלקוח שלכם ב-Blogger Data API תוכלו ליצור פוסטים חדשים בבלוג, לערוך או למחוק פוסטים בבלוגים קיימים ולהגיש שאילתות על פוסטים בבלוג שתואמים לקריטריונים מסוימים.

בנוסף להסבר על היכולות של ה-Blogger Data API, במסמך הזה מפורטות דוגמאות לאינטראקציות בסיסיות עם Data API באמצעות ספריית הלקוח ב-JavaScript. אם אתם רוצים לקבל מידע נוסף על הפרוטוקול שבו הספרייה משתמשת, עיינו בקטע 'פרוטוקול' במדריך הזה.

תוכן עניינים

  1. קהל
  2. תנאים והגבלות
  3. מידע על סביבות נתמכות
  4. איך מתחילים
    1. יצירת חשבון Blogger
    2. רכישת הספרייה
  5. אימות לשירות Blogger
    1. אימות שרת proxy של OAuthSub

Audience

המסמך הזה מיועד למתכנתים שרוצים לכתוב אפליקציות לקוח JavaScript שיכולות לקיים אינטראקציה עם Blogger. היא מספקת סדרת דוגמאות לאינטראקציות בסיסיות של Data API באמצעות ספריית הלקוח של JavaScript.

במדריך העזר לפרוטוקולים ניתן למצוא מידע על קובצי עזר ב-Blogger Data API. המסמך הזה יוצא מנקודת הנחה שהבנת את הרעיונות הכלליים שמאחורי פרוטוקול Google Data APIs ואת מודל הנתונים ותהליך הבקרה שמשמשים את ספריית הלקוחות של JavaScript. הוא גם מניח שאתם יודעים איך לתכנת ב-JavaScript.

בחומר העזר בנושא JavaScript של ספריית JavaScript אפשר לקרוא מידע נוסף על הקורסים והשיטות שסופקו על ידי ספריית הלקוח.

אנחנו קוראים את המסמך הזה לפי הסדר, וכל דוגמה מבוססת על דוגמאות קודמות.

תנאים והגבלות

את/ה מסכים/ה לציית לתנאים ולהגבלות של ספריית הלקוח ב-Google JavaScript בעת השימוש בספריית הלקוח של JavaScript.

מידע על סביבות נתמכות

נכון לעכשיו אנחנו תומכים רק באפליקציות של לקוח JavaScript שפועלות בדף אינטרנט בדפדפן. הדפדפנים הנתמכים כרגע הם Firefox 1.5 ואילך, ו-Internet Explorer 6.0 ואילך.

ספריית הלקוח של JavaScript מטפלת בכל התקשורת עם השרת&#39. אם אתם מפתחי JS מנוסים, יכול להיות שאתם חושבים, "אבל מה לגבי אותו מדיניות מקור?" ספריית הלקוח של JavaScript מאפשרת ללקוח לשלוח בקשות Google Data API מכל דומיין, תוך שמירה על מודל האבטחה של הדפדפן.

איך מתחילים

לפני שכותבים אפליקציה של לקוח JavaScript, צריך לבצע הגדרה כלשהי כדי לקבל את הספרייה.

יצירת חשבון Blogger

ייתכן שתרצו להירשם לחשבון Blogger למטרות בדיקה. Blogger משתמש בחשבונות Google, כך שאם כבר יש לכם חשבון Google, אתם מוכנים.

רכישת הספרייה

כדי שהלקוח יוכל להשתמש בספריית הלקוחות, הוא צריך לבקש את קוד ספריית הלקוח מהשרת.

התחילו באמצעות תג <script> בקטע <head> של מסמך ה-HTML כדי לאחזר את טעינת ה-API של ממשק ה-API של Google:

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

כדי לקבל את ספריית הלקוח של Google Data API אחרי שטוענים את הכלי לטעינת תוכנות, יש להשתמש בשורה הבאה בקוד הגדרת ה-JavaScript, שצריך לקרוא בקטע <head> במסמך ה-HTML (או מקובץ JavaScript שכלול בתג <script> בקטע <head> במסמך ה-HTML):

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

הפרמטר השני אל google.load() הוא מספר הגרסה המבוקשת של ספריית הלקוח ב-JavaScript.סכמת מספור הגרסאות שלנו היא לפי המודל שבו נעשה שימוש ב-Google Maps API. הנה מספרי הגרסאות האפשריים והמשמעות שלהם:

"1"
הגרסה השנייה והאחרונה של גרסה 1.
"1.x"
הגרסה האחרונה (גרסה 1) של הגרסה הראשית.
"1.s"
הגרסה היציבה האחרונה של גרסה ראשית 1. אנחנו נכריז מדי פעם על גרסה מסוימת של ספריית הלקוח שתהיה "יציבה,"על סמך משוב שאנחנו מקבלים ממפתחים. עם זאת, יכול להיות שהגרסה הזו לא כוללת את התכונות העדכניות ביותר.
"1.0", "1.1" וכו'
גרסה ספציפית של הספרייה, עם מספר שכתוב ראשי ומשני.

לאחר שהתקשרת אל google.load(), יש לומר למטען להמתין עד לסיום הטעינה של הדף ואז להתקשר לקוד:

google.setOnLoadCallback(getMyBlogFeed);

בקטע getMyBlogFeed(), פונקציה שנגדיר בקטע שבהמשך של המסמך הזה. השתמשו בגישה הזו במקום לצרף handler של onload לאלמנט <body>.

מתבצע אימות לשירות Blogger

ניתן לגשת גם לפיד ציבורי וגם לפיד פרטי באמצעות Blogger Data API. אין צורך באימות כלשהו עבור פידים ציבוריים, אבל הם לקריאה בלבד. אם אתם רוצים לשנות בלוגים, הלקוח שלכם צריך לבצע אימות לפני שיבקש פידים פרטיים.

ספריית הלקוח של JavaScript משתמשת במערכת האימות של AuthSub. למידע נוסף על אימות באמצעות ממשקי API של Google Data, אפשר לעיין במסמכי האימות.

אימות שרת proxy של AuthSub

אימות שרת proxy של AuthSub משמש את אפליקציות האינטרנט שצריכים לאמת את המשתמשים שלהן לחשבונות Google. למפעיל האתר ולקוד הלקוח אין גישה לשם המשתמש ולסיסמה של משתמש Blogger, אלא הלקוח מקבל אסימוני AuthSub מיוחדים שמאפשרים ללקוח לפעול בשם המשתמש.

לפניכם סקירה קצרה של מה שיקרה בתהליך האימות ללקוח JavaScript באינטרנט.

  1. אפליקציית הלקוח קוראת לשיטה google.accounts.user.login() שסופקה על ידי ספריית הלקוח. היא מעבירה את הערך "scope" ומציין באיזה שירות של Google להשתמש. ב-Blogger, ההיקף הוא "http://www.blogger.com/feeds/".
  2. ספריית הלקוח שולחת את הדפדפן לדף Google'S "בקשת בקשה", שבו המשתמש יכול להזין את פרטי הכניסה שלו כדי להתחבר לשירות.
  3. אם המשתמש מתחבר בהצלחה, מערכת AuthSub שולחת את הדפדפן לכתובת ה-URL של לקוח האינטרנט להעברה של אסימון האימות.
  4. ספריית הלקוח ב-JavaScript מאחסנת את האסימון בקובץ cookie ומחזירה שליטה לפונקציה של אפליקציית הלקוח שנקראת google.accounts.user.login().
  5. כשאפליקציית הלקוח מתקשרת בהמשך לשיטות ספריית לקוח שיש להן אינטראקציה עם Blogger, ספריית הלקוח מצרפת את האסימון באופן אוטומטי לכל הבקשות.

הערה: כדי שספריית הלקוחות בפרוטוקול JavaScript תבצע בקשות מאומתות ל-Blogger בדפדפן, הדף חייב להכיל תמונה שמתארחת באותו דומיין של הדף. היא יכולה להיות כל תמונה, כולל תמונה שקופה בפיקסל יחיד, אך חייבת להיות תמונה בדף. אם אתם רוצים שהתמונה לא תופיע בדף, תוכלו להשתמש במאפיין 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. אם המשתמש מחליט שלא להתחבר, Google לא מפנה אותו בחזרה לדף שלכם. מנקודת המבט של המשתמש, הוא ניסה להיכנס לדף שלכם אבל לא נשלח הלאה. התרחיש הזה עלול לבלבל ומבלבל את המשתמשים. בקוד לדוגמה במסמך הזה, נתקשר למספר google.accounts.user.login() מיד לאחר הטעינה, כדי שהדוגמה תהיה פשוטה, אבל אנחנו לא ממליצים על הגישה הזו לאפליקציות של לקוחות בעולם האמיתי.

חשוב לזכור: לא צריך לעשות דבר עם המשתנה בשם token; ספריית הלקוח עוקבת אחר האסימון, כך שאין צורך לעשות זאת.

הערה: כשיוצרים אובייקט חדש של BloggerService, ספריית הלקוח קוראת לשיטה הנקראת google.gdata.client.init(), ובודקת שהדפדפן שבו הלקוח משתמש נתמך. אם יש שגיאה, ספריית הלקוח תציג למשתמש הודעת שגיאה. אם אתם רוצים לטפל בשגיאה זו בעצמכם, תוכלו לקרוא במפורש ל-google.gdata.client.init(handleInitError) לפני שתיצרו את השירות, כאשר handleInitError() הוא הפונקציה שלכם. אם מופיעה שגיאת init, הפונקציה מקבלת אובייקט שגיאה רגיל. אפשר לבצע את כל פעולה שרוצים באובייקט.

האסימון יישאר בתוקף עד שתבטלו אותו באמצעות קריאה google.accounts.user.logout():

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

אם לא תתבצע קריאה ל-logout(), קובץ ה-cookie שבו נשמר האסימון יישמר למשך שנתיים, אלא אם המשתמש ימחק אותו. קובץ ה-Cookie נשמר בפעילויות שונות בדפדפן, כך שהמשתמש יכול לסגור את הדפדפן שלו ואז לפתוח אותו מחדש ולחזור ללקוח ואז הוא עדיין יהיה מחובר.

עם זאת, יש נסיבות חריגות מסוימות שבהן אסימון עשוי להפוך ללא חוקי במהלך סשן. אם Blogger דחה אסימון, הלקוח צריך לטפל במצב השגיאה באמצעות קריאה ל-logout() להסרת קובץ ה-cookie שמכיל את האסימון הנוכחי, ולאחר מכן התקשרות שוב ל-login() כדי לקבל אסימון חדש וחוקי.

יש שתי שיטות AuthSub שעשויות להיות שימושיות בהקשרים שונים:

  • המדיניות google.accounts.user.checkLogin(scope) מציינת אם לדפדפן יש כרגע אסימון אימות בהיקף הנתון.
  • google.accounts.user.getInfo() מספק מידע מפורט על האסימון הנוכחי.

לפרטים על השימוש ב-JavaScript כדי לבצע פעולות ב-AuthSub, כולל מידע בנושא ניהול אסימונים ב-checkLogin() וב-getInfo(), ניתן לעיין במסמך שימוש ב-"AuthSub" אימות באמצעות ספריית לקוח של JavaScript.

חזרה למעלה