دليل البدء

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

مقدمة

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

قبل البدء

الحصول على حساب Google

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

التعرّف على "الكتب"

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

مزيد من المعلومات حول السماح بالطلبات وتحديد طلبك

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

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

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

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

خلفية واجهة برمجة تطبيقات "كتب Google"

مفاهيم الكتب

تم إنشاء خدمة كتب Google على أربعة مفاهيم أساسية:

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

  ملاحظة: لا يمكن إنشاء أرفف الكتب وحذفها بالإضافة إلى تعديل إعدادات الخصوصية فيها في الوقت الحالي إلا من خلال موقع كتب Google الإلكتروني.

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

نموذج بيانات واجهة برمجة تطبيقات "كتب Google"

المورد هو كيان بيانات فردي له معرّف فريد. تعمل واجهة برمجة التطبيقات Books API على نوعين من الموارد، بناءً على المفاهيم الموضحة أعلاه:

• مصدر المجلد: يمثّل هذا النوع من الملفات.
• مورد رف كتب: يمثل رف كتب واحدًا لمستخدم معيّن.

يعتمد نموذج بيانات واجهة برمجة التطبيقات للكتب على مجموعات من الموارد تسمى المجموعات:

جمع الكتب

مجموعة المجلدات هي مجموعة من كل مورد للمجلدات تتم إدارته من خلال "كتب Google". بناءً على ذلك، لا يمكنك إدراج جميع موارد المجلد، ولكن يمكنك إدراج جميع المجلدات التي تتطابق مع مجموعة من عبارات البحث.

مجموعة رفوف الكتب

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

توفر Google مجموعة من رفوف الكتب المحددة مسبقًا لكل مستخدم:

• المحتوى المفضَّل: رف كتب قابل للتحويل
• المُشتراة: تتم تعبئة هذه الوحدات بالأحجام التي اشتراها المستخدم. ولا يمكن للمستخدم إضافة وحدات التخزين أو إزالتها يدويًا.
• للقراءة: رف كتب قابل للتحويل
• القراءة الآن: رف كتب قابل للتحويل
• القراءة: رف كتب قابل للتحويل
• تمت المراجعة: يتم ملء هذه الأجزاء بالأحجام التي راجعها المستخدم. ولا يمكن للمستخدم إضافة وحدات التخزين أو إزالتها يدويًا.
• الصفحات التي تمّ الاطّلاع عليها مؤخرًا: تتم تعبئة هذا المجلد بوحدات تخزين اطّلع عليها المستخدم مؤخرًا في قارئ ويب. ولا يمكن للمستخدم إضافة وحدات التخزين يدويًا.
• كتبي الإلكترونية: رف الكتب القابل للتبديل تتم إضافة الكتب التي تم شراؤها تلقائيًا، ولكن يمكن إزالتها يدويًا.
• كتب مقترَحة لك: يتضمّن هذا القسم اقتراحات مخصّصة لك المتعلّقة بالصوت. إذا لم يكن لدينا أي اقتراحات للمستخدم، يعني هذا أنّ رف الكتب هذا غير متوفّر.

أمثلة على أرفف الكتب:

• "المفضلة"
• "هاري بوتر"
• "كتبي الإلكترونية"
• "تبديل"
• "الشفق"
• فيلم "The Girl with the Dragon Too" (الفتاة ذات وشم التنين)

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

يمكنك استدعاء خمس طرق مختلفة للمجموعات والموارد في Books API، كما هو موضح في الجدول التالي.

العملية	الوصف	تعيينات REST HTTP
list	لسرد مجموعة فرعية محددة من الموارد داخل مجموعة.	GET على عنوان URI لمجموعة.
إدراج	إدراج مورد جديد في مجموعة (إنشاء مورد جديد)	POST في معرّف الموارد المنتظم (URI) الخاص بالمجموعة، حيث تضبط البيانات لمورد جديد.
الحصول على	الحصول على مورد محدّد	GET في معرف الموارد المنتظم (URI) للمورد.
تعديل	لتعديل مورد معيّن.	PUT في معرّف الموارد المنتظم (URI) للمورد، حيث تسمح بتمرير البيانات للمصدر الذي تم تعديله.
حذف	حذف مورد محدَّد.	DELETE في معرّف الموارد المنتظم (URI) للمورد، حيث تُدخِل البيانات لكي يتم حذف المورد.

يتم تلخيص العمليات المدعومة لأنواع مختلفة من الموارد في الجدول أدناه. تُسمّى العمليات التي تنطبق على البيانات الخاصة للمستخدم عمليات "مكتبتي"، وتتطلب جميعها المصادقة.

نوع المورِد	العمليات المتاحة
	القائمة	إدراج	الحصول عليه	تعديل	حذف
المجلّدات	نعم*		نعم
رفوف كتب	نعم*	نعم، تمت المصادقة	نعم*	نعم، تمت المصادقة	نعم، تمت المصادقة
مواضع القراءة		نعم، تمت المصادقة	نعم، تمت المصادقة	نعم، تمت المصادقة	نعم، تمت المصادقة

*تتوفّر كلتا النسخة المصادقة وغير المصادَق عليها من هذه العمليات، حيث تعمل الطلبات التي تمت مصادقتها على بيانات "مكتبتي" الخاصة للمستخدم، وتعمل الطلبات التي لم تتم مصادقتها على البيانات العلنية فقط.

أنماط المكالمات

وتتوفّر عدة طرق لاستدعاء واجهة برمجة التطبيقات:

• استخدام REST مباشرةً
• استخدام REST من JavaScript (بدون الحاجة إلى رمز من جهة الخادم)

راحة

REST هو نمط من بنية البرامج التي توفر نهجًا مناسبًا ومتسقًا لطلب البيانات وتعديلها.

إنّ المصطلح REST هو اختصار لـ "التحويل التمثيلي للولاية". في سياق Google APIs، يشير ذلك إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي خزنتها Google.

في نظام REST، يتم تخزين الموارد في مخزن بيانات؛ يرسل العميل طلبًا بأن يقوم الخادم بتنفيذ إجراء معين (مثل إنشاء مورد أو استرداده أو تحديثه أو حذفه)، وينفذ الخادم الإجراء ويرسل استجابة غالبًا في شكل تمثيل للمورد المحدد.

في واجهات برمجة التطبيقات RESTful من Google، يحدّد العميل إجراءً باستخدام فعل HTTP مثل POST أو GET أو PUT أو DELETE. يحدد موردًا من خلال معرف موارد منتظم (URI) فريد عالميًا بالصيغة التالية:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

ونظرًا لأن جميع موارد واجهة برمجة التطبيقات تتضمن معرفات موارد منتظمة (URI) فريدة يمكن الوصول إليها عبر HTTP، فإن REST تتيح التخزين المؤقت للبيانات ويتم تحسينها للعمل مع البنية الأساسية الموزَّعة على الويب.

قد تجد تعريفات الطريقة في مستندات معايير HTTP 1.1 مفيدة، وتضم مواصفات GET وPOST وPUT وDELETE.

بروتوكول REST في واجهة برمجة تطبيقات الكتب

يتم ربط عمليات "الكتب" المتوافقة مباشرةً بأفعال HTTP في REST، كما هو موضّح في عمليات واجهة برمجة تطبيقات الكتب.

في ما يلي التنسيق المعيّن لمعرّفات الموارد المنتظمة (URI) لواجهة برمجة تطبيقات الكتب:

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) لا تسري إلا على بيانات المكتبة الخاصة للمستخدم الذي تمت مصادقته حاليًا. يتم تلخيص المجموعة الكاملة من معرفات الموارد المنتظمة (URI) المستخدمة لكل عملية متوافقة في واجهة برمجة التطبيقات في المستند مرجع واجهة برمجة تطبيقات الكتب.

في ما يلي مثالان على آلية عمل ذلك في واجهة برمجة تطبيقات "كتب Google".

لإجراء عملية بحث عن صناعة الألحفة:

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 ودالة معاودة الاتصال. يتيح لك ذلك كتابة تطبيقات ثرية تعرض بيانات "الكتب" بدون كتابة أي رمز من جانب الخادم.

ملاحظة: يمكنك استدعاء الطرق التي تمت مصادقتها من خلال تمرير رمز OAuth 2.0 المميز باستخدام المعلمة access_token. للحصول على رمز OAuth 2.0 المميز لاستخدامه مع JavaScript، يمكنك اتّباع التعليمات الموضحة في OAuth 2.0 لتطبيقات الويب من جهة العميل. في علامة التبويب "الوصول إلى واجهة برمجة التطبيقات" في وحدة التحكم في واجهات برمجة التطبيقات، تأكَّد من إعداد معرِّف العميل لتطبيقات الويب، واستخدام بيانات اعتماد 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.