Dynamic Links

تتيح لك ميزة "الروابط الديناميكية في كتب Google" إنشاء روابط أكثر موثوقية وقابلة للتخصيص إلى "كتب Google" من موقعك الإلكتروني. على سبيل المثال، تتيح لك هذه الأداة إنشاء روابط "ذكية" لا تظهر إلا عندما يكون الكتاب في فهرسنا، أو تعرض روابط توضح للمستخدمين ما إذا كان يمكن معاينة كتاب على "كتب Google". تتيح لك ميزة الروابط الديناميكية أيضًا تضمين صورة مصغّرة في رابطك إلى "كتب Google". يهدف هذا المستند إلى السماح لك بإضافة هذه الوظيفة إلى موقعك الإلكتروني بسرعة.

ملاحظة: كانت هذه الميزة تُعرف سابقًا باسم Book Viewability API.

معالج المعاينة هو أداة تم تصميمها فوق "الروابط الديناميكية" لتسهّل عليك ربط حجز معاينات من الموقع الإلكتروني عن طريق نسخ بضعة أسطر من الرموز. هذا المستند مخصص للمطورين الأكثر تقدمًا الذين يتطلعون إلى تخصيص كيفية ارتباطهم ببحث الكتب.

المحتويات

  1. الجمهور
  2. مصطلحات بحث الكتب
  3. المقدمة
  4. إرشادات بناء هوية العلامة التجارية
  5. واجهة برمجة التطبيقات من جهة العميل
    1. تنسيق عنوان URL للطلب
    2. تنسيق النتائج بتنسيق JSON
  7. الأوضاع المتزامنة وغير المتزامنة
  8. الأسئلة الشائعة
  9. عيّنات التعليمات البرمجية

الجمهور

وثائق الروابط الديناميكية مخصصة للمبرمجين الذين يريدون كتابة تطبيقات ويب ترتبط بالكتب داخل كتب Google. تفترض هذه الوثائق أنك على دراية ببروتوكول HTTP وJavaScript الأساسي.

مصطلحات بحث الكتب

تحترم خدمة "كتب Google" قيود حقوق الطبع والنشر المحلية للمستخدم، وبالتالي لا تتوفر معاينات أو طرق عرض كاملة لبعض الكتب في جميع المواقع. يتم تجميع إمكانية العرض في الفئات التالية:

عرض كامل
الكتاب بالكامل قابل للعرض. قد تكون هذه الكتب ضمن النطاق العام.
معاينة محدودة
جزء من الكتاب قابل للعرض. هذا الكتاب محمي بموجب حقوق الطبع والنشر وقد حصل تطبيق "كتب Google" على إذن بإتاحة الوصول إلى هذه الصفحات للمستخدمين. تختلف هذه الكتب عن الكتب التي تستخدم ميزة "عرض مقتطفات" من حيث إمكانية عرض المستخدمين لصفحات كاملة.
عرض المقتطف وعدم المعاينة
تظهر للمستخدمين صفحة "لمحة عن الكتاب" فقط. وفي معظم الأحيان، لا تتوفر سوى مقتطفات قصيرة من الكتاب. لم يتم مسح هذا الكتاب ضوئيًا أو أنّه محمي بحقوق الطبع والنشر ولم تحصل خدمة "كتب Google" على إذن لعرض أكثر من بضعة "مقتطفات" ذات صلة بعبارة بحث المستخدم.

المقدمة

تصف وثائق الروابط الثابتة طريقة بسيطة للغاية لإنشاء عناوين URL لصفحة كتاب معين على كتب Google. ولسوء الحظ، أحيانًا يكون عدم وجود كتاب معين في فهرس كتب Google أو عدم توفر المعاينة للمستخدم في موقع جغرافي معين. ولأن الروابط الثابتة "عمياء"، فإنها تفشل أحيانًا في الحصول على التأثير المطلوب.

توفّر الروابط الديناميكية طريقة بديلة من جانب العميل للاستعلام عن إمكانية عرض كتاب باستخدام JavaScript. ويتيح لك ذلك تضمين روابط أكثر موثوقية ويمكن توقُّعها لخدمة "بحث الكتب"، ما يؤدي إلى تجربة أكثر اتساقًا للمستخدمين. نظرًا لاختلاف إمكانية العرض وفقًا لموقع المستخدم النهائي، لم يتم تصميم واجهة الرابط الديناميكي لطلبات البحث من جهة الخادم أو بلا اتصال بالإنترنت.

للتعرّف على ما يمكن أن تفعله الروابط الديناميكية، انتقِل إلى عيّنات التعليمات البرمجية في نهاية هذا المستند.

إرشادات بناء هوية العلامة التجارية

عند عرض الروابط الديناميكية، يجب الالتزام بإرشادات بناء هوية العلامة التجارية التي تحكم مجموعة Google Books API. وعلى وجه الخصوص،

  • ويجب الاحتفاظ بالإسناد والروابط إلى "كتب Google".
  • يجب استخدام زر "معاينة Google" الموافَق عليه فقط عند الربط بالمعاينات على "كتب Google".
  • يجب أن تلتزم أي روابط نصية أو أزرار أو مستندات أو نص وصفي باصطلاحات التسمية الموافَق عليها. على سبيل المثال، يجب عدم استخدام الأفعال "تنزيل" أو "قراءة" عند الربط بمعاينات "كتب Google"، لأنّه يمكن تنزيل أعمال النطاق العام فقط.

مثال على الترويج للعلامة التجارية

Freakonomics: An Rogue Economist استكشاف الجانب المخفي من كل شيء
بقلم "ستيفن ليفيت" و"ستيفن دوبنر"

يقدّم قسم النماذج في نهاية هذا المستند أمثلة إضافية تتوافق مع الإرشادات الحالية حول بناء هوية العلامة التجارية.

واجهة برمجة التطبيقات من جهة العميل

يقع تنسيق عنوان URL الأساسي ضمن الرابط الديناميكي من جهة العميل يسمح للمطوّرين بإنشاء عناوين URL تطلب معلومات عن كتاب واحد أو أكثر وإرسال الطلبات إلى "كتب Google" باستخدام العلامة <script>.

مثال على البنية:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>

تنسيق الطلب

يتشابه تنسيق عنوان URL مع بنية عنوان URL المستخدَمة للربط بالكتب، ولكن قد يحتوي حقل معرّف الكتاب على عدة معرّفات كتب مفصولة بفواصل، مع توفّر مَعلمتَي "jscmd" و"callback" إضافيتَين. اختياريًا، يمكن توفير وسيطات إضافية للتحكّم في فلاتر إمكانية العرض.

تتيح الروابط الديناميكية العديد من الطرق المختلفة لتعريف الكتب: أرقام ISBN وأرقام OCLC ومفاتيح LCCN. تسمح واجهة برمجة التطبيقات بطلبات البحث المجمّعة التي يصل حجمها إلى الحد الأقصى لحجم طلب GET.

رقم ISBN
&bibkeys=ISBN:0451526538 (تتوافق واجهة برمجة التطبيقات مع رقمَي 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" تحتوي على معلومات عن الكتاب (صفحة حول هذا الكتاب).
preview_url
عنوان URL لمعاينة الكتاب، والذي ينقل المستخدم مباشرةً إلى غلاف الكتاب في حال عدم توفّر عرض مقتطفات فقط أو عدم توفّر كتب للمعاينة عند تقديم طلب، لن يتم عرض أي عنوان URL للمعاينة.
thumbnail_url
عنوان URL يؤدي إلى صورة مصغّرة لغلاف الكتاب.
معاينة المحتوى
قيمة تشير إلى حالة إمكانية عرض الكتاب: full (للكتب التي يمكن عرضها بالكامل) أو partial (للكتب ذات المعاينة المحدودة) أو noview (للكتب التي تتضمّن مقتطفات أو الكتب التي ليست متاحة للمعاينة).
قابل للتضمين
تكون هذه القيمة المنطقية true إذا كان من الممكن تضمين الكتاب في صفحات تابعة لجهات خارجية باستخدام العارض المضمن في بحث الكتب.

الردّ هو كائن JSON يحتوي على حقلَين، هما "الكتب" الذي يحتوي على قيمة لخريطة كائنات الكتب و "الخيارات" التي تحتوي على قائمة بالخيارات المفعَّلة لهذا الطلب. إذا لم يتم تحديد أي خيارات، قد يتم حذف حقل "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"
رد الاتصال
اسم دالة JavaScript التي ننتقل إليها من خلال الرجوع.

الوضع المتزامن في مقابل الوضع غير المتزامن

الوضع غير المتزامن

في الوضع غير المتزامن، يضع مطوّر البرامج العلامة <script> في <head> من المستند وينشئ عنوان URL مع جميع المعرّفات اللازمة لعرض الصفحة. يتم تلقي البيانات من الاستدعاء في متغير. فهذا يجعل معلومات الكتاب متاحة لبقية المستند ويمكن الوصول إليها على الفور في HTML وJavaScript.

الوضع المتزامن

في الوضع المتزامن، يستخدم مطوّر البرامج عنوان URL في منتصف رمز HTML <body>، ويتم التعامل مع الاستجابة باستخدام استدعاء JavaScript.

الأسئلة الشائعة

س: هل أحتاج إلى مفتاح واجهة برمجة تطبيقات أو إذن آخر لاستخدام الروابط الديناميكية؟
ج: لا حاجة إلى مفتاح واجهة برمجة التطبيقات أو أي إذن آخر لاستخدام الروابط الديناميكية. للبدء، ما عليك سوى نسخ أحد الأمثلة ولصقه، ثم البدء في التعديلات.
س: ماذا عن المتصفحات التي لا تتوافق مع JavaScript أو التي تم إيقافها؟
ج: ليست هناك طريقة لاختبار ما إذا كانت "كتب Google" تشتمل على كتاب عندما لا يتم تفعيل JavaScript في متصفّح المستخدم. ننصح باستخدام بنية الروابط الثابتة في "كتب Google" مع المتصفّحات التي لا تستخدم JavaScript، ولكن تذكّر أنّه لا يمكنك مسبقًا معرفة ما إذا كانت خدمة "كتب Google" تتضمّن الكتاب الذي تتضمّن روابط تؤدي إليه.
س: كم عدد الكتب التي يمكنني البحث عنها في آنٍ واحد؟
ج: يقتصر عدد الكتب التي يمكنك البحث عنها على طول طلبات GET. في Microsoft Internet Explorer، يعمل الحد الأقصى لطول عنوان URL (2083 حرفًا) على الحد من طول طلبات GET.
س: كانت خدمة "كتب Google" تعرض نتائج لكتاب قبل لحظات. لماذا لا يتم عرض نتائج الآن؟
ج: بما أنّ المطوّرين غالبًا ما يُصدرون عددًا غير عادي من الطلبات، قد تذكر بدون قصد احتياطات الأمان الواردة في "كتب Google". لمعرفة ما إذا كان ذلك يحدث أم لا، يمكنك الاطّلاع على ما تعرضه واجهة برمجة التطبيقات. إذا كان عبارة عن طلب لملء اختبار CAPTCHA، يعني هذا أنّك أصدرت عددًا كبيرًا جدًا من طلبات البحث. ننصحك بتسجيل الدخول إلى كتب Google وإعادة المحاولة.
س: ماذا عن الخصوصية؟
ج: عند الردّ على طلبات البحث المتعلّقة بإمكانية عرض الكتب، تتلقّى Google بيانات سجلّ الخادم الذي لا تحدّد الهوية الشخصية. نتعامل مع خصوصية المستخدم بجدية تامة ونتعامل مع هذه البيانات كما هو موضح في سياسة الخصوصية. إذا كنت تقدم للمستخدمين خدمة تتضمن إمكانية عرض الكتب، ننصحك بإعلام المستخدمين بأنّ خدمتك ترسل أيضًا طلبات بحث إلى Google من خلال الروابط الديناميكية.

عيّنات التعليمات البرمجية

يقدّم هذا القسم نماذج توضح طرقًا مختلفة لاستخدام الروابط الديناميكية. يمكنك النقر على أي مثال لمشاهدته. للاطّلاع على الرمز الأساسي، يمكنك "عرض المصدر" من متصفّحك.

  • زر معاينة لصفحة كتاب
    هذا هو المثال الذي يناسبك إذا أردت استخدام الروابط الديناميكية لإضافة أزرار "معاينة" إلى صفحات كتاب فردية على موقعك الإلكتروني. وتستخدم عملية التنفيذ هذه اتصالًا متزامنًا بخدمة "كتب Google".
  • قائمة قراءة الدورة التدريبية
    يعرض هذا المثال قائمة كتب نموذجية لدورة أكاديمية. نحن نستخدم مكالمة واحدة متزامنة للربط بصفحات الحجز على "كتب Google" وإضافة صور الغلاف والإشارة إلى مدى توفّر المعاينة.
  • قائمة الكتب البديلة
    مثل المثال السابق، يضيف هذا النموذج روابط إلى بحث الكتب باستخدام استدعاء غير متزامن لواجهة برمجة التطبيقات.
  • تطبيق AJAX تفاعلي
    قد تكون مهتمًا باستخدام الروابط الديناميكية في تطبيق AJAX تفاعلي للغاية. يوضِّح هذا المثال كيفية إجراء عدد من المكالمات المختلفة بدون إعادة تحميل الصفحة.