استخدام واجهة برمجة التطبيقات

المحتويات

  1. مقدّمة
    1. المصادقة والتفويض
    2. أرقام تعريف كتب Google
    3. ضبط الموقع الجغرافي للمستخدم
  2. العمل مع مجلدات
    1. إجراء بحث
    2. استرداد وحدة تخزين معيّنة
  3. العمل مع رفوف الكتب
    1. استرداد قائمة بمكتبات المستخدم العامة
    2. استرداد رف كتب علني محدّد
    3. استرداد قائمة بالمجلدات على رف كتب متاح للجميع
  4. العمل مع رفوف الكتب في "مكتبتي"
    1. استرداد قائمة برفوف الكتب
    2. استرداد قائمة بالمجلدات على رفّ الكتب
    3. إضافة مجلد إلى رف الكتب
    4. إزالة مجلد من رف الكتب
    5. محو كل الكتب من رف الكتب
  5. مرجع مَعلمة طلب البحث
    1. مَعلمات طلب البحث العادية
    2. مَعلمات طلب البحث الخاصة بواجهة برمجة التطبيقات

مقدمة

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

إذا لم تكن على دراية بمفاهيم "كتب Google"، عليك قراءة مقالة البدء قبل بدء الترميز.

تفويض الطلبات وتحديد تطبيقك

يجب أن يعرّف كل طلب يرسله تطبيقك إلى واجهة برمجة التطبيقات Books API تطبيقك على Google. هناك طريقتان لتحديد هوية تطبيقك: باستخدام رمز OAuth 2.0 المميّز (الذي يمنح الإذن بالطلب أيضًا) و/أو باستخدام مفتاح واجهة برمجة التطبيقات للتطبيق. في ما يلي كيفية تحديد الخيار الذي يجب استخدامه:

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

لمحة عن بروتوكولات الموافقة على الطلبات

يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.

الموافقة على الطلبات باستخدام OAuth 2.0

يجب أن يوافق مستخدم موثّق على الطلبات الموجّهة إلى Books API للحصول على بيانات المستخدم غير المتاحة للجميع.

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية العامة التالية على كل أنواع التطبيقات:

  1. عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
  2. فعِّل واجهة برمجة التطبيقات Books API في وحدة تحكّم Google API. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google 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 معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.

الحصول على مفتاح واجهة برمجة التطبيقات واستخدامه

يجب أن تكون طلبات البيانات العامة المرسَلة إلى واجهة برمجة التطبيقات Books API مصحوبة بمعرّف، والذي يمكن أن يكون مفتاح واجهة برمجة التطبيقات أو رمز مميّز للوصول.

للحصول على مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

  1. افتح صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات.
  2. تتيح واجهة برمجة التطبيقات هذه نوعَين من بيانات الاعتماد. أنشئ بيانات الاعتماد المناسبة لمشروعك:

    • بروتوكول OAuth 2.0: عندما يطلب تطبيقك بيانات مستخدمين خاصة، يجب أن يرسل رمزًا مميزًا لبروتوكول OAuth 2.0 مع الطلب. يُرسِل تطبيقك أولاً معرّف العميل وربما سر العميل للحصول على رمز مميّز. يمكنك إنشاء بيانات اعتماد OAuth 2.0 لتطبيقات الويب أو حسابات الخدمة أو التطبيقات المثبَّتة.

      لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OAuth 2.0.

    • مفاتيح واجهة برمجة التطبيقات: يجب إرسال مفتاح واجهة برمجة التطبيقات مع الطلب الذي لا يقدّم رمزًا مميزًا لبروتوكول OAuth 2.0. يحدِّد المفتاح مشروعك ويوفّر إمكانية الوصول إلى واجهة برمجة التطبيقات والحصة والتقارير.

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

للحفاظ على أمان مفاتيح واجهة برمجة التطبيقات، اتّبِع أفضل الممارسات المتعلقة باستخدام مفاتيح واجهة برمجة التطبيقات بأمان.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق مَعلمة طلب البحث key=yourAPIKey بجميع عناوين URL للطلبات.

مفتاح واجهة برمجة التطبيقات آمن لتضمينه في عناوين URL، ولا يحتاج إلى أي ترميز.

أرقام تعريف "كتب Google"

عليك تحديد حقول التعريف باستخدام طلبات محددة لطرق واجهة برمجة التطبيقات. هناك ثلاثة أنواع من المعرّفات المستخدَمة في "كتب Google":

  • معرّفات المجلدات: سلاسل فريدة يتم منحها لكل مجلد يعرفه تطبيق "كتب Google" . على سبيل المثال، _LettPDhwR0C هو رقم تعريف وحدة تخزين. يمكنك استخدام واجهة برمجة التطبيقات للحصول على معرّف المجلد من خلال تقديم طلب يعرض مرجعًا للمجلد، ويمكنك العثور على معرّف المجلد في الحقل id.
  • أرقام تعريف رفوف الكتب: هي قيم رقمية يتم منحها لرف كتب في مكتبة أحد المستخدمين. توفّر Google بعض الرفوف المحدّدة مسبقًا لكل مستخدم باستخدام أرقام التعريف التالية:
    • القنوات المفضّلة: 0
    • تم شراؤه: 1
    • للقراءة: 2
    • تتم القراءة الآن: 3
    • الكتب التي تمت قراءتها: 4
    • عدد المراجعات: 5
    • المنتجات التي تم الاطّلاع عليها مؤخرًا: 6
    • كتبي الإلكترونية: 7
    • الكتب المُقترَحة لك: 8 إذا لم تكن لدينا أي اقتراحات للمستخدم، لن يظهر هذا الرف.
    تحتوي الرفوف المخصّصة على أرقام تعريف أكبر من 1000. يكون رقم تعريف رف الكتب فريدًا لمستخدم معيّن، أي يمكن أن يكون لدى مستخدمَين رف كتب يحمل رقم التعريف نفسه ويشير إلى رفوف كتب مختلفة. يمكنك استخدام واجهة برمجة التطبيقات للحصول على معرّف رف الكتب من خلال تقديم طلب يعرض مرجع رف الكتب، ويمكنك العثور على معرّف رف الكتب في الحقل id.
  • أرقام تعريف المستخدِمين: قيم رقمية فريدة يتمّ تعيينها لكلّ مستخدِم. ولا تعني قيم هذه بالضرورة أنّها هي نفسها قيمة المعرّف المستخدَمة في خدمات Google الأخرى. في الوقت الحالي، الطريقة الوحيدة لاسترداد معرّف المستخدم هي استخراجه من ملف ‎ selfLink في مورد Bookshelf تم استرداده من خلال طلب تمّت مصادقته. يمكن للمستخدمين أيضًا الحصول على رقم تعريف المستخدم الخاص بهم من موقع "كتب Google" الإلكتروني. لا يمكن لمستخدمٍ ما الحصول على معرّف مستخدم آخر من خلال واجهة برمجة التطبيقات أو موقع "كتب Google" الإلكتروني، بل على المستخدم الآخر مشاركة هذه المعلومات صراحةً، عبر البريد الإلكتروني مثلاً.

المعرّفات على موقع "كتب Google" الإلكتروني

الأرقام التعريفية التي تستخدمها مع Books API هي الأرقام التعريفية نفسها المستخدَمة على موقع كتب Google الإلكتروني.

  • رقم تعريف وحدة التخزين

    عند عرض مجلد معيّن على الموقع الإلكتروني، يمكنك العثور على معرّف المجلد في مَعلمة عنوان URL id. يُرجى الاطّلاع على المثال أدناه: 

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

  • معرّف رف الكتب

    عند عرض رفّ كتب معيّن على الموقع الإلكتروني، يمكنك العثور على معرّف رفّ الكتب في مَعلمة عنوان URL as_coll. يُرجى الاطّلاع على المثال أدناه: 

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

  • رقم تعريف المستخدم

    عند عرض مكتبتك على الموقع الإلكتروني، يمكنك العثور على رقم تعريف المستخدم في مَعلمة عنوان URL uid. يُرجى الاطّلاع على المثال أدناه: 

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

ضبط الموقع الجغرافي للمستخدم

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

العمل مع مجلدات

إجراء عملية بحث

يمكنك إجراء بحث عن مجلدات من خلال إرسال طلب HTTP GET إلى معرّف الموارد المنتظم (URI) التالي:

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

يحتوي هذا الطلب على مَعلمة واحدة مطلوبة:

  • q - البحث عن المجلدات التي تحتوي على سلسلة النصوص هذه هناك كلمات رئيسية خاصة يمكنك تحديدها في عبارات البحث للبحث في حقول معيّنة، مثل:
    • intitle: تعرِض النتائج التي يتضمّن فيها العنوان النص الذي يلي الكلمة الرئيسية هذه.
    • inauthor: تعرِض النتائج التي يتضمّن فيها المؤلف النص الذي يلي الكلمة الرئيسية هذه.
    • inpublisher: تعرِض النتائج التي يتضمّن فيها الناشر النص الذي يلي هذه الكلمة الرئيسية.
    • subject: تعرِض النتائج التي يتضمّن النص الذي يلي هذه الكلمة الرئيسية في قائمة الفئات للوحدة.
    • isbn: تعرِض النتائج التي يكون فيها النص الذي يلي هذه الكلمة الرئيسية هو رقم ISBN.
    • lccn: تعرِض النتائج التي يكون فيها النص التالي للكلمة الرئيسية هو رقم الضبط في مكتبة الكونغرس.
    • oclc: تعرِض النتائج التي يكون فيها النص الذي يلي هذه الكلمة الأساسية هو رقم مركز المكتبة الرقمية على الإنترنت.

الطلب

في ما يلي مثال على البحث عن كتاب "زهور لألفريد" لدانيال كييز: 

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" للحصول على مزيد من المعلومات عن أرقام تعريف المجلدات.

الطلب

في ما يلي مثال على طلب 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.

مَعلمات طلب البحث الاختيارية

بالإضافة إلى مَعلمات طلب البحث العادية، يمكنك استخدام مَعلمة طلب البحث التالية عند استرداد وحدة تخزين معيّنة.

الإسقاط

يمكنك استخدام المَعلمة 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" للحصول على مزيد من المعلومات عن أرقام تعريف المستخدمين.

الطلب

يُرجى الاطّلاع على المثال أدناه:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

بما أنّه ليس من الضروري مصادقة المستخدم لاسترداد معلومات بشأن رفوف الكتب العامة، ليس عليك تقديم عنوان Authorization HTTP مع طلب 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"
  },
  ...
 ]
}

مَعلمات طلب البحث الاختيارية

يمكنك استخدام مَعلمات طلب البحث العادية عند retrieving the list of a user's public bookshelves.

استرداد رف كتب عام محدّد

يمكنك استرداد رفّ كتب عام محدّد من خلال إرسال طلب HTTP GET إلى معرّف URI بالشكل التالي:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

استبدِل مَعلمتَي مسار userId و shelf بمعرّفات تحدِّد المستخدم ورفّ الكتب الذي تريد استرجاعه. اطّلِع على القسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات.

الطلب

يُرجى الاطّلاع على المثال أدناه:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

بما أنّه ليس من الضروري مصادقة المستخدم لاسترداد معلومات بشأن رفوف الكتب العامة، ليس عليك تقديم عنوان Authorization HTTP مع طلب 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"
}

مَعلمات طلب البحث الاختيارية

يمكنك استخدام مَعلمات طلب البحث العادية عند retrieving a specific public bookshelf.

استرداد قائمة بالمجلدات على رف كتب متاح للجميع

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

بما أنّه ليس من الضروري مصادقة المستخدم لاسترداد معلومات بشأن الرفوف العامة للكتب، ليس عليك تقديم عنوان Authorization HTTP مع طلب 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، والحد الأقصى المسموح به هو 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"
  }
 ]
}

مَعلمات طلب البحث الاختيارية

يمكنك استخدام مَعلمات طلب البحث العادية عند retrieving the list of the authenticated user's bookshelves.

استرجاع قائمة بالمجلدات على رفّ الكتب

يمكنك استرداد قائمة بالمجلدات في رفّ الكتب الخاص بالمستخدم الذي تمّت مصادقة هويته من خلال إرسال طلب HTTP GET إلى معرّف الموارد المنتظم (URI) بالشكل التالي:

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

استبدِل مَعلمة مسار shelf بمعرّف bookshelf. اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات عن أرقام تعريف رفوف الكتب.

الطلب

يُرجى الاطّلاع على المثال أدناه:

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

استبدِل مَعلمة مسار shelf بمعرّف bookshelf. اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات عن أرقام تعريف رفوف الكتب.

يحتوي الطلب على مَعلمة طلب بحث واحدة مطلوبة:

  • ‫volumeId: رقم تعريف وحدة التخزين اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات عن أرقام تعريف المجلدات.

الطلب

في ما يلي مثال لإضافة "زهور لألفريد" إلى رف الكتب "الكتب المفضّلة":

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 إلى معرّف الموارد المنتظم بالشكل التالي:

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

استبدِل مَعلمة مسار shelf بمعرّف bookshelf. اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات عن أرقام تعريف رفوف الكتب.

يحتوي الطلب على مَعلمة طلب بحث واحدة مطلوبة:

  • ‫volumeId: رقم تعريف وحدة التخزين اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات عن أرقام تعريف المجلدات.

الطلب

في ما يلي مثال لإزالة "زهور لألفريد" من رفّ الكتب "الكتب المفضّلة": 

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.

مَعلمات طلب البحث الاختيارية

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

محو كل الكتب من رفّ الكتب

لإزالة جميع الأجزاء من رفّ الكتب الخاص بالمستخدم الذي تمّت مصادقة هويته، أرسِل POST HTTP إلى عنوان URL بالشكل التالي:

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

استبدِل مَعلمة مسار shelf بمعرّف bookshelf. اطّلِع على قسم أرقام تعريف "كتب 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 في مَعلمات النظام.

مَعلمات طلب البحث الخاصة بواجهة برمجة التطبيقات

في الجدول التالي، تم تلخيص مَعلمات الطلب التي تنطبق فقط على عمليات معيّنة في واجهة برمجة التطبيقات Books API.

المَعلمة المعنى ملاحظات قابلية التطبيق
download تقييد المحتوى على وحدات التخزين حسب مدى توفّر التنزيل
  • والقيمة الوحيدة المتاحة حاليًا هي epub.
  • قد يكون عليك الشراء للوصول إلى إمكانية التنزيل.
filter فلترة نتائج البحث حسب نوع الحجم ومدى التوفّر
  • الفلاتر المتوافقة هي:
    • filter=partial - حصر النتائج بالكتب التي يمكن معاينة جزء من النص فيها على الأقل
    • filter=full - حصر النتائج بمجموعات الكتب التي يمكن فيها عرض كل النص
    • filter=free-ebooks - يمكنك عرض النتائج على الكتب الإلكترونية المجانية من Google فقط.
    • filter=paid-ebooks - يمكنك حصر النتائج بالكتب الإلكترونية من Google التي تتضمّن سعرًا للشراء.
    • filter=ebooks - يمكنك حصر النتائج بالكتب الإلكترونية من Google، سواء كانت مدفوعة أو مجانية.ومن الأمثلة على المحتوى غير الكتب الإلكترونية، محتوى الناشر المتاح في معاينة محدودة وليس للبيع، أو المجلات.

 
langRestrict حصر الكتب المعروضة في نتائج البحث بالكتب التي تم وضع علامة عليها باللغة المحدّدة
  • يمكنك حصر نتائج البحث على تلك التي تتضمّن لغة معيّنة من خلال ضبط langRestrict على رمز مكوّن من حرفَين وفقًا لمعيار ISO-639-1، مثل "ar" أو "en".
maxResults الحد الأقصى لعدد العناصر التي سيتم عرضها مع هذا الطلب.
  • في أي طلب لعرض جميع العناصر في مجموعة، يمكنك تقسيم النتائج إلى صفحات من خلال تحديد startIndex وmaxResults في مَعلمات الطلب.
  • عناوين URL التلقائية: maxResults=10
  • الحد الأقصى المسموح به للقيمة: maxResults=40.
orderBy

ترتيب نتائج البحث حسب حجم البحث

  • يعرض طلب البحث تلقائيًا maxResults نتيجة، حيث maxResults هي المَعلمة المستخدَمة في تقسيم الصفحات، ويتم ترتيبها حسب الأكثر صلة أولاً.
  • يمكنك تغيير الترتيب من خلال ضبط المَعلمة orderBy على إحدى القيم التالية:
    • orderBy=relevance - عرض نتائج البحث بترتيب من الأكثر صلة إلى الأقل (هذا هو الإعداد التلقائي)
    • orderBy=newest - عرض نتائج البحث بترتيب تاريخ النشر من الأحدث إلى الأقدم
printType حصر المحتوى بالكتب أو المجلات
  • القيم المسموح بها هي:
    • printType=all - عرض جميع أنواع المحتوى في المجلد (بدون قيود) هذا هو الخيار التلقائي.
    • printType=books - إرجاع الكتب فقط
    • printType=magazines - إرجاع المجلات فقط
projection تستخدم لتقييد معلومات الحجم التي يتم عرضها على مجموعة فرعية من الحقول.
  • التوقعات المتوافقة هي:
    • projection=full - يتضمّن جميع البيانات الوصفية للوحدة (الإعداد التلقائي).
    • ‫projection=lite: تتضمّن هذه السمة بيانات وصفية حول حجم البيانات وإمكانية الوصول إليها فقط.
q سلسلة طلب البحث النصية الكاملة
  • عند إنشاء طلب بحث، يجب إدراج عبارات البحث مفصولة بعلامة "+"، على النحو التالي: q=term1+term2_term3. (يمكنك بدلاً من ذلك فصلها باستخدام مسافة، ولكن كما هو الحال مع جميع قيم مَعلمات طلب البحث، يجب بعد ذلك ترميز المسافات باستخدام ترميز عنوان URL). تعرض واجهة برمجة التطبيقات جميع الإدخالات التي تتطابق مع كل عبارات البحث (مثل استخدام AND بين العبارات). مثل ميزة "بحث الويب" من Google، تبحث الواجهة في الكلمات الكاملة (والكلمات ذات الصلة ذات الجذر نفسه)، وليس في السلسلة الفرعية.
  • للبحث عن عبارة مطابقة، احط العبارة بعلامات اقتباس: q="exact phrase".
  • لاستبعاد الإدخالات التي تتطابق مع عبارة معيّنة، استخدِم النموذج q=-term.
  • عبارات البحث غير حسّاسة لحالة الأحرف.
  • مثال: للبحث عن جميع الإدخالات التي تحتوي على العبارة "Elizabeth Bennet" والكلمة "Darcy" بالضبط ولكنّها لا تحتوي على الكلمة "Austen"، استخدِم قيمة مَعلمة الطلب التالية:
    q="Elizabeth+Bennet"+Darcy-Austen
  • هناك كلمات رئيسية خاصة (حساسة لحالة الأحرف) يمكنك تحديدها في عبارات البحث للبحث في حقول معيّنة، مثل:
    • intitle: تعرض النتائج التي يتضمّن عنوانها النص الذي يلي هذه الكلمة الرئيسية.
    • inauthor: تعرض النتائج التي يتضمّن فيها المؤلف النص الذي يلي هذه الكلمة الرئيسية.
    • inpublisher: تعرض النتائج التي يتضمّن فيها الناشر النص الذي يلي هذه الكلمة الرئيسية.
    • subject: تعرض النتائج التي يتضمّن فيها النص الذي يلي الكلمة الرئيسية هذه في قائمة فئات المجلد.
    • isbn: تعرض النتائج التي يكون فيها النص الذي يلي هذه الكلمة الرئيسية هو رقم ISBN.
    • ‫lccn: تعرِض النتائج التي يكون فيها النص الذي يلي الكلمة الرئيسية هذه هو رقم التحكّم في مكتبة الكونغرس.
    • oclc: تعرِض النتائج التي يكون فيها النص الذي يلي الكلمة الرئيسية هذا هو رقم مركز المكتبة الإلكترونية للكمبيوتر.
startIndex الموضع في المجموعة الذي سيتم من خلاله بدء قائمة النتائج.
  • في أي طلب للحصول على جميع العناصر في مجموعة، يمكنك تقسيم النتائج إلى صفحات عن طريق تحديد startIndex وmaxResults في مَعلمات الطلب.
  • فهرس العنصر الأول هو 0.
volumeId لتحديد وحدة تخزين مرتبطة بالطلب
  • لتحديد المجلد الذي تريد إضافته أو إزالته من رفّ كتب