במאמר הזה נסביר איך מתחילים להשתמש ב-Blogger API.
לפני שמתחילים
קבל חשבון Google
מוודאים שיש לכם חשבון Google מוגדר. כדי להגן על עצמך מפני אובדן נתונים מקרי, מומלץ להשתמש בחשבון Google נפרד למטרות פיתוח ובדיקה. אם כבר יש לכם חשבון בדיקה, אז הכול מוכן. תוכלו להיכנס לממשק המשתמש של Blogger כדי להגדיר, לערוך או להציג את נתוני הבדיקה.
היכרות עם Blogger
אם אינכם מכירים את המושגים של Blogger, מומלץ לקרוא את המסמך הזה ולהתנסות בממשק המשתמש לפני שמתחילים לקוד. המסמך הזה יוצא מנקודת הנחה שיש לך היכרות עם Blogger, עם מושגים של תכנות אינטרנט ועם פורמטים של נתוני אינטרנט.
מידע נוסף על אישור בקשות וזיהוי הבקשה
כאשר הבקשה שלכם מבקשת נתונים פרטיים, רק משתמשים מאומתים שיש להם גישה לנתונים האלה צריכים לקבל הרשאה.
בעת הגשת בקשה לנתונים ציבוריים, אין צורך בהרשאה עבור הבקשה, אבל יש לצרף אליהם מזהה, כמו מפתח API.
למידע על אישור בקשות ושימוש במפתחות API, עיינו במאמר אישור בקשות וזיהוי האפליקציה שלכם במסמך 'שימוש ב-API'.
רקע של Blogger API
הקונספטים של Blogger
Blogger מבוסס על חמישה עקרונות בסיסיים:
- בלוגים: הקונספט הבסיסי של ה-API. בבלוג יש פוסטים ודפים. זהו המאגר של המטא-נתונים של הבלוג, כמו שם הבלוג והתיאור.
- פוסטים: פוסט בבלוג הוא הפריט שניתן לפרסם על ידי מחבר הבלוג. המידע צריך להיות עדכני ולשקף את מה שהמחברים רוצים לפרסם בעולם כיום. ברור לנו שעם הזמן, הבלוג מפרסם תוכן והופך לגיל פחות יחסי.
- תגובות: תגובה היא המקום שבו אנשים מלבד המחבר שכתבו את הפוסט מגיבים למה שהמחבר כתב. החל מלבנים ועד זרי פרחים.
- דפים: דף הוא מקום לתוכן סטטי, כמו מידע ביוגרפי, או דרכים ליצירת קשר עם משתמש. זהו מידע בדרך כלל שלא משתנה לעיתים קרובות.
- משתמשים: משתמש הוא אינטראקציה עם Blogger, הוא יכול להיות מחבר, מנהל מערכת או רק קורא. עבור בלוגים ציבוריים, הקוראים עשויים להיות אנונימיים, אבל בבלוגים פרטיים הקורא צריך לזהות אותם.
מודל הנתונים ב-Blogger API
משאב הוא ישות נתונים נפרדת עם מזהה ייחודי. ה-Blogger API API פועל בחמישה סוגים של משאבים:
- משאב בלוגים: מייצג בלוג.
- משאב פוסטים: מייצג פוסט. כל משאב של פוסט הוא צאצא של משאב בבלוגים.
- משאב תגובות: מייצג תגובה בפוסט ספציפי. כל משאב של תגובות הוא צאצא של משאב פוסטים.
- משאב דפים: מייצג דף סטטי, כל משאב של דפים הוא צאצא של משאב בלוגים.
- משאב משתמשים: מייצג משתמש שאינו אנונימי. משמש לזיהוי המחבר של דף, פוסט או תגובה.
מודל הנתונים של Blogger API מבוסס על קבוצות של משאבים, הנקראים אוספים:
- אוסף בלוגים
- אוסף <span="apicollection">blogs מורכב מכל הבלוגים שאליהם יש למשתמש הרשאות גישה. אפשר לציין בלוגים לפי משתמש או לאחזר בלוג יחיד לפי מזהה.</span="apicollection">
- איסוף פוסטים
- אוסף פוסטים מכיל את כל משאבי הפוסטים בתוך משאב ספציפי של בלוגים.
- איסוף תגובות
- אוסף של תגובות מכיל את כל מקורות המידע על תגובות במשאב ספציפי של פוסטים.
- איסוף דפים
- אוסף דפים מכיל את כל משאבי הדפים במשאב ספציפי של בלוגים.
- אוסף משתמשים
- אוסף משתמשים מכיל את כל
משאבי המשתמשים ב-Blogger, ולכן
לא ניתן לרשום אותם. משתמש יכול לאחזר את משאב המשתמש שלו (אבל אף אחד אחר) באמצעות המזהה, או באמצעות המזהה
self.
פעולות ב-Blogger API
ניתן להפעיל מספר שיטות שונות לגבי אוספים ומשאבים ב-Blogger API, כפי שמוסבר בטבלה הבאה.
| פעולה | תיאור | מיפויי HTTP ב-REST |
|---|---|---|
| list | רשימה של כל המשאבים בתוך אוסף. | GET ב-URI של אוסף. |
| הורדה | מקבלים משאב ספציפי. | GET ב-URI של משאב. |
| getByUrl | מקבלים משאב ומחפשים אותו לפי כתובת URL. | GET עם כתובת ה-URL שהועברה כפרמטר. |
| getByPath | מקבלים משאב על ידי חיפוש נתיב. | GET עם נתיב שמועבר כפרמטר. |
| listByUser | רשימה של משאבים בבעלות המשתמש. | GET באוסף בבעלות המשתמש. |
| search | חיפוש משאבים על סמך פרמטר של שאילתה. | GET בכתובת URL של חיפוש, כשהשאילתה מועברת כפרמטר. |
| insert | יצירת משאב באוסף. | POST ב-URI של אוסף. |
| מחיקה | מחיקת משאב. | DELETE ב-URI של משאב. |
| תיקון | עדכון משאב באמצעות הסמנטיקה של Patchic. | PATCH ב-URI של משאב. |
| עדכון | מעדכנים משאב. | PUT ב-URI של משאב. |
בטבלה הבאה אפשר לראות אילו שיטות נתמכות בכל סוג משאב. כל הפעולות של רשימות והורדה בבלוגים פרטיים מחייבות אימות.
Resource Type |
שיטות נתמכות |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| רשימה | קבלת | getByUrl | getByPath | listByUser | חיפוש | insert | מחיקה | תיקון | עדכון | |
| בלוגים | 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. בהקשר של ממשקי ה-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 API
הפעולות הנתמכות ב-Blogger ממופה ישירות לפעלים של HTTP ב-REST, כפי שמתואר בפעולות של Blogger API.
הפורמט הספציפי ל-URIs של 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 מסוכם במסמך Blogger API.
דוגמאות
רשימה של הבלוגים שלמשתמש המאומת יש גישה אליהם:
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
ניתן להפעיל את ה-API של Blogger מ-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.