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

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

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

קבל חשבון Google

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

היכרות עם Blogger

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

מידע על אישור בקשות וזיהוי האפליקציה

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

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

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

מידע כללי על Blogger API

מושגים ב-Blogger

הפלטפורמה של Blogger מבוססת על חמישה מושגים בסיסיים:

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

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

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

משאב הבלוגים: מייצג בלוג.
משאב posts: מייצג פוסט. כל משאב posts הוא צאצא של משאב blogs.
משאב התגובות: מייצג תגובה לפוסט ספציפי. כל משאב תגובות הוא צאצא של משאב הפוסטים.
משאב Pages: מייצג דף סטטי. כל משאב Pages הוא צאצא של משאב Blogs.
משאב המשתמשים: מייצג משתמש לא אנונימי. התג הזה משמש לזיהוי המחבר של דף, פוסט או תגובה.

למשאב הבלוגים יש שני סוגים של משאבי צאצא: דפים ופוסטים.
יכול להיות שלמשאב posts יהיו צאצאים מסוג משאב comments. — סקירה כללית על הקשרים בין המשאבים

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

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

פעולות ב-Blogger API

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

פעולה	תיאור	מיפויים של REST HTTP
list	רשימה של כל המשאבים בקולקציה.	‫`GET` ב-URI של אוסף.
get	קבלת משאב ספציפי.	‫`GET` במזהה URI של משאב.
getByUrl	מאחזר משאב לפי כתובת URL.	‫`GET` עם כתובת ה-URL שמועברת כפרמטר.
getByPath	מאחזר משאב לפי הנתיב שלו.	‫`GET` כשהנתיב מועבר כפרמטר.
listByUser	רשימת משאבים בבעלות משתמש.	`GET` באוסף שנמצא בבעלות המשתמש.
search	חיפוש משאבים על סמך פרמטר שאילתה.	‫`GET` בכתובת URL של חיפוש, כשהשאילתה מועברת כפרמטר.
הוספה	יוצרים משאב באוסף.	‫`POST` ב-URI של אוסף.
מחיקה	מחיקת משאב.	‫`DELETE` במזהה URI של משאב.
patch	עדכון משאב באמצעות סמנטיקה של תיקון.	‫`PATCH` במזהה URI של משאב.
עדכון	עדכון משאב.	‫`PUT` במזהה URI של משאב.

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

Resource Type	אמצעי תשלום נתמכים
	list	קבלת	getByUrl	getByPath	listByUser	חיפוש	הוספה	מחיקה	patch	עדכון
בלוגים	לא	כן	כן	לא	כן	לא	לא	לא	לא	לא
פוסטים	כן	כן	לא	כן	לא	כן	כן	כן	כן	כן
תגובות	כן	כן	לא	לא	לא	לא	לא	לא	לא	לא
דפים	כן	כן	לא	לא	לא	לא	לא	לא	לא	לא
משתמשים	לא	כן	לא	לא	לא	לא	לא	לא	לא	לא

סגנונות של מודעות עם קריאה לפעולה

יש כמה דרכים להפעיל את ה-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

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

אלה הם הפורמטים שספציפיים למזהי 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 מסוכם במסמך Blogger API Reference.

דוגמאות

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

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.

Blogger API: תחילת העבודה קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.