Blogger JSON API: תחילת העבודה

במסמך הזה נסביר איך להתחיל להשתמש ב-Blogger JSON API.

תוכן עניינים

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

מבוא

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

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

כרגע, הגרסה הזו של ממשק ה-API של Blogger JSON היא לקריאה בלבד, אבל אנחנו מתכננים להוסיף יכולות קריאה/כתיבה וגם יכולות אחרות. ניתן לבקש תכונות נוספות בפורום העזרה של Blogger.

לפני שמתחילים

קבל חשבון Google

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

היכרות עם Blogger

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

מידע נוסף על אישור בקשות וזיהוי הבקשה

כאשר הבקשה שלכם מבקשת נתונים פרטיים, רק משתמשים מאומתים שיש להם גישה לנתונים האלה צריכים לקבל הרשאה.

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

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

רקע של Blogger JSON API

הקונספטים של Blogger

Blogger מבוסס על חמישה עקרונות בסיסיים:

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

מודל נתונים של Blogger JSON API

משאב הוא ישות נתונים נפרדת עם מזהה ייחודי. ה-Blogger API API פועל בחמישה סוגים של משאבים:

  • Resources Resource: מייצג בלוג.
  • משאב פוסטים: מייצג פוסט. כל משאב של פוסט הוא צאצא של משאב 'בלוגים'.
  • משאב תגובות: מייצג תגובה בפוסט ספציפי. כל משאב של תגובות הוא צאצא של משאב פוסטים.
  • משאב 'דפים': מייצג דף סטטי; כל משאב 'דפים' הוא צאצא של משאב 'בלוגים'.
  • משאב משתמשים: מייצג משתמש שאינו אנונימי. משמש לזיהוי המחבר של דף, פוסט או תגובה.
למשאב בלוגים יש שני סוגי משאבים לילדים, דפים ופוסטים. למשאב פוסטים יכולים להיות חשבונות של משאב תגובות.
סקירה כללית של הקשרים בין המשאבים

מודל הנתונים של Blogger JSON API מבוסס על קבוצות של משאבים, הנקראים אוספים:

אוסף בלוגים
A <span="apicollection">אוסף הבלוגים כולל את כל הבלוגים שיש למשתמש גישה אליהם. אפשר לציין בלוגים לפי משתמש או לאחזר בלוג יחיד לפי מזהה.</span="apicollection">
איסוף פוסטים
אוסף פוסטים מכיל את כל משאבי הפוסטים בתוך משאב ספציפי של בלוגים.
איסוף תגובות
אוסף תגובות כולל את כל משאבי התגובות בתוך משאב ספציפי של פוסטים.
איסוף דפים
אוסף דפים מכיל את כל משאבי הדפים במשאב ספציפי של בלוגים.
אוסף משתמשים
אוסף משתמשים כולל את כל משאבי המשתמשים ב-Blogger, ולכן לא ניתן לרשום אותם. משתמש יכול לאחזר משאב משתמש משלו (אבל אף אחד אחר) לפי מזהה, או באמצעות המזהה self.

פעולות API ל-Blogger JSON

ניתן להפעיל שתי שיטות שונות לאוספים ולמשאבים ב-Blogger JSON API, כפי שמתואר בטבלה הבאה.

פעולה תיאור מיפויי HTTP ב-REST
list רשימה של כל המשאבים בתוך אוסף. GET ב-URI של אוסף.
הורדה מקבלים משאב ספציפי. GET ב-URI של משאב.

בטבלה הבאה אפשר לראות אילו שיטות נתמכות בכל סוג משאב. כל הפעולות של רשימות והורדה בבלוגים פרטיים מחייבות אימות.

Resource Type
שיטות נתמכות
רשימה קבלת
בלוגים כן כן
פוסטים כן כן
תגובות כן כן
דפים כן כן
משתמשים no כן

סגנונות של שיחות

יש כמה דרכים להפעיל את ה-API:

REST

‏REST הוא סגנון של ארכיטקטורת תוכנה שמציע תפיסה נוחה ועקבית לבקשת נתונים ולשינוי שלהם.

המונח REST הוא קיצור של Representational State Transfer. בהקשר של ממשקי ה-API של Google,‏ REST מתייחס לשימוש בפעלי HTTP כדי לאחזר ולשנות ייצוגים של נתונים ש-Google מאחסנת.

במערכת RESTful, המשאבים מאוחסנים במאגר נתונים. לקוח שולח בקשה לשרת לבצע פעולה מסוימת (כמו יצירה, אחזור, עדכון או מחיקה של משאב), והשרת מבצע את הפעולה ושולח תגובה – לעיתים קרובות בצורת ייצוג של המשאב שצוין.

בממשקי RESTful API של Google, הלקוח מציין פעולה באמצעות פועל HTTP כמו POST, GET, PUT או DELETE. הוא מציין משאב לפי URI גלובלי ייחודי, באופן הבא:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

מאחר שלכל משאבי ה-API יש מזהי URI ייחודיים שניתן לגשת אליהם ב-HTTP,‏ מערכת REST מאפשרת לשמור נתונים במטמון ומבצעת אופטימיזציה של העבודה באמצעות התשתית המבוזרת של האינטרנט.

תוכלו להיעזר בהגדרות השיטה במסמכי התיעוד של תקני HTTP 1.1 – הן כוללות מפרטים עבור GET, POST, PUT ו-DELETE.

REST ב-Blogger JSON API

הפעולות הנתמכות ב-Blogger ממופה ישירות לפעלים של HTTP ב-REST, כפי שמתואר בפעולות ה-API ב-Blogger JSON.

הפורמט הספציפי ל-URIs של API ל-Blogger JSON הוא:

https://www.googleapis.com/blogger/v2/users/userId
https://www.googleapis.com/blogger/v2/users/self
https://www.googleapis.com/blogger/v2/users/userId/blogs
https://www.googleapis.com/blogger/v2/users/self/blogs

https://www.googleapis.com/blogger/v2/blogs/blogId/posts
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v2/blogs/blogId/pages
https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId

הסבר מלא על מזהי URI שמופיעים ועל התוצאות של כל פעולה נתמכת ב-API מסוכם במסמך Blogger JSON API.

ריכזנו כאן כמה דוגמאות לאופן הפעולה של הממשק הזה ב-Blogger JSON API.

רשימה של הבלוגים שלמשתמש המאומת יש גישה אליהם:

GET https://www.googleapis.com/blogger/v2/users/self/blogs?key=YOUR-API-KEY

פרסום הפוסטים בבלוג code.blogger.com (עם מזהה הבלוג 3213900):

GET https://www.googleapis.com/blogger/v2/blogs/3213900?key=YOUR-API-KEY

REST מ-JavaScript

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

הדוגמה הבאה מאחזרת פוסט מהבלוג code.blogger.com (לאחר שתחליף את YOUR-API-KEY במפתח ה-API).

<html>
  <head>
    <title>Blogger JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v2/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

פורמט נתונים

JSON

JSON‏ (JavaScript Object Notation) הוא פורמט נתונים נפוץ בלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף: json.org.