במסמך הזה מפורט מידע בסיסי שצריך לדעת כדי להשתמש ב-Google Books API.
מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיכולות לקיים אינטראקציה עם Google Books API. החזון של Google Books הוא להפוך את הספרים בעולם לדיגיטליים. אתם יכולים להשתמש ב-Google Books API כדי לחפש תוכן, לארגן את הספרייה האישית של משתמש מאומת ולשנות אותה.
לפני שמתחילים
איך מקבלים חשבון Google
לצורך בדיקות, צריך חשבון Google. אם כבר יש לכם חשבון בדיקה, אתם מוכנים. אתם יכולים להיכנס לממשק המשתמש של Google Books כדי להגדיר, לערוך או לראות את נתוני הבדיקה.
היכרות עם Google Books
אם אתם לא מכירים את המושגים של Google Books, כדאי לקרוא את המסמך הזה ולנסות את ממשק המשתמש לפני שתתחילו לתכנת. ההנחה במאמר הזה היא שאתם מכירים מושגים בתכנות לאינטרנט ופורמטים של נתונים באינטרנט.
מידע על אישור בקשות וזיהוי האפליקציה
כשהאפליקציה שלכם מעבירה בקשה לנתונים פרטיים, הבקשה חייבת להיות מאושרת על ידי משתמש מאומת שיש לו גישה לנתונים האלה.
בפרט, כל הפעולות בקטע 'הספרייה שלי' ב-Google Books API נחשבות פרטיות ודורשות אימות והרשאה. בנוסף, רק המשתמש שבבעלותו הנתונים יכול לבצע פעולות שמשנות את הנתונים ב-Google Books.
כשהאפליקציה מעבירה בקשה לנתונים ציבוריים אין צורך לקבל הרשאה לכך, אבל יש לצרף לבקשה מזהה כלשהו כמו מפתח API.
מידע על הרשאת בקשות ושימוש במפתחות API מופיע במאמר הרשאת בקשות וזיהוי האפליקציה בתיעוד בנושא שימוש ב-API.
רקע על Books API
מושגים שקשורים ל-Books
Google Books מבוסס על ארבעה מושגים בסיסיים:
- כרך: כרך מייצג את הנתונים שמתארחים ב-Google Books לגבי ספר או מגזין. זהו המשאב העיקרי ב-Books API. כל שאר המשאבים ב-API הזה מכילים נפח או מוסיפים לו הערות.
- מדף ספרים: מדף ספרים הוא אוסף של כרכים. Google Books
מספקת לכל משתמש קבוצה של מדפי ספרים מוגדרים מראש. חלק מהמדפים מנוהלים באופן מלא על ידי המשתמש, חלקם מתמלאים אוטומטית על סמך פעילות המשתמש וחלקם הם שילוב של השניים. המשתמשים יכולים ליצור, לשנות או למחוק מדפי ספרים אחרים, שתמיד מלאים בכרכים באופן ידני. המשתמש יכול להגדיר את מדפי הספרים כפרטיים או כציבוריים.
הערה: בשלב הזה, אפשר ליצור ולמחוק מדפים, וגם לשנות את הגדרות הפרטיות שלהם, רק דרך האתר של Google Books.
- ביקורת: ביקורת על ספר היא שילוב של דירוג כוכבים ו/או טקסט. כל משתמש יכול לשלוח ביקורת אחת על כל ספר. ביקורות זמינות גם ממקורות חיצוניים, והן משויכות למקורות המתאימים.
- מיקום קריאה: מיקום קריאה מציין את המיקום האחרון שנקרא בכרך על ידי משתמש. לכל משתמש יכולה להיות רק עמדת קריאה אחת לכל כרך. אם המשתמש לא פתח את הכרך הזה בעבר, מיקום הקריאה לא קיים. מיקום הקריאה יכול לשמור מידע מפורט על המיקום, עד לרמת המילה. המידע הזה תמיד פרטי למשתמש.
מודל הנתונים של Books API
משאב הוא ישות נתונים נפרדת עם מזהה ייחודי. ממשק Books API פועל על שני סוגים של משאבים, על סמך המושגים שמתוארים למעלה:
- משאב נפח: מייצג נפח.
- משאב מדף הספרים: מייצג מדף ספרים יחיד של משתמש מסוים.
מודל הנתונים של Books API מבוסס על קבוצות של משאבים שנקראות אוספים:
- איסוף נפח
- אוסף הכרכים הוא אוסף של כל משאבי הכרכים שמנוהלים על ידי Google ספרים.
לכן, אי אפשר לפרט את כל משאבי נפח האחסון, אבל אפשר לפרט את כל נפחי האחסון שתואמים לקבוצה של מונחי חיפוש.
- אוסף מדף ספרים
- אוסף מדף ספרים כולל את כל משאבי מדף הספרים שמנוהלים על ידי Google Books. תמיד צריך להתייחס למדפים בהקשר של הספרייה של משתמש ספציפי. מדפים יכולים להכיל אפס או יותר כרכים.
- מועדפים: מדף ספרים שניתן לערוך.
- נרכש: מאוכלס בנפחים שהמשתמש רכש. המשתמש לא יכול להוסיף או להסיר נפחים באופן ידני.
- לקריאה: מדף ספרים שניתן לשינוי.
- קריאה עכשיו: מדף ספרים שניתן לשינוי.
- קראתי: מדף ספרים שניתן לעריכה.
- נבדקו: מכיל את הכרכים שהמשתמש בדק. המשתמש לא יכול להוסיף או להסיר נפחים באופן ידני.
- פריטים שנצפו לאחרונה: מכיל את הכרכים שהמשתמש פתח לאחרונה בקורא אינטרנט. המשתמש לא יכול להוסיף נפחים באופן ידני.
- הספרים הדיגיטליים שלי: מדף ספרים שניתן לשינוי. ספרים שנרכשו מתווספים אוטומטית, אבל אפשר להסיר אותם ידנית.
- ספרים מומלצים בשבילך: המלצות מותאמות אישית לספרים. אם אין לנו המלצות למשתמש, מדף הספרים הזה לא קיים.
- 'מועדפים'
- "Harry Potter"
- "My eBooks" (הספרים הדיגיטליים שלי)
- "Switch" (החלפה)
- "Twilight"
- "נערה עם קעקוע דרקון"
Google מספקת לכל משתמש קבוצה של מדפי ספרים מוגדרים מראש:
מדפים לדוגמה:
פעולות של Books API
בטבלה הבאה מפורטות חמש שיטות שונות שאפשר להפעיל באוספים ובמשאבים ב-Books API.
| פעולה | תיאור | מיפויים של REST HTTP |
|---|---|---|
| list | מציג רשימה של קבוצת משנה ספציפית של משאבים באוסף. | GET ב-URI של אוסף. |
| הוספה | הוספת משאב חדש לאוסף (יצירת משאב חדש). | POST ב-URI של אוסף, שבו מעבירים נתונים למשאב חדש. |
| get | קבלת משאב ספציפי. | GET ב-URI של המשאב. |
| עדכון | עדכון של משאב ספציפי. | PUT ב-URI של המשאב, שבו מעבירים נתונים למשאב המעודכן. |
| מחיקה | מחיקת משאב ספציפי. | DELETE ב-URI של המשאב, שבו מעבירים נתונים למשאב שרוצים למחוק. |
בטבלה הבאה מפורטות הפעולות שנתמכות בסוגים השונים של משאבים. פעולות שחלות על נתונים פרטיים של משתמש נקראות פעולות של 'הספרייה שלי', וכולן דורשות אימות.
Resource Type |
פעולות נתמכות |
||||
|---|---|---|---|---|---|
| list | הוספה | קבלת | עדכון | מחיקה | |
| כרכים | כן* | כן | |||
| מדפי ספרים | כן* | כן, AUTHENTICATED | כן* | כן, AUTHENTICATED | כן, AUTHENTICATED |
| מיקומי קריאה | כן, AUTHENTICATED | כן, AUTHENTICATED | כן, AUTHENTICATED | כן, AUTHENTICATED | |
*יש גרסאות מאומתות ולא מאומתות של הפעולות האלה. הבקשות המאומתות פועלות על הנתונים הפרטיים של המשתמש בספרייה שלו, והבקשות הלא מאומתות פועלות רק על נתונים ציבוריים.
סגנונות של מודעות עם קריאה לפעולה
יש כמה דרכים להפעיל את ה-API:
- שימוש ישירות ב-REST
- שימוש ב-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 ב-Books API
הפעולות הנתמכות ב-Books ממופות ישירות לפעלים מסוג REST HTTP, כמו שמתואר בפעולות של Books API.
אלה הם הפורמטים שספציפיים למזהי URI של Books API:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parametersכאשר resourceID הוא המזהה של משאב של ספר או של מדף ספרים, ו-parameters הם פרמטרים שאפשר להחיל על השאילתה. פרטים נוספים זמינים במאמר בנושא פרמטרים של שאילתות.
הפורמט של תוספי הנתיב resourceID מאפשר לזהות את המשאב שבו אתם פועלים כרגע, למשל:
https://www.googleapis.com/books/v1/volumes https://www.googleapis.com/books/v1/volumes/volumeId https://www.googleapis.com/books/v1/mylibrary/bookshelves https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes ...
שימו לב שפעולות עם mylibrary ב-URI חלות רק על נתונים פרטיים בספרייה של המשתמש שאומת כרגע. הקבוצה המלאה של מזהי URI שמשמשים לכל פעולה נתמכת ב-API מסוכמת במסמך Books API Reference.
הנה כמה דוגמאות שממחישות איך זה עובד ב-Books API.
מבצעים חיפוש של quilting (תפירת טלאים):
GET https://www.googleapis.com/books/v1/volumes?q=quilting
כדי לקבל מידע על אמצעי האחסון s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST מ-JavaScript
אפשר להפעיל את Books API באמצעות REST מ-JavaScript (שנקרא גם JSON-P), באמצעות פרמטר השאילתה callback ופונקציית קריאה חוזרת. כך תוכלו לכתוב אפליקציות מפותחות שמציגות נתונים מ-Books בלי לכתוב קוד בצד השרת.
הערה: אפשר לקרוא לשיטות מאומתות על ידי העברת אסימון OAuth 2.0 באמצעות הפרמטר access_token. כדי לקבל אסימון OAuth 2.0 לשימוש ב-JavaScript, צריך לפעול לפי ההוראות שמתוארות במאמר OAuth 2.0 לאפליקציות אינטרנט בצד הלקוח. בכרטיסייה 'גישת API' ב-APIs Console, צריך להגדיר מזהה לקוח לאפליקציות אינטרנט ולהשתמש בפרטי הכניסה האלה של OAuth 2.0 כשמקבלים את האסימון.
בדוגמה הבאה מוצגות תוצאות חיפוש של 'הארי פוטר' באמצעות הגישה הזו:
<html> <head> <title>Books API Example</title> </head> <body> <div id="content"></div> <script> function handleResponse(response) { for (var i = 0; i < response.items.length; i++) { var item = response.items[i]; // in production code, item.text should have the HTML entities escaped. document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title; } } </script> <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script> </body> </html>
פורמט נתונים
JSON
JSON (JavaScript Object Notation) הוא פורמט נתונים נפוץ בלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף היכנסו לאתר של json.org.