يوضّح هذا المستند المعلومات الأساسية التي تحتاج إليها لاستخدام Google Books API.
مقدمة
هذا المستند مخصّص للمطوّرين الذين يريدون إنشاء تطبيقات يمكنها التفاعل مع Google Books API. تتمثّل رؤية كتب Google في رقمنة كتب العالم. يمكنك استخدام Google Books API للبحث عن المحتوى وتنظيم المكتبة الشخصية للمستخدم الذي تمّت مصادقته وتعديلها أيضًا.
قبل البدء
إنشاء حساب على Google
يجب أن يكون لديك حساب على Google لأغراض الاختبار. إذا كان لديك حساب تجريبي، يمكنك الانتقال إلى واجهة مستخدم كتب Google لإعداد بياناتك التجريبية أو تعديلها أو عرضها.
التعرّف على "كتب Google"
إذا لم تكن على دراية بمفاهيم "كتب Google"، ننصحك بقراءة هذا المستند وتجربة واجهة المستخدم قبل البدء في الترميز. يفترض هذا المستند أنّك على دراية بمفاهيم البرمجة على الويب وبتنسيقات بيانات الويب.
مزيد من المعلومات حول منح الإذن للطلبات وتعريف تطبيقك
إذا طلب التطبيق بيانات خاصة، يجب أن تتم الموافقة على الطلب من قِبل مستخدم مصادَق عليه ولديه الإذن بالوصول إلى تلك البيانات.
على وجه الخصوص، تُعتبر جميع العمليات ضِمن "مكتبتي" في Google Books API خاصة وتتطلّب المصادقة والتفويض. بالإضافة إلى ذلك، لا يمكن لأي مستخدم آخر غير مالك البيانات إجراء أي عملية تعدّل بيانات "كتب Google".
إذا طلب تطبيقك بيانات عامة، لن يحتاج الطلب إلى موافقة، ولكن يجب أن يكون مصحوبًا بمعرّف، مثل مفتاح واجهة برمجة التطبيقات.
للحصول على معلومات حول كيفية الموافقة على الطلبات واستخدام مفاتيح واجهة برمجة التطبيقات، يُرجى الاطّلاع على الموافقة على الطلبات وتحديد تطبيقك في مستند "استخدام واجهة برمجة التطبيقات".
لمحة عن Books API
مفاهيم الكتب
تستند "كتب Google" إلى أربعة مفاهيم أساسية:
- المجلد: يمثّل المجلد البيانات التي تستضيفها "كتب Google" حول كتاب أو مجلة. وهو المرجع الأساسي في Books API. تحتوي جميع الموارد الأخرى في واجهة برمجة التطبيقات هذه على حجم أو تشير إليه.
- رف الكتب: رف الكتب هو مجموعة من المجلدات. توفّر "كتب Google" مجموعة من رفوف الكتب المحدّدة مسبقًا لكل مستخدم، ويدير المستخدم بعضها بالكامل، ويتم ملء بعضها تلقائيًا استنادًا إلى نشاط المستخدم، وبعضها مختلط. يمكن للمستخدمين إنشاء رفوف كتب أخرى أو تعديلها أو حذفها، ويتم دائمًا ملء هذه الرفوف يدويًا. يمكن للمستخدم جعل رفوف الكتب خاصة أو عامة.
ملاحظة: لا يمكن حاليًا إنشاء رفوف كتب وحذفها وتعديل إعدادات الخصوصية فيها إلا من خلال موقع كتب Google الإلكتروني.
- المراجعة: هي مزيج من تقييم بالنجوم و/أو نص. يمكن للمستخدم إرسال مراجعة واحدة لكل مجلد. تتوفّر أيضًا مراجعات من مصادر خارجية، ويتم تحديد مصدرها بشكل مناسب.
- موضع القراءة: يشير موضع القراءة إلى آخر موضع تمت قراءته في كتاب من قِبل مستخدم. يمكن للمستخدم أن يملك موضع قراءة واحدًا فقط لكل مجلد. إذا لم يفتح المستخدم هذا المجلد من قبل، لن يكون موضع القراءة متوفّرًا. يمكن أن يخزّن موضع القراءة معلومات مفصّلة عن الموضع، وصولاً إلى دقة الكلمة. وتكون هذه المعلومات خاصة بالمستخدم دائمًا.
نموذج بيانات Books API
المورد هو كيان بيانات فردي يتضمّن معرّفًا فريدًا. يعمل Books API على نوعَين من الموارد استنادًا إلى المفاهيم الموضّحة أعلاه:
- مورد وحدة التخزين: يمثّل وحدة تخزين.
- مصدر رف الكتب: يمثّل رف كتب واحدًا لمستخدم معيّن.
يستند نموذج بيانات Books API إلى مجموعات من الموارد تُعرف باسم المجموعات:
- جمع بيانات الحجم
- مجموعة المجلدات هي مجموعة
من كل موارد المجلدات التي تديرها "كتب Google".
وبالتالي، لا يمكنك إدراج جميع موارد الصوت، ولكن يمكنك إدراج جميع وحدات التخزين التي تتطابق مع مجموعة من عبارات البحث.
- مجموعة رفوف الكتب
- تتألف مجموعة رف الكتب من جميع مراجع رف الكتب التي تديرها "كتب Google". يجب دائمًا الإشارة إلى رفوف الكتب في سياق مكتبة مستخدم معيّن. يمكن أن تحتوي رفوف الكتب على صفر أو أكثر من المجلدات.
- المفضّلة: رف كتب قابل للتعديل
- تم شراؤها: يتم ملء هذا الحقل بالألعاب التي اشتراها المستخدم. لا يمكن للمستخدم إضافة وحدات تخزين أو إزالتها يدويًا.
- للقراءة: رف كتب قابل للتعديل
- القراءة الآن: رف كتب قابل للتعديل
- الكتب التي قرأتها: رف كتب قابل للتعديل
- تمت مراجعته: يتضمّن هذا الحقل الكتب التي راجعها المستخدم. لا يمكن للمستخدم إضافة وحدات تخزين أو إزالتها يدويًا.
- المحتوى الذي تم عرضه مؤخرًا: يتم ملء هذا القسم بالمجلدات التي فتحها المستخدم مؤخرًا في قارئ الويب. لا يمكن للمستخدم إضافة وحدات تخزين يدويًا.
- الكتب الإلكترونية: رف كتب قابل للتعديل تتم إضافة الكتب التي تم شراؤها تلقائيًا، ولكن يمكن إزالتها يدويًا.
- كتب مقترَحة لك: يتم ملء هذا القسم باقتراحات مخصّصة لك. إذا لم يكن لدينا أي اقتراحات للمستخدم، لن تكون رفّة الكتب هذه متوفرة.
- "المفضّلة"
- "هاري بوتر"
- "كتبي الإلكترونية"
- "التبديل"
- "توايلايت"
- "الفتاة ذات وشم التنين"
توفّر Google مجموعة من رفوف الكتب المحدّدة مسبقًا لكل مستخدم:
أمثلة على رفوف الكتب:
عمليات Books API
يمكنك استدعاء خمس طرق مختلفة للمجموعات والمراجع في Books API، كما هو موضّح في الجدول التالي.
| العملية | الوصف | عمليات ربط REST HTTP |
|---|---|---|
| list | تعرض هذه الطريقة مجموعة فرعية محدّدة من الموارد ضمن مجموعة. | GET على معرّف الموارد المنتظم (URI) الخاص بمجموعة. |
| إدراج | تُدرج هذه الطريقة موردًا جديدًا في مجموعة (أي تنشئ موردًا جديدًا). | POST على معرّف الموارد المنتظم (URI) لمجموعة، حيث يتم إدخال بيانات لمورد جديد |
| الحصول على | تعرض هذه الطريقة موردًا معيّنًا. | GET على معرّف الموارد المنتظم (URI) للمورد |
| تعديل | تعديل مورد معيّن | PUT على معرّف الموارد المنتظم (URI) للمورد، حيث يمكنك إدخال بيانات المورد المعدَّل. |
| حذف | يحذف هذا الإجراء موردًا معيّنًا. | DELETE على معرّف الموارد المنتظم (URI) للمورد، حيث يتم تمرير البيانات الخاصة بالمورد المطلوب حذفه. |
يتم تلخيص العمليات المتوافقة مع الأنواع المختلفة من الموارد في الجدول أدناه. تُعرف العمليات التي تنطبق على البيانات الخاصة بالمستخدم باسم عمليات "مكتبتي"، وتتطلّب جميعها المصادقة.
نوع المورد |
العمليات المتوافقة |
||||
|---|---|---|---|---|---|
| list | إدراج | الحصول على | تعديل | delete | |
| وحدات التخزين | نعم* | نعم | |||
| رفوف الكتب | نعم* | نعم، تم إثبات صحة المستند | نعم* | نعم، تم إثبات صحة المستند | نعم، تم إثبات صحة المستند |
| مواضع القراءة | نعم، تم إثبات صحة المستند | نعم، تم إثبات صحة المستند | نعم، تم إثبات صحة المستند | نعم، تم إثبات صحة المستند | |
*يتوفّر الإصداران المصادَق عليه وغير المصادَق عليه من هذه العمليات، حيث تعمل الطلبات المصادَق عليها على بيانات "مكتبتي" الخاصة بالمستخدم، بينما تعمل الطلبات غير المصادَق عليها على البيانات العامة فقط.
أنماط الاتصال
تتوفّر عدة طرق لاستدعاء واجهة برمجة التطبيقات:
- استخدام REST مباشرةً
- استخدام REST من JavaScript (لا يلزم استخدام رمز من جهة الخادم)
REST
REST هو نمط هندسة برامج يقدّم نهجًا متسقًا وملائمًا لطلب البيانات وتعديلها.
مصطلح REST هو اختصار لعبارة نقل الحالة التمثيلية. وفي سياق Google API، يشير المصطلح إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي تخزّنها Google.
في نظام REST، يتم تخزين الموارد في متجر بيانات. يرسل العميل طلبًا يقضي بتنفيذ الخادم لإجراء محدد (مثلاً إنشاء مورد أو استرداده أو تعديله أو حذفه)، وينفّذ الخادم الإجراء ويرسل ردًّا غالبًا ما يكون على شكل تمثيل للمورد المحدد.
في REST API التابع لـ Google، يحدد العميل إجراءً باستخدام فعل HTTP، مثل POST أو GET أو PUT أو DELETE. ويحدد موردًا حسب معرف موارد منتظم (URI) فريد عالميًا يكون على الشكل التالي:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
بما أنّ كل الموارد تملك معرفات منتظمة لبروتوكولات HTTP يمكن الوصول إليها، يتيح REST تخزين البيانات مؤقتًا وتم تحسينه ليعمل مع بنية الويب الأساسية الموزَّعة.
قد تكون تعريفات الطرق في مستند معايير HTTP 1.1 مفيدة لك، وهي تشمل مواصفات عن GET وPOST وPUT وDELETE.
REST في Books API
ترتبط عمليات "كتب Google" المتاحة مباشرةً بأفعال HTTP الخاصة بـ REST، كما هو موضّح في عمليات Books API.
في ما يلي التنسيقات المحددة لمعرفات الموارد المنتظمة الخاصة بـ Books API:
https://www.googleapis.com/books/v1/{collectionName}/resourceID?parametersحيث resourceID هو معرّف لمورد وحدة تخزين أو رف كتب، وparameters هي أي معلَمات يتم تطبيقها على طلب البحث. راجِع مرجع مَعلمات طلب البحث لمعرفة التفاصيل.
يتيح لك تنسيق إضافات المسار resourceID تحديد المورد الذي تعمل عليه حاليًا، على سبيل المثال:
https://www.googleapis.com/books/v1/volumes https://www.googleapis.com/books/v1/volumes/volumeId https://www.googleapis.com/books/v1/mylibrary/bookshelves https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes ...
يُرجى العِلم أنّ العمليات التي تتضمّن mylibrary في معرّف الموارد المنتظم (URI) تنطبق فقط على بيانات المكتبة الخاصة بالمستخدم الذي تم إثبات هويته حاليًا. يمكنك العثور على تلخيص لمجموعة المعرّفات الكاملة لكل عملية متاحة في واجهة برمجة التطبيقات في مستند مرجع Books API.
في ما يلي مثالان على كيفية عمل ذلك في Books API.
ابحث عن "خياطة اللحف":
GET https://www.googleapis.com/books/v1/volumes?q=quilting
احصل على معلومات عن وحدة التخزين s1gVAAAAYAAJ:
GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ
REST من JavaScript
يمكنك استدعاء Books API باستخدام REST من JavaScript (يُعرف أيضًا باسم JSON-P)، وذلك باستخدام مَعلمة طلب البحث callback ودالة ردّ الاتصال. يتيح لك ذلك كتابة تطبيقات متقدمة تعرض بيانات "كتب Google" بدون كتابة أي رمز برمجي من جهة الخادم.
ملاحظة: يمكنك طلب طرق مصادقة من خلال تمرير رمز OAuth 2.0 المميز باستخدام المَعلمة access_token. للحصول على رمز مميز لبروتوكول OAuth 2.0 لاستخدامه مع JavaScript، اتّبِع التعليمات الموضّحة في بروتوكول OAuth 2.0 لتطبيقات الويب من جهة العميل. في علامة التبويب "الوصول إلى واجهة برمجة التطبيقات" في وحدة تحكّم APIs، احرص على إعداد معرّف عميل لتطبيقات الويب واستخدام بيانات اعتماد OAuth 2.0 عند الحصول على الرمز المميز.
يستخدم المثال التالي هذه الطريقة لعرض نتائج البحث عن "هاري بوتر":
<html> <head> <title>Books API Example</title> </head> <body> <div id="content"></div> <script> function handleResponse(response) { for (var i = 0; i < response.items.length; i++) { var item = response.items[i]; // in production code, item.text should have the HTML entities escaped. document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title; } } </script> <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script> </body> </html>
تنسيق البيانات
JSON
JSON (JavaScript Object Notation) هو تنسيق بيانات شائع مستقل عن اللغة يقدّم تمثيلاً نصيًا بسيطًا عن بنى عشوائية للبيانات. لمزيد من المعلومات، انتقِل إلى json.org.