חשוב: ב-30 בספטמבר 2024 נפסיק את התמיכה ב-V2.0 JSON API. כדי להבטיח פונקציונליות מתמשכת, צריך לעדכן את האפליקציות שמסתמכות על v2.0 JSON API לגרסה האחרונה של ה-API. בגרסה העדכנית ביותר, משתמשים בקישורים שבסרגל הניווט הימני.
במסמך הזה נסביר איך להתחיל להשתמש ב-Blogger JSON API.
תוכן עניינים
מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיכולות ליצור אינטראקציה עם Blogger JSON API.
Blogger JSON API מרחיב את גרסה 2.0 של Blogger Data API. אם רוצים לאחזר נתונים מ-Blogger בפורמט JSON ולא בפורמט XML, משתמשים ב-Blogger JSON API. אם רוצים לאחזר נתונים בפורמט XML, צריך להשתמש ב-Blogger Data API.
נכון לעכשיו, הגרסה הזו של Blogger JSON API היא לקריאה בלבד. עם זאת, אנחנו מתכננים להוסיף יכולות קריאה/כתיבה ויכולות נוספות. אתם יכולים לבקש תכונות נוספות בפורום העזרה של Blogger.
לפני שמתחילים
קבל חשבון Google
מוודאים בחשבון Google מוגדר. אנחנו ממליצים להשתמש בחשבון Google נפרד למטרות פיתוח ובדיקה, כדי להגן על עצמכם מפני אובדן מקרי של נתונים. אם כבר יש לך חשבון בדיקה, הכול מוכן. תוכל להיכנס לממשק המשתמש של Blogger כדי להגדיר, לערוך או להציג את נתוני הבדיקות.
היכרות עם Blogger
אם אתם לא מכירים את המושגים של Blogger, כדאי לקרוא את המסמך הזה ולנסות להשתמש בממשק המשתמש לפני שתתחילו לתכנת. ההנחה במסמך זה היא שאתם מכירים את Blogger, את מושגי התכנות באינטרנט ואת הפורמטים של נתוני אינטרנט.
מידע על הרשאת בקשות וזיהוי הבקשה שלך
כשהאפליקציה מבקשת מידע פרטי, הבקשה צריכה להיות מאושרת על ידי משתמש מאומת שיש לו גישה לנתונים האלה.
כשהאפליקציה מבקשת נתונים ציבוריים, אין צורך לקבל הרשאה, אבל יש לצרף לבקשה מזהה כמו מפתח API.
למידע על איך לאשר בקשות ולהשתמש במפתחות API, ראו את המאמר מתן הרשאה לבקשות וזיהוי האפליקציה במסמך 'שימוש ב-API'.
רקע של Blogger JSON API
מושגים ב-Blogger
Blogger מבוסס על חמישה מושגים בסיסיים:
- בלוגים: מושג הבסיס של ה-API. בבלוג יש פוסטים ודפים. זהו מאגר מטא-מידע של הבלוג, כמו Blog Name (שם הבלוג) ו-Description (תיאור).
- פוסטים: פוסט בבלוג הוא הפריט שמחבר הבלוג יצר. המידע הזה אמור להיות עדכני, וישקף את מה שהמחברים רוצים לפרסם בפני העולם עכשיו. ברור שעם הזמן, התוכן בבלוג מצטיין והופך להיות פחות רלוונטי.
- תגובות: תגובה היא המקום שבו אנשים אחרים, מלבד מחבר הפוסט, מגיבים למה שכתב המחבר. כל דבר, מלבנים ועד זרים.
- דפים: דף הוא מקום לתוכן סטטי, כמו מידע ביוגרפי, או דרכים ליצירת קשר עם המשתמש. בדרך כלל מדובר במידע חסר זמן שלא משתנה לעיתים קרובות.
- משתמשים: משתמש הוא מישהו שמקיים אינטראקציה עם Blogger, בין אם הוא פועל כמחבר, מנהל מערכת או רק קורא. בבלוגים ציבוריים, הקוראים יכולים להיות אנונימיים, אבל בבלוגים פרטיים הקוראים חייבים להיות מזוהים על ידי Blogger.
מודל נתונים ב-Blogger JSON API
משאב הוא ישות נתונים בודדת עם מזהה ייחודי. ה-API ל-JSON של Blogger פועל עם חמישה סוגים של משאבים:
- משאבי בלוגים: מייצג בלוג.
- מקור של פוסטים: מייצג פוסט. כל משאב של פוסט הוא צאצא של משאב של בלוגים.
- משאב של תגובות: מייצג תגובה לפוסט ספציפי. כל משאב של תגובות הוא צאצא של משאב של פוסט.
- Page Resource: מייצג דף סטטי. כל משאב Pages הוא צאצא של משאב בלוגים.
- משאב של משתמשים: מייצג משתמש לא אנונימי. משמש לזיהוי המחבר של הדף, הפוסט או התגובה.
מודל הנתונים של Blogger JSON API מבוסס על קבוצות של משאבים, שנקראים אוספים:
- אוסף הבלוגים
- <span="apicollection">אוסף בלוגים מורכב מכל הבלוגים שלמשתמש יש זכויות גישה אליהם. ניתן לרשום בלוגים לפי משתמשים, או לאחזר בלוג יחיד לפי מזהה.</span="apicollection">
- אוסף פוסטים
- אוסף פוסטים כולל את כל משאבי הפוסטים במשאב מסוים של בלוגים.
- אוסף תגובות
- אוסף תגובות מורכב מכל מקורות המידע לתגובות של מקור פוסטים ספציפי.
- אוסף דפים
- אוסף דפים כולל את כל משאבי הדפים במשאב בלוגים ספציפי.
- אוסף משתמשים
- אוסף משתמשים מורכב מכל משאבי המשתמשים ב-Blogger, ולכן לא ניתן להציג אותו. משתמש יכול לאחזר את המשאב של המשתמשים שלו (אבל לא של אף אחד אחר) לפי מזהה או באמצעות המזהה
self.
פעולות ב-Blogger API API
תוכלו להפעיל שתי שיטות שונות לאוספים ומשאבים ב-Blogger JSON API, כפי שמתואר בטבלה הבאה.
| פעולה | תיאור | מיפויי HTTP של REST |
|---|---|---|
| list | רשימה של כל המשאבים באוסף. | GET ב-URI של אוסף. |
| get | מקבלת משאב ספציפי. | GET ב-URI של משאב. |
הטבלה הבאה מציגה אילו שיטות נתמכות בכל סוג משאב. כל הפעולות list ו-get בבלוגים פרטיים מחייבות אימות.
Resource Type |
שיטות נתמכות |
|
|---|---|---|
| רשימה | get | |
| בלוגים | כן | כן |
| פוסטים | כן | כן |
| תגובות | כן | כן |
| דפים | כן | כן |
| משתמשים | no | כן |
סגנונות שיחה
יש כמה דרכים להפעיל את ה-API:
- שימוש ב-REST ישירות או מ-JavaScript (לא נדרש קוד בצד השרת)
- שימוש בספריות הלקוח.
REST
REST הוא סגנון של ארכיטקטורת תוכנה שמציע תפיסה נוחה ועקבית לבקשת נתונים ולשינוי שלהם.
המונח REST הוא קיצור של Representational State Transfer. בהקשר של Google APIs, 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 API ל-JSON
הפעולות הנתמכות ב-Blogger ממופות ישירות לפעלים מסוג REST HTTP, כפי שמתואר בפעולות של Blogger JSON API.
הפורמט הספציפי למזהי URI של Blogger API 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 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
אפשר להפעיל את Blogger JSON API באמצעות 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.