שימוש ב-API

תוכן עניינים

מבוא

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

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

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

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

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

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

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

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

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

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

1. כשאתם מפתחים את האפליקציה, צריך לרשום אותה באמצעות מסוף Google API. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
2. מפעילים את Books API במסוף Google API. (אם ה-API לא מופיע במסוף API, אפשר לדלג על השלב הזה).
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 ושימוש בו

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

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

1. פותחים את דף פרטי הכניסה במסוף ה-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 key. כדי להגביל את המפתח לפני השימוש בו בסביבת הייצור, לוחצים על Restrict key ובוחרים באחת מהRestrictions.

כדי לשמור על אבטחת מפתחות ה-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 אחרים. נכון לעכשיו, הדרך היחידה לאחזר את מזהה המשתמש היא לחלץ אותו מה-selfLink במשאב של Bookshelf שאוחזר באמצעות בקשה מאומתת. המשתמשים יכולים לקבל מזהה משתמש משלהם גם באתר Books. משתמש לא יכול לקבל את מזהה המשתמש של משתמש אחר דרך ה-API או אתר Google Books. המשתמש השני צריך לשתף את המידע הזה באופן מפורש, למשל באימייל.

מזהים באתר של Google Books

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

• מזהה הכרך
  

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

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

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

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

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

• User-ID
  

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

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

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

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

עבודה עם נפחים

ביצוע חיפוש

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

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

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

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

בקשה

דוגמה לחיפוש של'פרחים לאלג'רנון' מאת דניאל קייס:

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

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

תשובה

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

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
}

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

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

פורמט ההורדה

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

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

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

סינון

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

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

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

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 עם אחד מהערכים הבאים כדי לציין קבוצה מוגדרת מראש של שדות Volume שיוחזר:

• full – מחזירה את כל השדות של Volume.
• 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

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

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

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

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

בקשה

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

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

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

היטל

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

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

בדוגמה הבאה מופיע מידע מוגבל על נפח אחסון בנפח אחסון יחיד:

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

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

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

כדי לאחזר רשימה של מדפי הספרים הציבוריים של משתמש, שולחים בקשת HTTP‏ GET ל-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

מכיוון שאין צורך לבצע אימות של משתמש כדי לאחזר מידע לגבי מדפי ספרים ציבוריים, אין צורך לספק את הכותרת Authorization של HTTP עם הבקשה 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"
  },
  ...
 ]
}

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

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

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

כדי לאחזר מדף ספרים ציבורי ספציפי, שולחים בקשת HTTP GET למזהה ה-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

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

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

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

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

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

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

תשובה

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

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"
  }
 ]
}

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

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

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

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

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

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

בקשה

לדוגמה:

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.

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

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

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

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

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

• volumeId – המזהה של האחסון. מידע נוסף על מזהי כרכים זמין בקטע מזהים של 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 הזה.

תשובה

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

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

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

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

כדי להסיר כרך מהמדף של המשתמש המאומת, שולחים HTTPPOST אל ה-URI בפורמט הבא:

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

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

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

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

בקשה

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

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.

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

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

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

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

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

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

בקשה

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

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.

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

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

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

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

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

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

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

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