البدء

يوضح هذا المستند بالتفصيل المعلومات الأساسية المطلوبة لاستخدام Google Books API.

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

المقدمة

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

قبل البدء

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

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

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

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

تعرف على كيفية مصادقة الطلبات وتحديد تطبيقك

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

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

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

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

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

مفاهيم الكتب

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

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

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

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

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

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

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

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

جمع بيانات المجلد

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

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

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

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

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

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

• "المفضلة"
• "هاري بوتر"
• "كتبي الإلكترونية"
• "تبديل"
• "الشفق"
• "الفتاة مع وشم التنين"

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

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

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

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

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

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

أنماط الاتصال

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

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

الراحة

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

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

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

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

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

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

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

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

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

ويكون التنسيق المحدد لمُعرِّفات الموارد المنتظمة (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 المستخدمة لكل عملية معتمدة في واجهة برمجة التطبيقات في مستند مرجع واجهة برمجة التطبيقات للكتب.

في ما يلي بعض الأمثلة على كيفية عمل ذلك في واجهة برمجة تطبيقات الكتب.

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

GET https://www.googleapis.com/books/v1/volumes?q=quilting

الحصول على معلومات عن مستوى الصوت 1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST من JavaScript

يمكنك استدعاء واجهة برمجة تطبيقات الكتب باستخدام REST من جافا سكريبت (تُسمى أيضًا JSON-P)، وذلك باستخدام معلمة طلب البحث callback ووظيفة معاودة الاتصال. ويتيح لك هذا كتابة تطبيقات ثرية تعرض بيانات الكتب بدون كتابة أي رمز من جانب الخادم.

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