תחילת העבודה

במסמך הזה מפורט מידע הרקע שדרוש לכם כדי להשתמש ב-Google Books API.

1. מבוא
2. לפני שמתחילים
   1. יצירת חשבון Google
   2. לעיון בספרים
   3. מידע על אישור בקשות וזיהוי הבקשה
3. רקע של Books API
   1. מושגים על ספרים
   2. מודל הנתונים של Books API
   3. פעולות ב-Books API
4. סגנון השיחה
   1. REST
5. פורמט נתונים
   1. JSON

מבוא

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

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

פתיחת חשבון Google

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

היכרות עם ספרים

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

מידע נוסף על אישור בקשות וזיהוי הבקשה

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

באופן ספציפי, כל הפעולות בקטע 'הספרייה שלי' ב-Google Books API נחשבות כפרטיות ומחייבות אימות והרשאה. בנוסף, כל פעולה שמשנה את הנתונים ב-Google Books יכולה להתבצע רק על ידי המשתמש שהוא הבעלים של הנתונים האלה.

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

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

רקע של Books API

מונחים על ספרים

Google ספרים מבוסס על ארבעה מושגים בסיסיים:

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

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

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

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

משאב הוא ישות נתונים בודדת עם מזהה ייחודי. ה-Books API פועל על שני סוגי משאבים, בהתאם למושגים שמתוארים למעלה:

• משאב נפח: מייצג נפח אחסון.
• משאב של מדף ספרים: מייצג מדף ספרים יחיד של משתמש מסוים.

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

איסוף כרך

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

אוסף מדפי ספרים

אוסף ספרים כולל את כל המשאבים של המדף שמנוהלים על ידי Google Books. תמיד צריך להפנות למדפי ספרים בהקשר של הספרייה של משתמש ספציפי. מדפי ספרים יכולים להכיל אפס כרכים או יותר.

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

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

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

• 'מועדפים'
• "הארי פוטר"
• 'הספרים הדיגיטליים שלי'
• "Switch"
• "דמדומים"
• "The Girl with the Dragon Tattoo"

פעולות ב-Book API

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

פעולה	תיאור	מיפויים של HTTP ב-REST
list	בתיבת הדו-שיח הזו מפורטים קבוצת משנה ספציפית של משאבים בתוך אוסף.	GET ב-URI של אוסף.
הוספה	הוספת משאב חדש לאוסף (יצירת משאב חדש).	POST ב-URI של אוסף, שבו מעבירים נתונים למשאב חדש.
הורדה	קבלת משאב ספציפי.	GET ב-URI של המשאב.
עדכון	מעדכן משאב ספציפי.	PUT ב-URI של המשאב, שבו מעבירים את הנתונים למשאב המעודכן.
מחיקה	המחיקה של משאב ספציפי.	DELETE ב-URI של המשאב: מעבירים את הנתונים כדי שהמשאב יימחק.

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

Resource Type	פעולות נתמכות
	list	insert	get (הורדה)	עדכון	מחיקה
נפחי אחסון	כן*		כן
מדפי ספרים	כן*	כן, מאומת	כן*	כן, מאומת	כן, מאומת
מיקומי קריאה		כן, מאומת	כן, מאומת	כן, מאומת	כן, מאומת

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

סגנונות שיחה

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

בצעו חיפוש של שמיכות טלאים:

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

הערה: אתם יכולים להפעיל שיטות מאומתות על ידי העברת אסימון OAuth 2.0 באמצעות הפרמטר access_token. כדי לקבל אסימון OAuth 2.0 לשימוש עם JavaScript, פועלים לפי ההוראות שמפורטות במאמר OAuth 2.0 לאפליקציות אינטרנט בצד הלקוח. בכרטיסייה 'API Access' במסוף API, חשוב להגדיר Client-ID לאפליקציות אינטרנט ולהשתמש בפרטי הכניסה האלה של 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.