במסמך הזה נסביר איך להתחיל להשתמש ב-API של Blogger.
לפני שמתחילים
קבל חשבון Google
לוודא שיש לכם חשבון Google מוגדר. כדי להגן על עצמכם מפני אובדן מקרי של נתונים, מומלץ להשתמש בחשבון Google נפרד למטרות פיתוח ובדיקה. אם כבר יש לכם חשבון בדיקה, הכול מוכן. אתם יכולים להיכנס לממשק המשתמש של Blogger כדי להגדיר, לערוך או להציג את נתוני הבדיקה.
היכרות עם Blogger
אם אתם לא מכירים את המושגים של Blogger, כדאי לקרוא את המסמך הזה ולהתנסות בממשק המשתמש לפני שתתחילו לתכנת. המסמך הזה מניח שאתם מכירים את Blogger, את המושגים לתכנות באינטרנט ואת הפורמטים של נתוני האינטרנט.
מידע נוסף על אישור בקשות וזיהוי הבקשה
כשהאפליקציה שלכם מבקשת מידע פרטי, הבקשה חייבת להיות מאושרת על ידי משתמש מאומת שיש לו גישה לנתונים האלה.
כשהאפליקציה מבקשת נתונים ציבוריים, לא צריך לאשר את הבקשה, אבל צריך לצרף לה מזהה, כמו מפתח API.
למידע על אישור בקשות ושימוש במפתחות API, ראו הרשאות בקשות וזיהוי האפליקציה במסמך השימוש ב-API.
רקע של Blogger API
מושגים ב-Blogger
Blogger מבוסס על חמישה מושגים בסיסיים:
- בלוגים: המושג הבסיסי (root) של ה-API. בבלוג יש פוסטים ודפים. זהו מאגר המידע למטא-מידע של הבלוג, כמו שם הבלוג והתיאור.
- פוסטים: פוסט בבלוג הוא הפריט שניתן לפרסם שנוצר על ידי כותב הבלוג. המידע הזה אמור להופיע בזמן אמת, והוא משקף את מה שהכותבים רוצים לפרסם לעולם עכשיו. ברור לנו שככל שהזמן עובר, התוכן בבלוג מתפרסם והופך להיות פחות רלוונטי.
- תגובות: תגובה היא המקום שבו אנשים אחרים מלבד מי שכתב את הפוסט מגיבים למה שכתב המחבר. הכול מלבנים ועד זרים.
- דפים: דף הוא מקום לתוכן סטטי, כמו מידע ביוגרפי או דרכים ליצירת קשר עם המשתמש. בדרך כלל מדובר במידע נצחי שלא משתנה לעיתים קרובות.
- משתמשים: משתמש הוא מי שמקיים אינטראקציה עם Blogger, בין אם הוא פועל כמחבר, כאדמין או רק כקורא. בבלוגים ציבוריים, הקוראים יכולים להיות אנונימיים, אבל בבלוגים פרטיים הקורא חייב להיות מזוהה על ידי Blogger.
מודל הנתונים של Blogger API
משאב הוא ישות נתונים בודדת עם מזהה ייחודי. ה-API בפורמט JSON של Blogger פועל על חמישה סוגי משאבים:
- מקור מידע על בלוגים: מייצג בלוג.
- משאב פוסטים: מייצג פוסט. כל משאב של פוסטים הוא צאצא של משאב בלוגים.
- מקור תגובות: מייצג תגובה בפוסט ספציפי. כל משאב של תגובות הוא צאצא של משאב פוסטים.
- משאב Pages: מייצג דף סטטי. כל משאב של דף הוא צאצא של משאב בלוגים.
- משאב משתמשים: מייצג משתמש לא אנונימי. משמש לזיהוי המחבר של דף, פוסט או תגובה.
מודל הנתונים של Blogger API מבוסס על קבוצות של משאבים, שנקראות 'אוספים':
- אוסף בלוגים
- אוסף <span="apicollection">בלוגים מורכב מכל הבלוגים שלמשתמש יש גישה אליהם. אפשר לרשום בלוגים לפי משתמש, או לאחזר בלוג יחיד לפי מזהה.</span="apicollection">
- אוסף פוסטים
- אוסף פוסטים מורכב מכל המשאבים של פוסטים במשאב ספציפי של בלוגים.
- איסוף תגובות
- אוסף תגובות מורכב מכל המשאבים לתגובות במשאב ספציפי של פוסטים.
- איסוף דפים
- אוסף דפים כולל את כל המשאבים של הדפים במשאב בלוגים ספציפי.
- אוסף משתמשים
- אוסף משתמשים מורכב מכל משאבי המשתמשים ב-Blogger, ולכן אי אפשר להציג אותו ברשימה. משתמש יכול לאחזר את משאב המשתמשים שלו
(אבל לא של אף אחד אחר) לפי מזהה או באמצעות המזהה
self.
פעולות ב-Blogger API
אפשר להפעיל כמה שיטות שונות לגבי אוספים ומשאבים ב-Blogger API, כמו שמתואר בטבלה הבאה.
| פעולה | תיאור | מיפויים של HTTP ב-REST |
|---|---|---|
| list | רשימה של כל המשאבים באוסף. | GET ב-URI של אוסף. |
| הורדה | קבלת משאב ספציפי. | GET ב-URI של משאב. |
| getByUrl | מקבל משאב, מחפש אותו לפי כתובת אתר. | GET בכתובת ה-URL שמועברת כפרמטר. |
| getByPath | מקבל משאב על ידי חיפושו לפי הנתיב שלו. | GET בנתיב שמועבר כפרמטר. |
| listByUser | בתיבת הדו-שיח הזו מפורטים משאבים שבבעלות משתמש. | GET באוסף בבעלות המשתמש. |
| search | חיפוש משאבים על סמך פרמטר של שאילתה. | GET בכתובת URL של חיפוש, כשהשאילתה מועברת כפרמטר. |
| הוספה | יצירת משאב באוסף. | POST ב-URI של אוסף. |
| מחיקה | מוחק משאב. | DELETE ב-URI של משאב. |
| תיקון | מעדכנים משאב באמצעות סמנטיקה של תיקונים. | PATCH ב-URI של משאב. |
| עדכון | עדכון משאב. | PUT ב-URI של משאב. |
בטבלה הבאה אפשר לראות אילו methods נתמכות בכל סוג משאב. כל פעולות list ו-get בבלוגים פרטיים מחייבות אימות.
Resource Type |
שיטות נתמכות |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| list | get (הורדה) | getByUrl | getByPath | listByUser | חיפוש | insert | מחיקה | patch | עדכון | |
| בלוגים | no | כן | כן | no | כן | no | no | no | no | no |
| פוסטים | כן | כן | no | כן | no | כן | כן | כן | כן | כן |
| תגובות | כן | כן | no | no | no | no | no | no | no | no |
| דפים | כן | כן | no | no | no | no | no | no | no | no |
| משתמשים | no | כן | no | no | no | no | no | no | no | 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 ב-API של Blogger
הפעולות הנתמכות ב-Blogger ממופות ישירות לפעלים מסוג REST HTTP, כפי שמתואר בפעולות API של Blogger.
הפורמט הספציפי למזהי URI של Blogger API הם:
https://www.googleapis.com/blogger/v3/users/userId https://www.googleapis.com/blogger/v3/users/self https://www.googleapis.com/blogger/v3/users/userId/blogs https://www.googleapis.com/blogger/v3/users/self/blogs https://www.googleapis.com/blogger/v3/blogs/blogId https://www.googleapis.com/blogger/v3/blogs/byurl https://www.googleapis.com/blogger/v3/blogs/blogId/posts https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId https://www.googleapis.com/blogger/v3/blogs/blogId/pages https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId
ההסבר המלא על מזהי ה-URI בשימוש והתוצאות של כל פעולה נתמכת ב-API מופיע בחומר העזר בנושא API של Blogger.
דוגמאות
הצגת רשימה של הבלוגים שלמשתמש המאומת יש הרשאות גישה אליהם:
GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY
הפוסטים בבלוג code.blogger.com, שמזהה הבלוג 3213900:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
REST מ-JavaScript
אפשר להפעיל את Blogger API מ-JavaScript באמצעות
פרמטר השאילתה callback ולספק פונקציית קריאה חוזרת.
כשהדפדפן טוען את הסקריפט, פונקציית הקריאה החוזרת מופעלת והתשובה מסופקת לפונקציית הקריאה החוזרת. הגישה הזו מאפשרת לכתוב אפליקציות עשירות שמציגות נתונים של Blogger בלי צורך בקוד בצד השרת.
הדוגמה הבאה מאחזרת פוסט מהבלוג code.blogger.com, אחרי שמחליפים את YOUR-API-KEY במפתח ה-API שלכם.
<html>
<head>
<title>Blogger 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/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
</body>
</html>
פורמט נתונים
JSON
JSON (JavaScript Object Notation) הוא פורמט נתונים נפוץ בלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף: json.org.