תחילת העבודה

מסמך זה מפרט את הידע ברקע שדרוש לכם כדי להשתמש ב-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. יש להתייחס תמיד למדפי ספרים בהקשר של ספרייה של משתמש מסוים. מדפי ספרים יכולים להכיל אפס כרכים או יותר.

Google מספקת קבוצה של מדפי ספרים מוגדרים מראש לכל משתמש:

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

מדפי ספרים לדוגמה:

  • "מועדפים"
    • "הארי פוטר"
  • "ספרי ה-eBook שלי"
    • "החלפה"
    • "דמדומים"
    • "הילדה עם קעקוע הדרקון"

פעולות ב-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.