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

ה-API של נתוני Blogger מאפשר לאפליקציות לקוח להציג ולעדכן תוכן ב-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.

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

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

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

אתה מסכים לציית לתנאים ולהגבלות של ספריית הלקוח של Google JavaScript בעת השימוש בספריית הלקוח של 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 אחרי אחזור הטוען, משתמשים בשורה הבאה בקוד ההגדרה של 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

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

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

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

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

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

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

חזרה למעלה