Dynamic Links

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

הערה: התכונה הזו נקראה בעבר Book Viewability API.

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

תוכן עניינים

  1. קהל
  2. מונחי חיפוש בספרים
  3. מבוא
  4. הנחיות מיתוג
  5. ה-API בצד הלקוח
    1. הפורמט של כתובת ה-URL של הבקשה
    2. פורמט תוצאות JSON
  7. מצבים סינכרוניים ואסינכרוניים
  8. שאלות נפוצות
  9. דוגמאות קוד

קהל

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

מונחי חיפוש בספרים

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

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

מבוא

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

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

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

הנחיות מיתוג

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

  • חובה לשמור על השיוך והקישורים ל-Google Books.
  • צריך להשתמש רק בלחצן התצוגה המקדימה של Google שאושר כשמקשרים לתצוגות מקדימות ב-Google Books.
  • כל קישורי הטקסט, הלחצנים, המסמכים או הטקסט התיאורי צריכים לציית למוסכמות מתן שמות שאושרו. לדוגמה, אין להשתמש בפעלים "הורדה" או "קריאה" בעת קישור לתצוגות מקדימות ב-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 המשמש לקישור לספרים, אבל השדה 'מזהה הספר' יכול להכיל כמה מזהי ספרים מופרדים בפסיקים ויש פרמטרים נוספים 'jscmd' ו-'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;
};

בשדות האלה מוצג הפרטים הבאים:

bib_key
המזהה ששימש לשליחת שאילתה על הספר הזה.
info_url
כתובת URL של דף ב-Google Books שמכיל מידע על הספר (הדף 'מידע על הספר').
preview_url
כתובת URL של תצוגה מקדימה של הספר, שמעבירה את המשתמש ישירות לכריכה של הספר. אם רק 'תצוגת קטע טקסט' או 'אין תצוגה מקדימה של ספרים' זמינים לבקשה, לא תוחזר כתובת URL של תצוגה מקדימה.
thumbnail_url
כתובת URL של תמונה ממוזערת של שער הספר.
קטע מקדים
ערך שמציין את מצב הניראות של הספר: full (לספרים בתצוגה מלאה), partial (לספרים בתצוגה מקדימה מוגבלת) או noview (לספרים מסוג קטע טקסט או ללא תצוגה מקדימה).
ניתן להטמעה
הערך הבוליאני הזה הוא true אם ניתן להטמיע את הספר בדפים של צד שלישי באמצעות המציג המוטמע של Book Search.

התגובה היא אובייקט JSON עם שני שדות: "books" שמכיל ערך של מפת אובייקטים של ספרים ו-"options" שמכיל רשימה של האפשרויות שהופעלו עבור הבקשה הזו. אם לא צוינו אפשרויות, ייתכן שהשדה '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 כדי לעשות זאת.

פרמטרים ושדות נוספים

jscmd
הבקשה אל Google Books.
קריאה חוזרת (callback)
השם של פונקציית JavaScript שאליה אנחנו מעבירים את ההחזר.

מצב סינכרוני לעומת מצב אסינכרוני

מצב אסינכרוני

במצב אסינכרוני, המפתח מציב את התג <script> ב-<head> של המסמך ובונה את כתובת ה-URL עם כל המזהים הדרושים לעיבוד הדף. הנתונים מתקבלים מהקריאה במשתנה. כך פרטי הספר יהיו זמינים לשאר המסמך וניתן לגשת אליהם באופן מיידי ב-HTML וב-JavaScript.

מצב סינכרוני

במצב סינכרוני, המפתח משתמש בכתובת ה-URL שבמרכז ה-HTML <body>. התגובה מטופלת באמצעות קריאה חוזרת של 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, להוסיף תמונות שער ולציין את זמינות התצוגה המקדימה.
  • רשימת ספרים חלופיים
    בדומה לדוגמה הקודמת, הדוגמה הזו מוסיפה קישורים ל-Book Search באמצעות קריאה חוזרת (callback) אסינכרונית של API.
  • AJAX אינטראקטיבי
    כדאי להשתמש בקישורים דינמיים באפליקציית AJAX אינטראקטיבית במיוחד. בדוגמה הזו ניתן לראות איך לבצע מספר קריאות שונות בלי לרענן את הדף.