התכונה 'קישורים דינמיים' של Google Books מאפשרת ליצור קישורים אמינים יותר שניתן להתאים אישית ל-Google Books מהאתר שלכם. לדוגמה, כלי זה מאפשר ליצור קישורים &ציטוט;smart" קישורים שמופיעים רק כאשר ספר נמצא באינדקס שלנו, או להציג קישורים שמציינים למשתמשים אם ניתן להציג תצוגה מקדימה של ספר ב-Google Books. התכונה 'קישורים דינמיים' מאפשרת גם לכלול תמונה ממוזערת בקישור שלכם ל-Google Books. המסמך הזה נועד לאפשר לכם להוסיף את הפונקציונליות הזו לאתר שלכם במהירות.
הערה: התכונה הזו נקראה בעבר API ל-Book Viewability.
אשף התצוגה המקדימה הוא כלי שנבנה מעל קישורים דינמיים. הקישור מאפשר לכם להוסיף קישורים לתצוגה מקדימה של ספר בקלות על ידי העתקה של כמה שורות קוד. מסמך זה מיועד למפתחים מתקדמים יותר שמעוניינים להתאים אישית את האופן שבו הם מקשרים לחיפוש ספרים.
תוכן עניינים
- קהל
- המונח של חיפוש הספרים
- מבוא
- הנחיות מיתוג
- API בצד הלקוח
- מצבים סינכרוניים ואסינכרוניים
- שאלות נפוצות
- דוגמאות קוד
קהל
המסמכים של הקישורים הדינמיים מיועדים למתכנתים שרוצים לכתוב אפליקציות אינטרנט המקשרות לספרים ב-Google Books. ההנחה היא שהיכרות עם פרוטוקול HTTP ו-JavaScript בסיסי.
מילון המונחים לחיפוש הספרים
Google Books מכבדת את הגבלות זכויות היוצרים המקומיות של המשתמש, וכתוצאה מכך, תצוגות מקדימות או צפיות מלאות של ספרים מסוימים אינן זמינות בכל המיקומים. הניראות מרוכזת במחלקות הבאות:
- תצוגה מלאה
- כל הספר ניתן לצפייה. הספרים האלה עשויים להיות נחלת הכלל.
- תצוגה מקדימה מוגבלת
- ניתן להציג חלק מהספר. הספר הזה מוגן בזכויות יוצרים ו-Google Books קיבלה הרשאה להפוך את הדפים האלה לנגישים למשתמשים. הספרים האלה שונים מתצוגת קטעי הטקסט, כך שמשתמשים יכולים לצפות בדפים שלמים.
- תצוגת קטע ללא תצוגה מקדימה
- המשתמשים רואים רק דף &מידע על הספר. לכל היותר, רק קטעים קצרים מהספר זמינים. הספר הזה לא נסרק, או שהוא מוגן בזכויות יוצרים ו-Google Books לא קיבל הרשאה לחשוף יותר מכמה סימני ציטוט.
מבוא
התיעוד של קישורים סטטיים מתאר דרך פשוטה מאוד ליצור כתובות URL לדף של ספר מסוים ב-Google Books. לצערנו, לפעמים הספר לא מופיע באינדקס של Google Books או שתצוגה מקדימה אינה זמינה למשתמש במיקום גיאוגרפי מסוים. מאחר שקישורים סטטיים הם "עיוורים,&מירכאות; לפעמים הם לא משפיעים.
התכונה 'קישורים דינמיים' מספקת שיטה חלופית פרוגרמטית בצד הלקוח לשליחת שאילתות בנוגע לניראות של ספר באמצעות JavaScript. כך תוכלו לספק קישורים אמינים וצפויים יותר לחיפוש הספרים, וכך ליהנות מחוויה עקבית יותר עבור המשתמשים. מאחר שמידת הניראות משתנה בהתאם למיקום של משתמש הקצה, ממשק הקישור הדינמי לא מיועד לשאילתות בצד השרת או אופליין.
כדי להבין מה היתרונות של קישורים דינמיים, אפשר לדלג אל דוגמאות הקוד בסוף המסמך.
הנחיות מיתוג
בעת עיבוד קישורים דינמיים, עליך לציית להנחיות המיתוג הקובעות את משפחת Google Books API. בפרט,
- יש לשמור על השיוך והקישורים ל-Google Books.
- עליך להשתמש בלחצן התצוגה המקדימה של Google שאושר רק בעת קישור לתצוגה מקדימה ב-Google Books.
- קישורים לטקסט, לחצנים, מסמכים או טקסט תיאורי צריכים לעמוד בדרישות של המוסכמות למתן שמות. לדוגמה, אין להשתמש בפעלים "download" או "read" בעת קישור לתצוגה מקדימה של Google Books, מאחר שניתן להוריד רק עבודות ציבוריות בדומיין.
מיתוג לדוגמה
הקטע לדוגמה בסוף המסמך מספק דוגמאות נוספות שתואמות להנחיות המיתוג הנוכחיות.
API בצד הלקוח
בלב הקישור הדינמי בצד הלקוח יש תבנית של כתובת URL שמאפשרת למפתחים ליצור כתובות URL שמבקשים מידע על ספר אחד או יותר ולשלוח את הבקשות ל-Google Books באמצעות התג <script>.
- דוגמה לתחביר:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
פורמט בקשה
הפורמט של כתובת ה-URL דומה לתחביר של כתובת ה-URL שמקושר לקישור לספרים, אבל השדה של מזהה הספר עשוי להכיל מספר מזהי ספרים המופרדים בפסיקים, ויש פרמטרים נוספים &&339;callback' אפשר גם להוסיף ארגומנטים כדי לשלוט במסנני הניראות.
קישורים דינמיים תומכים במספר שיטות לזיהוי ספרים: מספרי ISBN , מספרי OCLC ומפתחות LCCN. ממשק ה-API מאפשר שאילתות מקובצות בגודל המקסימלי של בקשת GET.
- מספר ISBN
&bibkeys=ISBN:0451526538(ה-API תומך גם ב-ISBN 10 וגם ב-13.)- OCLC
&bibkeys=OCLC:36792831- מספר LCCN
&bibkeys=LCCN:96072233
פורמט תוצאות JSON
התגובה מהשיחה הזו תכלול מידע על הספרים שהוחזרו, בתור אובייקט JSON אחד או יותר. האובייקטים מסוג JSON משתמשים במבנה הבא:
JsonSearchResult {
string bib_key;
string info_url;
string preview_url;
string thumbnail_url;
string preview;
};
השדות הבאים מספקים את המידע הבא:
- מפתח_מפתח
- המזהה המשמש לשליחת שאילתה לספר הזה.
- info_url
- כתובת URL לדף ב-Google Books שמכיל מידע על הספר (מידע על דף הספר הזה).
- תצוגה מקדימה url
- כתובת URL לתצוגה מקדימה של הספר, שתעביר את המשתמש ישירות לכריכה של הספר. אם רק תצוגה מקדימה של קטע טקסט או ספרים ללא תצוגה מקדימה זמינים לבקשה, לא יוחזרו כתובות URL של תצוגה מקדימה.
- תמונה ממוזערת
- כתובת URL לתמונה ממוזערת של שער הספר.
- תצוגה מקדימה
- ערך שמציין את מצב הניראות של הספר:
full(לספרים עם תצוגה מלאה),partial(לספרים עם תצוגה מקדימה מוגבלת) אוnoview(לספרים המוגדרים בקטעי קוד או לספרים בתצוגה המקדימה). - ניתן להטמעה
- הערך הבוליאני הזה הוא
trueאם ניתן להטמיע את הספר בדפי צד שלישי באמצעות המציג המוטמע של 'חיפוש ספרים'. - jscmd
- הבקשה ל-Google Books.
- קריאה חוזרת (callback)
- שם פונקציית JavaScript שאליה אנחנו מעבירים את החזרה.
- ש: האם דרוש לי מפתח API או הרשאה אחרת כדי להשתמש בקישורים דינמיים?
- ת: אין צורך במפתח API או הרשאה אחרת כדי להשתמש בקישורים דינמיים. כדי להתחיל, פשוט מעתיקים ומדביקים אחת מהדוגמאות שלנו ומתחילים לערוך אותה.
- ש: מה לגבי דפדפנים שלא תומכים ב-JavaScript או שמשביתים אותם?
- ת: אין אפשרות לבדוק אם ב-Google Books יש ספר כאשר JavaScript של משתמש לא מופעל בדפדפן. אנחנו ממליצים להשתמש במבנה הקישור הסטטי של Google Books לדפדפנים ללא JavaScript, אבל זכרו שאתם לא יכולים לדעת מראש אם ל-Google Books יש את הספר שלכם.
- שאלה: כמה ספרים ניתן לחפש בבת אחת?
- ת: מספר הספרים שאתם יכולים לחפש מוגבל רק באורך של בקשות GET. ב-Microsoft Internet Explorer, האורך המקסימלי של כתובת URL (2,083 תווים) מגביל את האורך של בקשות GET.
- שאלה: Google Books החזירה תוצאות עבור ספר ממש לפני רגע. למה הוא לא מחזיר תוצאות עכשיו?
- ת: מאחר שהמפתחים בדרך כלל שולחים כמות לא שגרתית של בקשות, אנחנו עשויים לשלוח לכם בטעות מידע על אמצעי הזהירות שנמצאו ב-Google Books. כדי לבדוק אם זה קורה, עליך לבדוק מה מוחזר על ידי ה-API. אם ביקשת למלא קוד captcha, שלחת יותר מדי שאילתות. מומלץ להתחבר ל-Google Books ולנסות שוב.
- ש: מה לגבי פרטיות?
- ת: במענה על שאילתות הניראות של ספרים, Google מקבלת נתוני יומן שלא ניתנים לזיהוי אישי בשרת. אנחנו מתייחסים ברצינות רבה לפרטיות המשתמשים ומטפלים בנתונים האלה, כפי שמתואר במדיניות הפרטיות שלנו. אם אתם מספקים למשתמשים שירות שכולל מידת חשיפה של ספר, כדאי ליידע את המשתמשים שגם הם שולחים שאילתות ל-Google באמצעות קישורים דינמיים.
- לחצן תצוגה מקדימה לדף של ספר
אם אתם מתכוונים להשתמש בקישורים דינמיים כדי להוסיף &ציטוט;תצוגה מקדימה יישום זה משתמש בקריאה סינכרונית ל-Google Books. - רשימת קריאה לקורס
בדוגמה הזו מוצגת רשימת ספרים אופיינית לקורס אקדמי. אנחנו משתמשים בקריאה סינכרונית אחת כדי לקשר לדפי ספרים ב-Google Books, להוסיף תמונות שער ולציין את זמינות התצוגה המקדימה. - רשימת ספרים חלופית
בדומה לדוגמה הקודמת, דוגמה זו מוסיפה קישורים לחיפוש ספרים באמצעות קריאה חוזרת אסינכרונית ל-API. - AJAX אינטראקטיבי
יכול להיות שתרצו להשתמש בקישורים דינמיים באפליקציית AJAX אינטראקטיבית במיוחד. הדוגמה הזו מראה איך לבצע כמה שיחות שונות בלי לרענן את הדף.
התגובה היא אובייקט JSON עם שני שדות, "books" שמכיל ערך של מפה של אובייקטים של ספרים ו-"אפשרויות&מירכאות; שכולל רשימה של האפשרויות המופעלות עבור הבקשה הזו. אם לא צוינו אפשרויות, ייתכן שהשדה "options" יושמט בתשובה. למשל:
Request:
https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo
Response:
ProcessGBSBookInfo({
"0596000278":{
"bib_key":"0596000278",
"info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
"preview":"partial"
},
"ISBN0765304368":{
"bib_key":"ISBN0765304368",
"info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
"preview":"full"
},
"0439554934":{
"bib_key":"0439554934",
"info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM",
"preview":"noview"}
});
לאחר מכן, המפתחים יכולים לשנות את התוכן ואת המראה של דפי האינטרנט שלהם על סמך תוצאות ה-JSON שאוחזרו משרת ה-GBS. בשלב זה, GBS לא מספק ספריות לשינוי ה-DOM כדי לעשות זאת.
פרמטרים ושדות נוספים
מצב סינכרוני לעומת מצב אסינכרוני
מצב אסינכרוני
במצב אסינכרוני, המפתח ממקם את התג <script> ב<head> של המסמך ובונה את כתובת ה-URL עם כל המזהים הנחוצים לעיבוד הדף. הנתונים מתקבלים מהשיחה במשתנה. פעולה זו הופכת את פרטי הספר לזמינים לשאר המסמך, וניתן לגשת אליו באופן מיידי ב-HTML וב-JavaScript.
מצב סינכרוני
במצב סינכרוני, המפתח משתמש בכתובת ה-URL באמצע ה-HTML <body>. התגובה מטופלת באמצעות קריאה חוזרת (callback) של JavaScript.
שאלות נפוצות
דוגמאות קוד
בקטע הזה מוצגות דוגמאות שממחישות דרכים שונות לשימוש בקישורים דינמיים. אפשר ללחוץ על כל דוגמה כדי לראות אותה בפעולה. כדי לראות את הקוד הבסיסי, "view source" מהדפדפן.