תוכן עניינים
מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיכולות לבצע אינטראקציה עם ה-API של Books. ל-Google Books יש מטרה: להפוך את התוכן של הספר לדיגיטלי ולהפוך אותו לגלוי יותר באינטרנט. ה-API של Books הוא דרך לחפש תוכן כזה ולגשת אליו, וכן ליצור ולהציג התאמה אישית סביב תוכן זה.
אם אתם לא מכירים את המושגים של Google Books, כדאי לקרוא את המאמר תחילת העבודה לפני שמתחילים לקוד.
מתן הרשאה וזיהוי הבקשה שלך
כל בקשה שהאפליקציה שלך שולחת ל-Books API צריכה לזהות את האפליקציה שלך ב-Google. יש שתי דרכים לזהות את האפליקציה שלכם: באמצעות אסימון OAuth 2.0 (שמאשר גם את הבקשה), ו/או באמצעות מפתח API של האפליקציה. כך קובעים באילו מהאפשרויות להשתמש:
- אם הבקשה מחייבת הרשאה (למשל, בקשה לנתונים פרטיים של אדם), האפליקציה חייבת לספק את אסימון OAuth 2.0 עם הבקשה. גם האפליקציה יכולה לספק את מפתח ה-API, אבל היא לא חייבת לעשות זאת.
- אם לבקשה לא נדרשת הרשאה (למשל, בקשה לנתונים ציבוריים), האפליקציה חייבת לספק את מפתח ה-API או את אסימון OAuth 2.0, או את שניהם – האפשרות המתאימה לך ביותר.
הסבר על פרוטוקולים של הרשאות
כדי לאשר בקשות, האפליקציה חייבת להשתמש בפרוטוקול OAuth 2.0. אין תמיכה בפרוטוקולים אחרים של הרשאות. אם האפליקציה שלכם משתמשת באפשרות כניסה באמצעות חשבון Google, היבטים מסוימים של ההרשאה יטופלו עבורכם.
הרשאת בקשות עם פרוטוקול OAuth 2.0
משתמש מאומת צריך לאשר בקשות ל-API של Google Books לקבלת נתונים שאינם גלויים לכולם.
הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:
- בעת יצירת האפליקציה, עליך לרשום אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
- מפעילים את Books API ב-Google API Console. (אם ה-API לא רשום במסוף ה-API, אפשר לדלג על השלב הזה.)
- כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
- Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
- אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
- האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
- אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.
חלק מתהליכי העבודה כוללים שלבים נוספים, כמו שימוש באסימוני רענון כדי לקבל אסימוני גישה חדשים. למידע מפורט על תהליכי העבודה לסוגים שונים של אפליקציות, ניתן לעיין בתיעוד של OAuth 2.0 של Google.
כאן מופיע מידע על היקף OAuth 2.0 של Books API:
https://www.googleapis.com/auth/books
כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).
טיפ: ספריות הלקוח של Google APIs יכולות לטפל בחלק מתהליך ההרשאה עבורכם. הן זמינות למגוון שפות תכנות. מידע נוסף זמין בדף עם ספריות ודוגמאות.
רכישה של מפתח API ושימוש בו
בקשות ל-Play API לקבלת נתונים ציבוריים חייבות להיות משויכות למזהה שיכול להיות מפתח API או אסימון גישה.
כדי לקבל מפתח API:
- פותחים את דף פרטי הכניסה ב-API Console.
-
ה-API הזה תומך בשני סוגים של פרטי כניסה.
יוצרים את פרטי הכניסה המתאימים לפרויקט:
-
OAuth 2.0: בכל פעם שהאפליקציה שלך מבקשת נתוני משתמש פרטיים, עליה לשלוח אסימון OAuth 2.0 יחד עם הבקשה. האפליקציה שלך שולחת תחילה מזהה לקוח, ואולי גם סוד לקוח כדי לקבל אסימון. יש לך אפשרות ליצור פרטי כניסה של OAuth 2.0 לאפליקציות אינטרנט, לחשבונות שירות או לאפליקציות מותקנות.
למידע נוסף, יש לעיין בתיעוד של OAuth 2.0.
-
מפתחות API: בקשה שלא מספקת אסימון OAuth 2.0 חייבת לשלוח מפתח API. המפתח מזהה את הפרויקט שלך ומספק גישה ל-API, מכסה ודוחות.
ה-API תומך בסוגים שונים של הגבלות על מפתחות API. אם מפתח ה-API הנדרש לא קיים, יוצרים מפתח API ב-Play על ידי לחיצה על יצירת פרטי כניסה > מפתח API. אפשר להגביל את המפתח לפני שמשתמשים בו בסביבת הייצור על ידי לחיצה על הגבלת המפתח, ולבחור באחת ההגבלות.
-
כדי לשמור על אבטחת מפתחות ה-API, יש לפעול לפי השיטות המומלצות לשימוש מאובטח במפתחות API.
אחרי שמקבלים מפתח API, האפליקציה יכולה לצרף את פרמטר השאילתה
key=yourAPIKey לכל כתובות ה-URL של הבקשות.
מפתח ה-API בטוח להטמעה בכתובות URL. אין צורך בקידוד כלשהו.
מזהי ספרים ב-Google Books
עליך לציין שדות מזהה עם קריאות מסוימות לשיטת API. יש שלושה סוגים של מזהים ב-Google Books:
- מזהי נפח – מחרוזות ייחודיות שניתנות לכל כרך ש-Google Books
יודע עליו. דוגמה למזהה נפח הוא
_LettPDhwR0C. ניתן להשתמש ב-API כדי לקבל את מזהה הנפח על ידי שליחת בקשה שמחזירה משאב של עוצמת קול. המזהה של עוצמת הקול מופיע בשדהid. - מזהי מדף – ערכים מספריים שניתנים למדף בספרייה של משתמש. Google מספקת מדפים מוגדרים מראש לכל משתמש עם המזהים הבאים:
- מועדפים: 0
- נרכשו: 1
- לקריאה: 2
- לקריאה עכשיו: 3
- נקראו: 4
- נבדקו: 5
- נצפו לאחרונה: 6
- הספרים הדיגיטליים שלי: 7
- ספרים עבורך: 8 אם אין לנו המלצות עבור המשתמש, המדף הזה לא קיים.
id. - מזהי משתמשים – ערכים מספריים ייחודיים שהוקצו לכל משתמש. הערכים האלה לא בהכרח זהים לערך המזהה המשמש בשירותי Google אחרים. בשלב הזה, הדרך היחידה לאחזר את ה-User-ID היא לחלץ אותה מקישור עצמי במשאב של מדף ספרים שאוחזר באמצעות בקשה מאומתת. המשתמשים יכולים גם להשיג את מזהה המשתמש שלהם באתר Google Books. משתמש לא יכול להשיג את מזהה המשתמש עבור משתמש אחר באמצעות ה-API או אתר הספרים. המשתמש האחר יצטרך לשתף את המידע הזה באופן מפורש, לדוגמה, באימייל.
מזהים באתר Google Books
המזהים שבהם אתם משתמשים עם ה-API של Google Books הם אותם המזהים שמופיעים באתר 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 של השרת או האפליקציה של הלקוח.
עבודה עם נפחים
מתבצע חיפוש
ניתן לבצע חיפוש נפחים על ידי שליחת בקשת HTTP GET
ל-URI הבא:
https://www.googleapis.com/books/v1/volumes?q=search+terms
הבקשה הזו מכילה פרמטר נדרש אחד:
q- חיפוש כרכים שמכילים את מחרוזת הטקסט הזו. יש מילות מפתח מיוחדות שאפשר לציין במונחי החיפוש בשדות ספציפיים, כמו:intitle:מחזירה תוצאות שבהן נמצאה טקסט אחרי מילת המפתח הזו בכותרת.inauthor:מחזירה תוצאות שבהן נמצא הטקסט שמופיע בעקבות מילת המפתח במחבר.inpublisher:מחזירה תוצאות שבהן נמצא הטקסט אחרי מילת המפתח הזו בבעל האפליקציה.subject:מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו מופיע ברשימת הקטגוריות של הנפח.isbn:מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו הוא מספר ה-ISBN.lccn:מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו הוא מספר הבקרה של ספריית הקונגרס.oclc:מחזירה תוצאות שבהן הטקסט שמופיע אחרי מילת המפתח הזו הוא המספר של ספריית המחשב המקוונת.
שליחת בקשה
הנה דוגמה לחיפוש של Daniel Keyes' "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.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 עם אחד מהערכים הבאים כדי לציין קבוצה מוגדרת מראש של שדות נפח להחזרה:
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
אחזור עוצמת קול ספציפית
כדי לאחזר מידע על נפח אחסון מסוים, אפשר לשלוח בקשת HTTP של GET אל ה-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. עם זאת, אם השיחה מבוצעת עם אימות, הנפח יכלול מידע ספציפי למשתמש, כגון מצב רכישה.
תשובה
אם הבקשה מצליחה, השרת מגיב באמצעות קוד סטטוס ה-HTTP של 200 OK ומשאב הנפח שהתבקש:
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 eBook.
פרמטרים אופציונליים של שאילתה
בנוסף לפרמטרים של שאילתות רגילות, אפשר להשתמש בפרמטר השאילתה הבא כדי לאחזר נפח מסוים של שאילתה.
תחזית
אתם יכולים להשתמש בפרמטר projection עם אחד מהערכים הבאים כדי לציין קבוצה מוגדרת מראש של שדות נפח להחזרה:
full– מחזירה את כל השדות של עוצמת הקול.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
מכיוון שהמשתמש לא צריך לעבור אימות כדי לאחזר מידע על מדפי ספרים ציבוריים, אין צורך לספק את כותרת ה-HTTP מסוג Authorization עם בקשת ה-GET.
תשובה
אם הבקשה מצליחה, השרת מגיב באמצעות קוד סטטוס ה-HTTP של 200 OK ורשימת מדפי הספרים:
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 ו-מדפים במזהים שמגדירים את המשתמש ואת מדף הספרים שרוצים לאחזר. מידע נוסף זמין בקטע מזהי Google Books.
שליחת בקשה
לדוגמה:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
מכיוון שהמשתמש לא צריך לעבור אימות כדי לאחזר מידע על מדפי ספרים ציבוריים, אין צורך לספק את כותרת ה-HTTP מסוג Authorization עם בקשת ה-GET.
תשובה
אם הבקשה מצליחה, השרת מגיב באמצעות קוד סטטוס ה-HTTP של 200 OK והמשאב של מדף הספרים:
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 ו-מדפים במזהים שמגדירים את המשתמש ואת מדף הספרים שרוצים לאחזר. מידע נוסף זמין בקטע מזהי Google Books.
מכיוון שהמשתמש לא צריך לעבור אימות כדי לאחזר מידע על מדפי ספרים ציבוריים, אין צורך לספק את כותרת ה-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, והערך המקסימלי המותר הוא 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.
תשובה
אם הבקשה מצליחה, השרת מגיב באמצעות קוד סטטוס ה-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"
}
]
}
פרמטרים אופציונליים של שאילתה
אתם יכולים להשתמש בפרמטרים רגילים של שאילתות כדי לאחזר את רשימת מדפי הספרים של המשתמש המאומת.
מתבצע אחזור רשימה של כרכים במדף הספרים שלי
אפשר לאחזר רשימה של הכרכים במדף הספרים המאומת של המשתמש על ידי שליחת בקשת HTTP GET ל-URI בפורמט הבא:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
מחליפים את פרמטר הנתיב המדף במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים זמין בקטע מזהי Google Books.
שליחת בקשה
לדוגמה:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
הערה: יש לאמת את המשתמש כדי לאחזר רשימה של כרכים של ה&ספרייה שלי. לכן, עליך לספק את כותרת ה-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.
הוספת עוצמת קול למדף הספרים שלי
כדי להוסיף נפח אחסון למדף הספרים של המשתמש המאומת, יש לשלוח בקשת HTTP
POST ל-URI בפורמט הבא:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
מחליפים את פרמטר הנתיב המדף במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים זמין בקטע מזהי Google Books.
בבקשה יש פרמטר שאילתה נדרש אחד:
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.
תשובה
אם הבקשה תאושר, השרת יגיב באמצעות קוד סטטוס ה-HTTP של 204 No Content.
פרמטרים אופציונליים של שאילתה
אפשר להשתמש בפרמטרים רגילים של שאילתות כשמוסיפים נפח לאחד מדפי הספרים המאומתים של המשתמש.
הסרת נפח ממדף הספרים שלי
כדי להסיר נפח אחסון ממדף הספרים של המשתמש המאומת, יש לשלוח HTTP
POST אל ה-URI בפורמט הבא:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
מחליפים את פרמטר הנתיב המדף במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים זמין בקטע מזהי Google Books.
בבקשה יש פרמטר שאילתה נדרש אחד:
volumeId– מזהה עוצמת הקול. למידע נוסף על מזהים של כרכים, יש לעיין בקטע מזהי Google Books.
שליחת בקשה
לפניכם דוגמה להסרת "Flowers for Algernon" מתוך "Favorites" מדף:
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
מחליפים את פרמטר הנתיב המדף במזהה של מדף הספרים. מידע נוסף על מזהי מדף ספרים זמין בקטע מזהי 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.
פרמטרים אופציונליים של שאילתה
אפשר להשתמש בפרמטרים רגילים של שאילתות בעת ניקוי כל הכרכים מאחד מדפי הספרים המאומתים של המשתמש.
הפניה לפרמטר השאילתה
הפרמטרים של הפרמטרים שניתן להשתמש בהם עם ה-API של Books מסכמים בקטע הזה.כל ערכי הפרמטרים צריכים להיות מקודדים בכתובות URL.
פרמטרים רגילים של שאילתה
פרמטרים של שאילתות שחלים על כל הפעולות ב-Books API מתועדים ב-פרמטרים של המערכת.
פרמטרים של שאילתה הספציפית ל-API
פרמטרים של בקשות שחלים רק על פעולות ספציפיות ב-Books API מסכמים בטבלה הבאה.
| פרמטר | משמעות | הערות | רלוונטי |
|---|---|---|---|
download |
הגבלה לכרכים לפי זמינות הורדות. |
|
|
filter |
סינון תוצאות החיפוש לפי סוג הנפח והזמינות. |
|
|
langRestrict |
הגבלה של כרכים שחוזרים לאלה שמתויגים עם השפה שצוינה. |
|
|
maxResults |
המספר המקסימלי של רכיבים להחזרה עם הבקשה הזו. |
|
|
orderBy |
סדר התוצאות של חיפוש הנפח. |
|
|
printType |
הגבלה לספרים או לכתבי עת. |
|
|
projection |
הגבלת המידע על נפח האחסון המוחזר לקבוצת משנה של שדות. |
|
|
q |
מחרוזת שאילתה בטקסט מלא. |
|
|
startIndex |
המיקום באוסף שבו יש להתחיל את רשימת התוצאות. |
|
|
volumeId |
מזהה נפח המשויך לבקשה. |
|