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

المحتويات

مقدمة

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

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

السماح بالطلبات وتحديد تطبيقك

يحتاج كل طلب يرسله تطبيقك إلى واجهة برمجة تطبيقات "كتب Google" إلى تحديد تطبيقك إلى 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 في وحدة تحكُّم واجهة برمجة تطبيقات Google. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google API.)
3. إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
4. يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
5. عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
6. يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
7. يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.

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

في ما يلي معلومات عن نطاق OAuth 2.0 في واجهة برمجة التطبيقات Books:

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 إذا لم يكن لدينا أي اقتراحات للمستخدم، هذا يعني أنّ هذا الرف غير متوفّر.
  يكون على الرفوف المخصّصة رقم تعريف أكبر من 1,000. ويكون معرّف رف الكتب فريدًا لمستخدم معيّن، أي أنّه يمكن أن يكون لمستخدمَين رف كتب يحمل المعرّف نفسه الذي يشير إلى رفوف كتب مختلفة. ويمكنك استخدام واجهة برمجة التطبيقات للحصول على رقم تعريف رف الكتب من خلال تقديم طلب يعرض مورد رف الكتب، ويمكنك العثور على رقم تعريف رف الكتب في الحقل id الخاص به.
• أرقام تعريف المستخدمين - قيم رقمية فريدة يتم تحديدها لكل مستخدم. وليس من الضروري أن تكون هذه القيم هي قيمة المعرّف نفسها المستخدمة في خدمات Google الأخرى. الطريقة الوحيدة لاسترداد رقم تعريف المستخدم في الوقت الحالي هي استخراجه من الرابط الذاتي في مورد "رف الكتب" الذي تم استرداده من خلال طلب تمت مصادقته. يمكن للمستخدمين أيضًا الحصول على معرف المستخدم الخاص بهم من موقع "كتب 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: النتائج التي يكون فيها النص الذي يلي هذه الكلمة الرئيسية هو رقم "مركز مكتبات الكمبيوتر على الإنترنت".

الطلب

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

الطلب

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

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

الطلب

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

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" للاطّلاع على مزيد من المعلومات.

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

الطلب

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

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 للحصول على مزيد من المعلومات حول معرّفات رفوف الكتب.

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

• volumeId - رقم تعريف المجلد راجِع قسم معرّفات "كتب Google" للاطّلاع على مزيد من المعلومات عن معرّفات المجلدات.

الطلب

في ما يلي مثال لإضافة "Flowers for Algernon" إلى رف الكتب "Favorites" (المفضلات):

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 للحصول على مزيد من المعلومات حول معرّفات رفوف الكتب.

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

• volumeId - رقم تعريف المجلد يمكنك الاطّلاع على قسم معرّفات "كتب Google" للحصول على مزيد من المعلومات حول معرّفات المجلدات.

الطلب

في ما يلي مثال لإزالة "Flowers for Algernon" من رف الكتب "المفضلة":

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 إلى معرّف الموارد المنتظم (URI) بالتنسيق التالي:

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

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

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

يتم توثيق معلَمات طلبات البحث التي تنطبق على جميع عمليات واجهة برمجة تطبيقات الكتب في مَعلمات النظام.

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

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