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

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

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

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

תוכן עניינים

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

קהל

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

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

למידע על הכיתות והשיטות שספריית הלקוח מספקת, ראו מידע על API של ספריית לקוח ב-JavaScript.

מומלץ לקרוא את המסמך לפי הסדר, כל דוגמה מבוססת על דוגמאות קודמות.

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

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

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

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

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

תחילת העבודה

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

יצירת חשבון Blogger

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

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

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

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

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

כדי לקבל את ספריית הלקוח של Google Data API אחרי אחזור ה-loader, משתמשים בשורה הבאה בקוד ההגדרה של 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() היא פונקציה שנגדיר בקטע מאוחר יותר במסמך הזה. מומלץ להשתמש בגישה הזו במקום לצרף טיפולן של onload לאלמנט <body>.

אימות לשירות Blogger

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

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

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

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

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

  1. אפליקציית הלקוח מפעילה את השיטה google.accounts.user.login() שמספקת ספריית הלקוח, ומעבירה לה ערך 'היקף' שמציין באיזה שירות Google להשתמש. ב-Blogger, ההיקף הוא "http://www.blogger.com/feeds/".
  2. ספריית הלקוח שולחת את הדפדפן לדף 'בקשת גישה' של Google, שבו המשתמש יכול להזין את פרטי הכניסה שלו כדי להתחבר לשירות.
  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, ספריית הלקוח קוראת ל-method‏ google.gdata.client.init(), שמאמתת שהדפדפן שבו פועל הלקוח נתמך. אם יש שגיאה, ספריית הלקוח מציגה הודעת שגיאה למשתמש. אם אתם רוצים לטפל בעצמכם בשגיאות כאלה, תוכלו להפעיל את google.gdata.client.init(handleInitError) באופן מפורש לפני יצירת השירות, כאשר handleInitError() היא הפונקציה שלכם. אם מתרחשת שגיאה ב-init, הפונקציה מקבלת אובייקט Error רגיל. אתם יכולים לעשות עם האובייקט הזה מה שאתם רוצים.

האסימון יישאר בתוקף עד שתבטלו אותו באמצעות קריאה ל-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.

חזרה למעלה