מסמך זה מפרט את הידע ברקע שדרוש לכם כדי להשתמש ב-Google Books API.
מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיכולות לקיים אינטראקציה עם Google Books API. ל-Google Books יש חזון להפוך את הספרים בעולם לדיגיטליים. אפשר להשתמש ב-Google Books API כדי לחפש תוכן, לארגן את הספרייה האישית של משתמש מאומת ולשנות אותה גם כן.
לפני שמתחילים
יצירת חשבון Google
צריך חשבון Google למטרות בדיקה. אם כבר יש לכם חשבון בדיקה, הכול מוכן. אפשר להיכנס לממשק המשתמש של Google Books כדי להגדיר, לערוך או להציג את נתוני הבדיקה.
היכרות עם Books
אם אינכם מכירים את המושגים של Google Books, כדאי לקרוא את המסמך הזה ולהתנסות בו באמצעות ממשק המשתמש לפני הקוד. המסמך הזה מבוסס על ההנחה שאתם מכירים מושגים של תכנות אתרים ופורמטים של נתוני אינטרנט.
מידע נוסף על הרשאת בקשות וזיהוי הבקשה שלך
כשהאפליקציה שלכם מעבירה בקשה לנתונים פרטיים, הבקשה חייבת להיות מאושרת על ידי משתמש מאומת שיש לו גישה לנתונים האלה.
באופן ספציפי, כל הפעולות בקטע 'הספרייה שלי' ב-Google Books API נחשבות כפרטיות ומחייבות אימות והרשאה. בנוסף, כל פעולה שמשנה את נתוני Google Books יכולה להתבצע רק על ידי המשתמש שהוא הבעלים של נתונים אלה.
כשהאפליקציה מעבירה בקשה לנתונים ציבוריים אין צורך לקבל הרשאה לכך, אבל יש לצרף לבקשה מזהה כלשהו כמו מפתח API.
למידע על מתן הרשאה לשימוש במפתחות API ועל השימוש במפתחות ה-API, יש לעיין בקטע אישור בקשות וזיהוי האפליקציה שלך במסמך 'שימוש ב-API'.
רקע של Books API
קונספטים של ספרים
Google Books בנוי על ארבעה עקרונות בסיסיים:
- כרך: כרך מייצג את הנתונים ש-Google Books מארח לגבי ספר או כתב עת. זהו המשאב העיקרי ב-Books API. כל שאר המשאבים בממשק ה-API הזה מכילים נפח, או מוסיפים לו הערות.
- מדף: מדף ספרים הוא אוסף של כרכים. ב-Google Books
יש קבוצה של מדפי ספרים מוגדרים מראש לכל משתמש, שחלק מהם מנוהלים באופן מלא על-ידי המשתמש, שחלק מהם ממולאים באופן אוטומטי על סמך פעילות המשתמש, וחלקם משולבים. משתמשים יכולים ליצור,
לשנות או למחוק מדפי ספרים אחרים, שתמיד מלאים בכרכים
באופן ידני. המשתמשים יכולים להגדיר מדפי ספרים כפרטיים או כציבוריים.
הערה: יצירה ומחיקה של מדפי ספרים, כמו גם שינוי הגדרות הפרטיות במדפים, ניתנים כרגע רק דרך האתר Google Books.
- בדיקה: בדיקה של עוצמת הקול היא שילוב של דירוג כוכבים ו/או טקסט. משתמש יכול לשלוח ביקורת אחת לכל כרך. הביקורות זמינות גם ממקורות חיצוניים ומיוחסות להן לפי הצורך.
- מיקום קריאה: מיקום קריאה מציין את מיקום הקריאה האחרון בכרך עבור משתמש. למשתמש יכול להיות רק מיקום קריאה אחד לכל כרך. אם המשתמש עוד לא פתח את הכרך הזה, מיקום הקריאה לא קיים. לפי מיקום הקריאה יכול להיות מידע מפורט על המיקום, עד להחלטה של מילה. המידע הזה תמיד פרטי למשתמש.
מודל נתונים של Books API
משאב הוא ישות נתונים נפרדת בעלת מזהה ייחודי. ה-API של Google Books פועל בשני סוגי משאבים, בהתאם לקונספטים שתוארו למעלה:
- משאב נפח: מייצג נפח.
- משאב מדף: מייצג מדף יחיד עבור משתמש ספציפי.
מודל הנתונים של Books API מבוסס על קבוצות משאבים, שנקראות אוספים:
- איסוף נפח אחסון
- אוסף הכרכים הוא אוסף של כל מקורות המידע לגבי נפח אחסון שמנוהלים על ידי Google Books.
לכן לא ניתן לפרט את כל משאבי עוצמת הקול, אבל אפשר לפרט את כל כרכים שתואמים לקבוצה של מונחי חיפוש.
- אוסף מדפי ספרים
- אוסף מדפי ספרים מורכב מכל המשאבים למדף ספרים שמנוהלים על ידי Google Books. יש להתייחס תמיד למדפי ספרים בהקשר של ספרייה של משתמש מסוים. מדפי ספרים יכולים להכיל אפס כרכים או יותר.
- מועדפים: מדף ספרים ניתן לשינוי.
- נרכש: מאוכלס בנפחים שהמשתמש רכש. המשתמש לא יכול להוסיף או להסיר נפחים באופן ידני.
- לקריאה: מדף ספרים ניתן לשינוי.
- לקריאה: מדף ספרים ניתן לשינוי.
- כדאי לקרוא: מדף ספרים ניתן לשינוי.
- נבדק: שדה זה מאוכלס בנפחים שהמשתמש בחן. המשתמש לא יכול להוסיף או להסיר נפחים באופן ידני.
- נצפו לאחרונה: מאוכלס בנפחים שהמשתמש פתח לאחרונה בקורא אינטרנט. המשתמש לא יכול להוסיף כרכים באופן ידני.
- הספרים הדיגיטליים שלי: מדף ספרים משתנה. ספרים שנרכשו מתווספים באופן אוטומטי, אבל ניתן להסיר אותם באופן ידני.
- ספרים עבורך: מאוכלסים בהמלצות מותאמות אישית לכרכים. אם אין המלצות למשתמש, המדף הזה לא יהיה קיים.
- "מועדפים"
- "הארי פוטר"
- "ספרי ה-eBook שלי"
- "החלפה"
- "דמדומים"
- "הילדה עם קעקוע הדרקון"
Google מספקת קבוצה של מדפי ספרים מוגדרים מראש לכל משתמש:
מדפי ספרים לדוגמה:
פעולות ב-Books API
תוכלו להפעיל חמש שיטות שונות באוספים ובמשאבים ב-Books API, כפי שמתואר בטבלה הבאה.
פעולה | תיאור | REST מיפויי HTTP |
---|---|---|
list | רשימה של קבוצת משנה ספציפית של משאבים בתוך אוסף. | GET ב-URI של אוסף. |
הוספה | הוספת משאב חדש לאוסף (יצירת משאב חדש). | POST ב-URI של אוסף, שבו מעבירים נתונים למשאב חדש. |
הורדה | מקבלת משאב ספציפי. | GET ב-URI של משאבים. |
עדכון | עדכון משאב ספציפי. | PUT ב-URI של המשאב, שאליו מעבירים את הנתונים של המשאב המעודכן. |
מחיקה | מחיקת משאב ספציפי. | DELETE ב-URI של המשאב, שבו מעבירים נתונים למשאב שרוצים למחוק. |
בטבלה הבאה מופיעות הפעולות הנתמכות בסוגי המשאבים השונים. פעולות שחלות על הנתונים הפרטיים של המשתמש נקראות 'הספרייה שלי', וכולן דורשות אימות.
Resource Type |
פעולות נתמכות |
||||
---|---|---|---|---|---|
רשימה | הוספה | הורדה | עדכון | מחיקה | |
עוצמות קול | כן* | כן | |||
מדפים | כן* | כן, אומת | כן* | כן, אומת | כן, אומת |
מיקומי קריאה | כן, אומת | כן, אומת | כן, אומת | כן, אומת |
*אפשר להפעיל את שתי הגרסאות המאומתות וגם את הגרסאות הלא מאומתות של הפעולות האלה, שבהן הבקשות הלא מאומתות פועלות על נתוני "הספרייה שלי" הפרטיים של המשתמש, ובקשות לא מאומתות פועלות רק על נתונים ציבוריים.
סגנונות של שיחות
יש כמה דרכים להפעיל API:
- שימוש ישיר ב-REST
- שימוש ב-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 ב-Books API
הפעולות הנתמכות ב-Books תואמות לפעלים של HTTP מסוג REST, כפי שמתואר בפעולות 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.
חיפוש שמיכות טלאים:
GET https://www.googleapis.com/books/v1/volumes?q=quilting
למידע על עוצמת הקול s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST מ-JavaScript
אפשר להפעיל את ה-API של Books באמצעות REST מ-JavaScript (שנקרא גם JSON-P), באמצעות פרמטר השאילתה callback
ופונקציית קריאה חוזרת. כך תוכלו לכתוב אפליקציות עשירות שמציגות נתוני ספרים בלי לכתוב קוד בצד השרת.
הערה: אפשר לקרוא לשיטות אימות על ידי העברה של אסימון OAuth 2.0 באמצעות הפרמטר access_token
. כדי לקבל אסימון OAuth 2.0 לשימוש ב-JavaScript, יש לפעול לפי ההוראות במאמר OAuth 2.0 לאפליקציות אינטרנט בצד הלקוח. בכרטיסייה 'גישה לממשק API' של מסוף ה-API, הקפד להגדיר Client ID לאפליקציות אינטרנט ולהשתמש בפרטי הכניסה OAuth 2.0 האלה כדי לקבל את האסימון.
הדוגמה הבאה משתמשת בגישה זו כדי להציג תוצאות חיפוש עבור "Pander":
<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.