שימוש ב-API

תוכן עניינים

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

מבוא

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

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

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

כל בקשה שהאפליקציה שולחת ל-Book API צריכה לזהות את האפליקציה ל-Google. יש שתי דרכים לזהות את האפליקציה שלכם: באמצעות אסימון OAuth 2.0 (שגם מאשר את הבקשה) ו/או שימוש במפתח ה-API של האפליקציה. כך קובעים באילו מהאפשרויות האלה להשתמש:

  • אם הבקשה מחייבת הרשאה (למשל, בקשה לקבלת מידע פרטי של אדם פרטי), היא חייבת לכלול בבקשה אסימון OAuth 2.0. האפליקציה יכולה גם לספק את מפתח ה-API, אבל היא לא חייבת.
  • אם הבקשה לא דורשת הרשאה (למשל, בקשה לנתונים ציבוריים), האפליקציה צריכה לספק את מפתח ה-API או אסימון OAuth 2.0, או את שניהם – בהתאם לאפשרות שהכי מתאימה לכם.

הסבר על פרוטוקולים של הרשאות

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

הרשאת בקשות עם פרוטוקול OAuth 2.0

בקשות ל-Book API עבור נתוני משתמש שאינם ציבוריים חייבות לקבל הרשאה על ידי משתמש מאומת.

הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:

  1. כשיוצרים את האפליקציה, רושמים אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
  2. מפעילים את Books API במסוף Google API. (אם ה-API לא מופיע ב-API Console, דלגו על השלב הזה).
  3. כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
  4. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  5. אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
  6. האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  7. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

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

אלו הם הפרטים של היקף OAuth 2.0 עבור Books API:

https://www.googleapis.com/auth/books

כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).

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

קבלת מפתח API ושימוש בו

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

כדי לקבל מפתח API:

  1. פותחים את הדף Credentials במסוף ה-API.
  2. ה-API הזה תומך בשני סוגים של פרטי כניסה. בוחרים את פרטי הכניסה שמתאימים לפרויקט:

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

      מידע נוסף זמין במסמכי התיעוד של OAuth 2.0.

    • מפתחות API: בקשה שלא מספקת אסימון OAuth 2.0 חייבת לשלוח מפתח API. המפתח מזהה את הפרויקט ומספק גישה ל-API, מכסות ודוחות.

      ה-API תומך בכמה סוגים של הגבלות על מפתחות API. אם מפתח ה-API שאתם צריכים עדיין לא קיים, תוכלו ליצור מפתח API במסוף בלחיצה על Create credentials > מפתח API. אפשר להגביל את המפתח לפני שמשתמשים בו בסביבת הייצור, על ידי לחיצה על Restrict key ובחירה באחת מההגבלות.

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

אחרי שיש לכם מפתח API, האפליקציה יכולה לצרף את פרמטר השאילתה key=yourAPIKey לכל כתובות ה-URL של הבקשות.

מפתח ה-API בטוח להטמעה בכתובות URL, אין צורך בקידוד שלו.

מזהים של Google Books

צריך לציין שדות מזהה עם קריאות מסוימות ל-method של API. ב-Google Books יש שלושה סוגי תעודות מזהות:

  • מזהי כרך – מחרוזות ייחודיות לכל כרך שמזוהה ב-Google Books. דוגמה למזהה כרך היא _LettPDhwR0C. כדי למצוא את מזהה הנפח, אפשר לשלוח בקשה להחזרת משאב של נפח אחסון באמצעות ה-API. אפשר למצוא אותו בשדה id.
  • מזהי מדף ספרים – ערכים מספריים המוענקים למדף ספרים בספרייה של משתמש. Google מספקת כמה מדפים מוגדרים מראש לכל משתמש עם המזהים הבאים:
    • מועדפים: 0
    • נרכש: 1
    • לקריאה: 2
    • לקריאה: 3
    • קריאה: 4
    • נבדקו: 5
    • נצפו לאחרונה: 6
    • הספרים הדיגיטליים שלי: 7
    • ספרים בשבילך: 8 אם אין לנו המלצות למשתמש, המדף הזה לא קיים.
    מזהים של מדפים בהתאמה אישית גדולים מ-1,000. מזהה מדף ספרים הוא ייחודי למשתמש נתון. כלומר, לשני משתמשים יכול להיות מדף ספרים עם אותו מזהה, שמפנה למדפי ספרים שונים. כדי להשתמש ב-API כדי לקבל את מזהה מדף הספרים, עליך לשלוח בקשה להחזרת משאב של מדף ספרים. המזהה הזה מופיע בשדה id.
  • מזהי משתמשים – ערכים מספריים ייחודיים שמוקצים לכל משתמש. הערכים האלה לא בהכרח זהים לערך המזהה שמשמש בשירותים אחרים של Google. בשלב זה, הדרך היחידה לאחזר את מזהה המשתמש היא לחלץ אותו מהקישור העצמי במשאב מדף ספרים שאוחזר באמצעות בקשה מאומתת. המשתמשים יכולים גם לקבל מזהה משתמש משלהם מאתר הספרים. משתמש לא יכול להשיג את מזהה המשתמש של משתמש אחר דרך ה-API או אתר הספרים. המשתמש האחר יצטרך לשתף את המידע הזה באופן מפורש, למשל באימייל.

התעודות המזהות באתר Google Books

המזהים שבהם אתם משתמשים ב-Book API הם אותם מזהים שמופיעים באתר Google Books.

  • מזהה כרך

    כשמציגים נפח מסוים באתר, אפשר למצוא את מזהה נפח האחסון בפרמטר id של כתובת ה-URL. לדוגמה: 

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • מזהה מדף ספרים

    כשמציגים מדף ספרים ספציפי באתר, אפשר למצוא את מזהה מדף הספרים בפרמטר as_coll של כתובת האתר. לדוגמה: 

    https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

  • מזהה משתמש

    כשמציגים את הספרייה באתר, אפשר למצוא את מזהה המשתמש בפרמטר uid של כתובת ה-URL. לדוגמה: 

    https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

הגדרת מיקום משתמש

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

עבודה עם נפחי אחסון

ביצוע חיפוש

אפשר לבצע חיפוש נפחי אחסון על ידי שליחת בקשת GET מסוג HTTP ל-URI הבא:

https://www.googleapis.com/books/v1/volumes?q=search+terms

הבקשה הזו מכילה פרמטר נדרש אחד:

  • q – חיפוש כרכים שמכילים את מחרוזת הטקסט הזו. יש מילות מפתח מיוחדות שאפשר לציין במונחי החיפוש בשדות מסוימים, כמו:
    • intitle: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו נמצא בכותרת.
    • inauthor: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו נמצא במחבר.
    • inpublisher: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו נמצא בבעל התוכן הדיגיטלי.
    • subject: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו מופיע ברשימת הקטגוריות של הנפח.
    • isbn: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא מספר ה-ISBN.
    • lccn: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא מספר הבקרה של ספריית הקונגרס.
    • oclc: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא המספר של Online Computer Library Center.

בקשה

הנה דוגמה לחיפוש של "Flowers for Algernon" של דניאל קיז: 

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

הערה: ביצוע חיפוש לא מחייב אימות, ולכן לא צריך לספק את כותרת ה-HTTP Authorization עם הבקשה GET. אבל אם השיחה תתבצע באמצעות אימות, כל נפח אחסון יכלול מידע ספציפי למשתמש, כמו סטטוס הרכישה.

תשובה

אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס HTTP 200 OK ועם תוצאות נפח האחסון:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

פרמטרים אופציונליים של שאילתות

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

הורדת הפורמט

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

הדוגמאות הבאות הן חיפוש של ספרים עם הורדת EPUB זמינה:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
סינון

אפשר להשתמש בפרמטר filter כדי להגביל עוד יותר את התוצאות שהוחזרו על ידי הגדרתו לאחד מהערכים הבאים:

  • partial - מחזירה תוצאות שבהן ניתן לראות תצוגה מקדימה של לפחות חלקים מהטקסט.
  • full - רק תוצאות שבהן כל הטקסט ניתן לצפייה.
  • free-ebooks - מחזירה רק תוצאות שאינן ספרים של Google Books בחינם.
  • paid-ebooks - מחזירה רק תוצאות שהן Google ספרים דיגיטליים עם מחיר.
  • ebooks - מוחזר רק תוצאות שהן ספרים של Google Books, בתשלום או בחינם. דוגמאות לספרים שאינם ספרים דיגיטליים: תוכן של מוציאים לאור שזמין בתצוגה מקדימה מוגבלת ולא למכירה, או כתבי עת.

הדוגמה הבאה מגבילה את תוצאות החיפוש לתוצאות החיפוש הזמינות כספרים דיגיטליים בחינם:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
חלוקה לדפים

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

  • startIndex – המיקום באוסף שממנו יתחיל. האינדקס של הפריט הראשון הוא 0.
  • maxResults – מספר התוצאות המקסימלי שיש להחזיר. ערך ברירת המחדל הוא 10. הערך המקסימלי המותר הוא 40.

אפשר להשתמש בפרמטר printType כדי להגביל את התוצאות שהוחזרו לסוג ספציפי של הדפסה או אתר חדשות, על ידי הגדרתו לאחד מהערכים הבאים:

  • all – ללא הגבלה לפי סוג ההדפסה (ברירת המחדל).
  • books - מחזיר רק תוצאות של ספרים.
  • magazines - הצגת תוצאות של כתבי עת.

הדוגמה הבאה מגבילה תוצאות חיפוש לכתבי עת:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
היטל

אפשר להשתמש בפרמטר projection עם אחד מהערכים הבאים כדי לציין קבוצה מוגדרת מראש של שדות נפח שיוחזר:

  • full - החזרת כל שדות עוצמת הקול.
  • lite - החזרת שדות מסוימים בלבד. אפשר לעיין בתיאורי השדות שמסומנים בכוכבית כפולה בחומר העזר בנושא נפח כדי לברר אילו שדות כלולים.

הדוגמה הבאה מחזירה תוצאות חיפוש עם מידע לגבי נפח מוגבל:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
מיון

כברירת מחדל, בקשת חיפוש נפחי חיפוש מחזירה maxResults תוצאות, כאשר maxResults הוא הפרמטר שמשתמשים בו בעימוד (למעלה), לפי סדר הרלוונטיות למונחי החיפוש.

אפשר לשנות את הסדר על ידי הגדרת הפרמטר orderBy לאחד מהערכים הבאים:

  • relevance - הצגת התוצאות לפי סדר הרלוונטיות של מונחי החיפוש (זו ברירת המחדל).
  • newest - החזרת התוצאות לפי סדר [מהחדשה לישנה] ועד האחרונה שפורסמה.

בדוגמה הבאה מוצגות תוצאות לפי תאריך הפרסום, מהחדש לישן:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

אחזור של נפח אחסון ספציפי

אפשר לאחזר מידע על נפח אחסון ספציפי על ידי שליחת בקשת GET מסוג HTTP ל-URI של משאב האחסון:

https://www.googleapis.com/books/v1/volumes/volumeId

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

בקשה

דוגמה לבקשת GET שמקבלת נפח אחסון יחיד:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

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

תשובה

אם הבקשה מצליחה, השרת ישיב עם קוד הסטטוס 200 OK של HTTP ועם משאב האחסון המבוקש:

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}
פרטי הגישה

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

פרמטרים אופציונליים של שאילתות

בנוסף לפרמטרים הרגילים של שאילתות, אפשר להשתמש בפרמטר השאילתה הבא לאחזור נפח אחסון ספציפי.

היטל

אפשר להשתמש בפרמטר projection עם אחד מהערכים הבאים כדי לציין קבוצה מוגדרת מראש של שדות נפח שיוחזר:

  • full - החזרת כל שדות עוצמת הקול.
  • lite - החזרת שדות מסוימים בלבד. אפשר לעיין בתיאורי השדות שמסומנים בכוכבית כפולה בחומר העזר בנושא נפח כדי לברר אילו שדות כלולים.

הדוגמה הבאה מחזירה מידע על נפח מוגבל של כרך יחיד:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

עבודה עם מדפי ספרים

אחזור רשימה של מדפי ספרים ציבוריים של משתמש

אפשר לאחזר רשימה של מדפי הספרים הציבוריים של המשתמש על ידי שליחת בקשת GET HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/users/userId/bookshelves

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

בקשה

לדוגמה:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

מכיוון שלא צריך לאמת את המשתמש כדי לאחזר מידע על מדפי ספרים ציבוריים, לא צריך לספק את כותרת ה-HTTP Authorization עם בקשת GET.

תשובה

אם הבקשה תתבצע בהצלחה, השרת ישיב עם קוד הסטטוס 200 OK של ה-HTTP ועם הרשימה של מדפי הספרים:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

פרמטרים אופציונליים של שאילתות

תוכלו להשתמש בפרמטרים רגילים של שאילתה כדי לאחזר את הרשימה של מדפי הספרים הציבוריים של המשתמש.

אחזור מדף ספרים ציבורי ספציפי

אפשר לאחזר מדף ספרים ציבורי ספציפי על ידי שליחת בקשת GET מסוג HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

מחליפים את הפרמטרים userId ו-shelf במזהים שמציינים את המשתמש ואת מדף הספרים שרוצים לאחזר. מידע נוסף זמין בקטע מזהים של Google Books.

בקשה

לדוגמה:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

מכיוון שלא צריך לאמת את המשתמש כדי לאחזר מידע על מדפי ספרים ציבוריים, לא צריך לספק את כותרת ה-HTTP Authorization עם בקשת GET.

תשובה

אם הבקשה מצליחה, השרת ישיב עם קוד הסטטוס 200 OK של ה-HTTP והמשאב של מדף הספרים:

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

פרמטרים אופציונליים של שאילתות

כשמאחזרים מדף ספרים ציבורי ספציפי, אפשר להשתמש בפרמטרים הרגילים של שאילתה.

אחזור רשימת כרכים של מדף ספרים ציבורי

אפשר לאחזר רשימה של כרכים במדף הספרים הציבורי של המשתמש על ידי שליחת בקשת HTTP של GET, עם ה-URI בפורמט הבא:

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

בקשה

לדוגמה:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

מחליפים את הפרמטרים userId ו-shelf במזהים שמציינים את המשתמש ואת מדף הספרים שרוצים לאחזר. מידע נוסף זמין בקטע מזהים של Google Books.

מכיוון שלא צריך לאמת את המשתמש כדי לאחזר מידע על מדפי ספרים ציבוריים, לא צריך לספק את כותרת ה-HTTP Authorization עם בקשת GET.

תשובה

אם הבקשה תתבצע בהצלחה, השרת ישיב עם קוד סטטוס HTTP 200 OK ועם הרשימה של מדפי הספרים של המשתמש:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

פרמטרים אופציונליים של שאילתות

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

חלוקה לדפים

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

  • startIndex – המיקום באוסף שממנו יתחיל. האינדקס של הפריט הראשון הוא 0.
  • maxResults – מספר התוצאות המקסימלי שיש להחזיר. ערך ברירת המחדל הוא 10. הערך המקסימלי המותר הוא 40.

עבודה עם מדפי ספרים בקטע 'הספרייה שלי'

כל הבקשות של 'הספרייה שלי' חלות על הנתונים של המשתמשים המאומתים.

אחזור רשימה של מדפי הספרים שלי

אפשר לאחזר רשימה של כל מדפי הספרים של המשתמשים המאומתים על ידי שליחת בקשת GET של HTTP ל-URI בפורמט הבא: 

https://www.googleapis.com/books/v1/mylibrary/bookshelves

בקשה

לדוגמה:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

הערה: כדי לאחזר רשימה של מדפי הספרים 'הספרייה שלי', צריך לאמת את המשתמש. לכן צריך לספק את כותרת ה-HTTP Authorization עם הבקשה GET.

תשובה

אם הבקשה תתבצע בהצלחה, השרת ישיב עם קוד סטטוס ה-HTTP 200 OK ועם הרשימה של כל מדפי הספרים של המשתמש המאומת הנוכחי:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

פרמטרים אופציונליים של שאילתות

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

אחזור רשימה של כרכים במדף הספרים שלי

אפשר לאחזר רשימה של נפחי האחסון במדף הספרים של המשתמש המאומת על ידי שליחת בקשת GET של HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

מחליפים את פרמטר הנתיב shelf במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים מופיע בקטע מזהי ספרים ב-Google Books.

בקשה

לדוגמה:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

הערה: כדי לאחזר רשימה של נפחי אחסון של 'הספרייה שלי', צריך לאמת את המשתמש. לכן צריך לספק את כותרת ה-HTTP Authorization עם הבקשה GET.

תשובה

אם הבקשה תתבצע בהצלחה, השרת ישיב עם קוד הסטטוס 200 OK של HTTP ורשימה של נפחי האחסון במדפי הספרים:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

פרמטרים אופציונליים של שאילתות

בנוסף לפרמטרים הרגילים של שאילתות, אפשר להשתמש בפרמטר השאילתה הבא לאחזור רשימה של נפחי אחסון באחד ממדפי הספרים של המשתמשים המאומתים.

חלוקה לדפים

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

  • startIndex – המיקום באוסף שממנו יתחיל. האינדקס של הפריט הראשון הוא 0.
  • maxResults – מספר התוצאות המקסימלי שיש להחזיר. ערך ברירת המחדל הוא 10.

הוספת כרך למדף הספרים שלי

כדי להוסיף נפח אחסון למדף הספרים של המשתמש המאומת, שולחים בקשת POST HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

מחליפים את פרמטר הנתיב shelf במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים מופיע בקטע מזהי ספרים ב-Google Books.

הבקשה מכילה פרמטר שאילתה נדרש אחד בלבד:

בקשה

הנה דוגמה להוספת "פרחים לאלג'רנון" למדף הספרים "מועדפים":

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

הערה: כדי לבצע שינויים במדף ספרים צריך לאמת את המשתמש, לכן צריך לספק את כותרת ה-HTTP של Authorization בבקשת POST. אבל לא נדרשים נתונים עם POST.

תשובה

אם הבקשה מצליחה, השרת ישיב עם קוד סטטוס ה-HTTP 204 No Content.

פרמטרים אופציונליים של שאילתות

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

הסרת כרך ממדף הספרים שלי

כדי להסיר נפח אחסון ממדף הספרים של המשתמש המאומת, שולחים POST HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

מחליפים את פרמטר הנתיב shelf במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים מופיע בקטע מזהי ספרים ב-Google Books.

הבקשה מכילה פרמטר שאילתה נדרש אחד בלבד:

בקשה

הנה דוגמה להסרה של 'Flowers for Algernon' מהמדף 'מועדפים':

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

הערה: כדי לבצע שינויים במדף ספרים צריך לאמת את המשתמש, לכן צריך לספק את כותרת ה-HTTP של Authorization בבקשת POST. אבל לא נדרשים נתונים עם POST.

תשובה

אם הבקשה מצליחה, השרת מגיב עם קוד סטטוס 204 No Content.

פרמטרים אופציונליים של שאילתות

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

ניקוי כל הכרכים ממדף הספרים שלי

כדי להסיר את כל נפחי האחסון ממדף הספרים של המשתמש המאומת, שולחים POST HTTP ל-URI בפורמט הבא:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

מחליפים את פרמטר הנתיב shelf במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים מופיע בקטע מזהי ספרים ב-Google Books.

בקשה

הנה דוגמה לניקוי מדף הספרים 'מועדפים':

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

הערה: כדי לבצע שינויים במדף ספרים צריך לאמת את המשתמש, לכן צריך לספק את כותרת ה-HTTP של Authorization בבקשת POST. אבל לא נדרשים נתונים עם POST.

תשובה

אם הבקשה מצליחה, השרת ישיב עם קוד הסטטוס 204 No Content.

פרמטרים אופציונליים של שאילתות

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

הפניה לפרמטרים של שאילתות

הפרמטרים של השאילתות שאפשר להשתמש בהם ב-Book API מסוכמים בקטע הזה.כל ערכי הפרמטרים צריכים להיות מקודדים בכתובת ה-URL.

פרמטרים רגילים של שאילתה

הפרמטרים של שאילתות שחלים על כל הפעולות של Books API מתועדים בפרמטרים של המערכת.

פרמטרים של שאילתות שספציפיים ל-API

הפרמטרים של בקשות שחלים רק על פעולות ספציפיות ב-Book API מסוכמים בטבלה הבאה.

פרמטר משמעות הערות המוצרים שעליהם חל המבצע
download הגבלה לנפחים על ידי זמינות ההורדות.
  • הערך הנתמך היחיד כרגע הוא epub.
  • יכול להיות שיהיה צורך לבצע רכישה כדי לקבל גישה להורדות.
filter סינון תוצאות החיפוש לפי סוג נפח וזמינות.
  • המסננים הנתמכים הם:
    • filter=partial – הגבלת התוצאות להיקפים שבהם ניתן לצפות בתצוגה מקדימה של לפחות חלק מהטקסט.
    • filter=full - הגבלת התוצאות לכרכים שבהם ניתן לראות את כל הטקסט.
    • filter=free-ebooks - הגבלת התוצאות לספרים דיגיטליים חינמיים ב-Google Books.
    • filter=paid-ebooks - הגבלת תוצאות ל-Google Books עם מחיר לרכישה.
    • filter=ebooks - הגבלת תוצאות לספרים דיגיטליים ב-Google Books, בתשלום או בחינם.דוגמאות לספרים שאינם ספרים דיגיטליים כוללות תוכן של מוציאים לאור שזמין בתצוגה מקדימה מוגבלת ולא למכירה, או כתבי עת.

 
langRestrict מגביל את נפחי האחסון שהוחזרו לכאלו שמתויגים בשפה שצוינה.
  • כדי להגביל את תוצאות החיפוש למשתמשים בשפה מסוימת, מציינים את langRestrict לקוד ISO-639-1 בן שתי אותיות, כמו en או fr.
maxResults המספר המקסימלי של רכיבים שיחזרו עם הבקשה הזו.
  • בכל בקשה לכל הפריטים באוסף, אפשר לציין את החלוקה לדפים של התוצאות על ידי ציון startIndex ו-maxResults בפרמטרים של הבקשה.
  • ברירת מחדל: maxResults=10
  • ערך מקסימלי מותר: maxResults=40.
orderBy

הסדר של תוצאות חיפוש הנפח.

  • כברירת מחדל, בקשת חיפוש מחזירה תוצאות maxResults, כאשר maxResults הוא הפרמטר שמשמש לעימוד, מסודר לפי הרלוונטי ביותר תחילה.
  • כדי לשנות את הסדר, מגדירים את הפרמטר orderBy לאחד מהערכים הבאים:
    • orderBy=relevance - החזרת תוצאות החיפוש לפי הרלוונטיות שלהן מהגבוהה ביותר לנמוכה (זו ברירת המחדל).
    • orderBy=newest - החזרת תוצאות חיפוש לפי סדר הפרסום החדש ביותר לישן ביותר.
printType הגבל לספרים או לכתבי עת.
  • הערכים הנתמכים הם:
    • printType=all – החזרת כל סוגי התוכן בעוצמת הקול (ללא הגבלה). (זוהי ברירת המחדל)
    • printType=books – החזרת ספרים בלבד.
    • printType=magazines - החזרה רק של כתבי עת.
projection הגבלת המידע על הנפח המוחזר לקבוצת משנה של שדות.
  • התחזיות הנתמכות הן:
    • projection=full – כולל כל המטא-נתונים של עוצמת הקול (ברירת מחדל).
    • projection=lite – כולל רק נושא של מטא-נתונים של נפח וגישה.
q מחרוזת שאילתה בטקסט מלא.
  • כשיוצרים שאילתה, צריך לרשום את מונחי החיפוש שמופרדים באמצעות '+', בפורמט q=term1+term2_term3. (לחלופין, אפשר להפריד ביניהם באמצעות רווח, אבל בדומה לכל ערכי הפרמטרים של השאילתה, הרווחים חייבים להיות מקודדים בכתובת URL). ה-API מחזיר את כל הרשומות שתואמות לכל מונחי החיפוש (למשל שימוש ב-AND בין מונחים). בדומה לחיפוש באינטרנט של Google, ה-API מחפש מילים שלמות (ומילים קשורות עם אותו שורש) ולא מחרוזות משנה.
  • כדי לחפש ביטוי מדויק, צריך לתחום את הביטוי במירכאות כפולות: q="exact phrase".
  • כדי להחריג ערכים שתואמים למונח נתון, יש להשתמש בטופס q=-term.
  • מונחי החיפוש הם לא תלויי-רישיות.
  • דוגמה: כדי לחפש את כל הרשומות שמכילות את הביטוי המדויק "Elizabeth Bennet" ואת המילה "Darcy" אבל לא מכילות את המילה "Austen", יש להשתמש בערך הבא בפרמטר של השאילתה:
    q="Elizabeth+Bennet"+Darcy-Austen
  • יש מילות מפתח מיוחדות (תלויות אותיות רישיות) שאפשר להגדיר במונחי החיפוש כדי לחפש בשדות מסוימים, למשל:
    • intitle: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו נמצא בכותרת.
    • inauthor: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו נמצא במחבר.
    • inpublisher: מחזירה תוצאות שבהן נמצא הטקסט שמופיע אחרי מילת המפתח הזו בבעל התוכן הדיגיטלי.
    • subject: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח מופיע ברשימת הקטגוריות של הנפח.
    • isbn: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא מספר ה-ISBN.
    • lccn: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא מספר הבקרה של ספריית הקונגרס.
    • oclc: מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הוא המספר של 'המרכז לספריות מחשבים באינטרנט'.
startIndex המיקום באוסף שבו יש להתחיל את רשימת התוצאות.
  • בכל בקשה לכל הפריטים באוסף, אפשר בחלוקה לדפים על ידי ציון startIndex ו-maxResults בפרמטרים של הבקשה.
  • האינדקס של הפריט הראשון הוא 0.
volumeId משמש לזיהוי נפח האחסון שמשויך לבקשה.
  • מציינת את כרך ההוספה או ההסרה ממדף ספרים.