المحتويات
المقدمة
هذا المستند مخصّص لمطوّري البرامج الذين يريدون كتابة تطبيقات يمكنها التفاعل مع Books API. تتمثّل مهمة كتب Google في تحويل محتوى الكتاب إلى العالم الرقمي وجعله أكثر قابلية للاكتشاف على الويب. واجهة برمجة التطبيقات للكتب هي طريقة للبحث عن هذا المحتوى والوصول إليه، بالإضافة إلى إنشاء وعرض المحتوى حول هذا المحتوى.
إذا لم تكن على دراية بمفاهيم "كتب Google"، ننصحك بالاطّلاع على البدء قبل بدء الترميز.
مصادقة الطلبات وتحديد تطبيقك
يجب أن يحدّد Google كل طلب يُرسِله تطبيقك إلى "واجهة برمجة تطبيقات الكتب". هناك طريقتان لتحديد تطبيقك: استخدام رمز OAuth 2.0 المميز (الذي يسمح أيضًا بطلب الطلب) و/أو استخدام مفتاح واجهة برمجة التطبيقات الخاص بالتطبيق. في ما يلي كيفية تحديد أي من هذه الخيارات لاستخدامها:
- إذا كان الطلب يتطلب إذنًا (مثل طلب بيانات خاصة لفرد واحد)، يجب أن يقدّم التطبيق رمز OAuth 2.0 المميز مع الطلب. قد يحتوي التطبيق أيضًا على مفتاح واجهة برمجة التطبيقات، ولكنه لا يحتاج إلى ذلك.
- إذا لم يكن الطلب يتطلب تفويضًا (مثل طلب بيانات عامة)، يجب أن يقدّم التطبيق إما مفتاح واجهة برمجة التطبيقات أو رمزًا مميزًا لبروتوكول OAuth 2.0 أو كليهما، أيًا كان الخيار الأنسب لك.
لمحة عن بروتوكولات الموافقة على الطلبات
يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.
الموافقة على الطلبات باستخدام OAuth 2.0
يجب أن يسمح مستخدم تمت مصادقته بإجراء طلبات من أجل "واجهة برمجة التطبيقات للكتب" لبيانات المستخدم غير المتاحة للجميع.
تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية العامة التالية على كل أنواع التطبيقات:
- عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
- فعِّل Books API في Google API Console. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google API.)
- إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
- يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
- عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
- يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
- يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.
تستلزم بعض التدفقات إجراء خطوات إضافية، مثل استخدام رموز مميزة للتحديث للحصول على رموز دخول جديدة. لمزيد من المعلومات التفصيلية حول العمليات المتعلقة بمختلف أنواع التطبيقات، راجِع مستندات بروتوكول OAuth 2.0 في Google.
في ما يلي معلومات حول نطاق OAuth 2.0 في واجهة برمجة التطبيقات للكتب:
https://www.googleapis.com/auth/books
لطلب الدخول باستخدام بروتوكول OAuth 2.0، يحتاج التطبيق معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google عند تسجيل التطبيق (مثل معرِّف العميل وسر العميل).
نصيحة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.
الحصول على مفتاح واجهة برمجة تطبيقات واستخدامه
يجب أن تكون الطلبات المُرسَلة إلى واجهة برمجة تطبيقات الكتب الخاصة بالبيانات العامة مصحوبةً بمعرّف يمكن أن يكون مفتاح واجهة برمجة التطبيقات أو رمز دخول.
للحصول على مفتاح واجهة برمجة تطبيقات:
- افتح صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات.
-
وتتوافق واجهة برمجة التطبيقات هذه مع نوعَين من بيانات الاعتماد.
أنشئ بيانات الاعتماد المناسبة لمشروعك:
-
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 إذا لم نقدّم أي اقتراحات للمستخدم، هذا يعني أنّ هذا الرفّ غير متوفّر.
id. - أرقام تعريف المستخدمين - القيم الرقمية الفريدة التي يتم تحديدها لكل مستخدم. وهذه القيم ليست بالضرورة قيمة المعرّف المستخدَمة في خدمات Google الأخرى. الطريقة الوحيدة لاسترداد رقم تعريف المستخدم حاليًا هي استخراجه من SelfLink في مورد Bookshelf الذي تم استرداده من خلال طلب تمت مصادقته. يمكن للمستخدمين أيضًا الحصول على رقم تعريف المستخدم الخاص بهم من موقع "كتب Google Play". ولا يمكن للمستخدم الحصول على رقم تعريف المستخدم لمستخدم آخر من خلال واجهة برمجة التطبيقات أو الموقع الإلكتروني "كتب Google"، على المستخدم الآخر مشاركة هذه المعلومات صراحةً عبر البريد الإلكتروني على سبيل المثال.
المعرّفات على موقع "كتب Google" الإلكتروني
إنّ المعرّفات التي تستخدمها مع واجهة برمجة التطبيقات للكتب هي المعرّفات نفسها المستخدمة على موقع كتب Google.
- رقم تعريف مستوى الصوت
عند عرض حجم معيّن على الموقع الإلكتروني، يمكنك العثور على رقم تعريف الحجم في معلّمة عنوان URL التي تبلغ
id. وفي ما يلي مثال لذلك:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- رقم تعريف رف الكتب
وعند عرض رف كتب معيّن على الموقع الإلكتروني، يمكنك العثور على رقم تعريف رف الكتب في المعلّمة
as_collلعنوان URL. وفي ما يلي مثال لذلك: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 حقوق الطبع والنشر والعقد والقيود القانونية الأخرى المرتبطة بالموقع الجغرافي للمستخدم النهائي. ونتيجةً لذلك، قد لا يتمكّن بعض المستخدمين من الوصول إلى محتوى الكتاب من بلدان معيّنة. على سبيل المثال، بعض الكتب &&;;previewable";في الولايات المتحدة فقط. نحذف هذه الروابط للمعاينة للمستخدمين في بلدان أخرى. ولذلك، يتم تقييد نتائج واجهة برمجة التطبيقات استنادًا إلى عنوان IP للخادم أو تطبيق العميل.
التعامل مع المجلدات
إجراء بحث
يمكنك إجراء بحث عن المجلدات من خلال إرسال طلب HTTP GET إلى معرّف الموارد المنتظم (URI) التالي:
https://www.googleapis.com/books/v1/volumes?q=search+terms
يحتوي هذا الطلب على معلمة مطلوبة واحدة:
q- ابحث عن المجلدات التي تحتوي على هذه السلسلة النصية. وتتوفّر كلمات رئيسية خاصة يمكنك تحديدها في عبارات البحث للبحث في حقول معيّنة، مثل:intitle:لعرض النتائج التي تم فيها العثور على النص الذي يلي هذه الكلمة الرئيسية في العنوان.inauthor:لعرض النتائج التي تم فيها العثور على النص الذي يلي هذه الكلمة الرئيسية في المؤلف.inpublisher:لعرض النتائج التي يُعثر فيها على النص الذي يلي هذه الكلمة الرئيسية في الناشر.subject:لعرض النتائج التي يكون فيها النص الذي يلي هذه الكلمة الرئيسية مُدرجًا في قائمة فئات المجلد.isbn:لعرض النتائج التي يكون فيها النص الذي يلي هذه الكلمة الرئيسية هو رقم ISBN.lccn:لعرض النتائج التي يكون فيها النص التالي لهذه الكلمة الرئيسية هو مكتبة مراقبة مكتبة الكونغرس.oclc:لعرض النتائج التي يكون فيها النص بعد هذه الكلمة الرئيسية هو رقم مركز المكتبة الرقمية على الإنترنت.
طلب
في ما يلي مثال على البحث عن "دانيال كيز" و#39;"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 وlflf حاليًا بالمعرّفات التي تحدّد المستخدم ورف الكتب الذي تريد استرداده. اطّلِع على القسم أرقام تعريف "كتب 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 وlflf حاليًا بالمعرّفات التي تحدّد المستخدم ورف الكتب الذي تريد استرداده. اطّلِع على القسم أرقام تعريف "كتب 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 */
ملاحظة: يجب أن تتم مصادقة المستخدم لاسترداد قائمة من مجلدات " "My Library" &مكتبتي"؛ لذلك يجب توفير عنوان 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 إلى معرّف الموارد المنتظم بالتنسيق التالي:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
استبدِل مَعلمة مسار الرف بمعرِّف رف الكتب. اطّلِع على قسم أرقام تعريف "كتب Google" للحصول على المزيد من المعلومات عن معرّفات رف الكتب.
يحتوي الطلب على معلَمة طلب بحث واحدة مطلوبة:
volumeId- رقم تعريف مستوى الصوت يمكنك الاطّلاع على قسم أرقام تعريف "كتب Google" للحصول على مزيد من المعلومات حول معرّفات المجلدات.
طلب
في ما يلي مثال على إضافة "زهور لـ Algernon" إلى &رف الكتب&المفضّلة:
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" للحصول على مزيد من المعلومات حول أرقام تعريف المجلدات.
طلب
في ما يلي مثال على إزالة "الزهور من أجل 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.
معلَمات طلب البحث الاختيارية
يمكنك استخدام معلَمات طلبات البحث العادية عند إزالة مستوى صوت من أحد رفوف الكتب التي تمت مصادقتها للمستخدم.
جارٍ محو كل المجلدات من رف الكتب
لإزالة كل المجلدات من رف الكتب الذي تمت مصادقته، أرسِل HTTP POST إلى معرّف الموارد المنتظم (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.
معلَمات طلب البحث الاختيارية
يمكنك استخدام معلَمات طلب البحث العادية عند محو كل المجلدات من رف الكتب الذي تمت المصادقة عليه الخاص بالمستخدم.
مرجع معلّمات طلب البحث
يتم تلخيص معلمات طلب البحث التي يمكنك استخدامها مع واجهة برمجة تطبيقات الكتب في هذا القسم.ويجب ترميز كل قيم المعلّمات باستخدام عناوين URL.
معلَمات طلب البحث العادية
تم توثيق معلَمات طلب البحث التي تنطبق على جميع عمليات واجهة برمجة التطبيقات للكتب على معلّمات النظام.
معلمات طلب البحث الخاصة بواجهة برمجة التطبيقات
يتم تلخيص معلمات الطلب التي تنطبق فقط على العمليات المحددة في واجهة برمجة التطبيقات للكتب في الجدول التالي.
| المعلمة | المعنى | ملاحظات | قابلية التطبيق |
|---|---|---|---|
download |
مقصورة على المجلدات حسب مدى توفّر التنزيل. |
|
|
filter |
فلترة نتائج البحث حسب نوع الحجم ومدى التوفّر |
|
|
langRestrict |
لتقييد المجلدات التي يتم عرضها باللغة التي تم وضع علامة عليها باللغة المحددة. |
|
|
maxResults |
الحد الأقصى لعدد العناصر التي يمكن عرضها مع هذا الطلب. |
|
|
orderBy |
ترتيب نتائج البحث عن الحجم |
|
|
printType |
تقييد على الكتب أو المجلات |
|
|
projection |
تقييد معلومات الحجم التي يتم عرضها لمجموعة فرعية من الحقول. |
|
|
q |
سلسلة طلب البحث بنص كامل. |
|
|
startIndex |
الموضع في المجموعة التي ستبدأ فيها قائمة النتائج. |
|
|
volumeId |
تحديد مجلد مرتبط بالطلب. |
|