חשוב: נפסיק את התמיכה ב-API בפורמט JSON בגרסה 2.0 ב-30 בספטמבר 2024. כדי להבטיח שהאפליקציות ימשיכו לפעול, צריך לעדכן את האפליקציות שמסתמכות על ה-API בפורמט JSON בגרסה 2.0 לגרסה האחרונה של ה-API. כדי לקבל את הגרסה האחרונה, אפשר להשתמש בקישורים בסרגל הניווט הימני.
במאמר הזה נסביר איך להתחיל להשתמש ב-Blogger JSON API.
תוכן עניינים
מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיכולות לקיים אינטראקציה עם Blogger JSON API.
API בפורמט JSON של Blogger הוא תוספת לגרסה 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'.
רקע על ה-API בפורמט JSON של Blogger
מושגים ב-Blogger
Blogger מבוסס על חמישה מושגים בסיסיים:
- בלוגים: הרעיון הבסיסי של ה-API. בבלוג יש פוסטים ודפים. זהו המאגר של המטא-נתונים של הבלוג, כמו שם הבלוג והתיאור שלו.
- פוסטים: פוסט בבלוג הוא פריט שאפשר לפרסם שיצר מחבר הבלוג. המידע הזה אמור להיות עדכני, ולשקף את מה שהמחברים רוצים לפרסם לעולם עכשיו. ברור לנו שעם הזמן, התוכן של פוסטים בבלוג הופך לפחות רלוונטי.
- תגובות: תגובה היא המקום שבו אנשים שאינם מחברי הפוסט בבלוג יכולים להגיב על מה שהם כתבו. מלבנים ועד זרי פרחים.
- דפים: דף הוא מקום לתוכן סטטי, כמו מידע ביוגרפיה או דרכים ליצירת קשר עם המשתמש. בדרך כלל מדובר במידע שלא משתנה לעיתים קרובות.
- משתמשים: משתמש הוא מי שמנהל אינטראקציה עם Blogger, בין שהוא פועל בתור מחבר, אדמין או פשוט קורא. בבלוגים ציבוריים, הקוראים יכולים להיות אנונימיים, אבל בבלוגים פרטיים, הקוראים חייבים להיות מזוהים על ידי Blogger.
מודל הנתונים של Blogger JSON API
משאב הוא ישות נתונים בודדת עם מזהה ייחודי. API בפורמט JSON של Blogger פועל על חמישה סוגים של משאבים:
- משאב Blogs: מייצג בלוג.
- משאב פוסטים: מייצג פוסט. כל משאב פוסטים הוא צאצא של משאב בלוגים.
- משאב תגובות: מייצג תגובה על פוסט ספציפי. כל משאב תגובות הוא צאצא של משאב פוסטים.
- משאב דפים: מייצג דף סטטי. כל משאב דפים הוא צאצא של משאב בלוגים.
- משאב Users: מייצג משתמש לא אנונימי. השדה הזה משמש לזיהוי המחבר של דף, פוסט או תגובה.
מודל הנתונים של Blogger JSON API מבוסס על קבוצות של משאבים שנקראות אוספים:
- אוסף בלוגים
- אוסף <span="apicollection">Blogs מורכב מכל הבלוגים שלמשתמש יש הרשאות גישה אליהם. אפשר להציג רשימה של בלוגים לפי משתמש, או לאחזר בלוג יחיד לפי מזהה.</span="apicollection">
- אוסף פוסטים
- אוסף פוסטים מורכב מכל משאבי הפוסטים במשאב הבלוגים הספציפי.
- אוסף תגובות
- אוסף תגובות מורכב מכל משאבי התגובות במשאב פוסטים ספציפי.
- אוסף דפים
- אוסף דפים מורכב מכל משאבי הדפים במשאב בלוגים ספציפי.
- האוסף 'משתמשים'
- אוסף משתמשים מורכב מכל משאבי המשתמשים ב-Blogger, ולכן אי אפשר להוסיף אותו לרשימת המשאבים. משתמש יכול לאחזר את משאב המשתמשים שלו (אבל לא של אף משתמש אחר) לפי מזהה או באמצעות המזהה
self.
פעולות ב-Blogger JSON API
אפשר להפעיל שתי שיטות שונות על אוספים ומשאבים ב-Blogger JSON API, כפי שמתואר בטבלה הבאה.
| פעולה | תיאור | מיפויים של HTTP ל-REST |
|---|---|---|
| list | הצגת רשימה של כל המשאבים בתוך קולקציה. | GET ב-URI של אוסף. |
| get | אחזור משאב ספציפי. | GET ב-URI של משאב. |
בטבלה הבאה מוצגות השיטות שנתמכות בכל סוג משאב. כל הפעולות של list ו-get בבלוגים פרטיים מחייבות אימות.
Resource Type |
שיטות נתמכות |
|
|---|---|---|
| list | get | |
| בלוגים | כן | כן |
| פוסטים | כן | כן |
| תגובות | כן | כן |
| דפים | כן | כן |
| משתמשים | לא | כן |
סגנונות של שיחות
יש כמה דרכים להפעיל את ה-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 JSON API
הפעולות הנתמכות ב-Blogger ממופות ישירות לפעלים מסוג REST HTTP, כפי שמתואר במאמר פעולות ב-API בפורמט JSON של Blogger.
אלה הפורמטים הספציפיים למזהי URI של Blogger JSON API:
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 Reference.
ריכזנו כאן כמה דוגמאות לאופן שבו זה עובד ב-API ל-JSON של Blogger.
הצגת רשימת הבלוגים שלמשתמש המאומת יש הרשאות גישה אליהם:
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 ופונקציית קריאה חוזרת (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.