توفّر واجهة برمجة تطبيقات Discovery قائمة بواجهات برمجة تطبيقات Google لاسترداد المستند الذي يمكن قراءته آليًا ومعدّل العثور على البيانات الوصفية لكل واجهة برمجة تطبيقات.
هذا المستند موجّه لمطوّري البرامج الذين يريدون كتابة مكتبات العملاء ومكوّنات IDE الإضافية وأدوات أخرى للتفاعل مع Google APIs.
خلفية خدمة Discovery
المفاهيم
تستند خدمة Google APIs Discovery إلى مفهومَين أساسيَين:
- دليل واجهات برمجة التطبيقات: قائمة بجميع واجهات برمجة التطبيقات التي تدعمها خدمة استكشاف واجهات برمجة التطبيقات. يقدّم كل إدخال في الدليل تفاصيل عن واجهة برمجة تطبيقات متوافقة، بما في ذلك اسمها ووصفها القصير لوظيفتها ورابط المستندات. يمكن أن تتضمّن واجهة برمجة التطبيقات عدة إدخالات للدليل، أحدها لكل إصدار من إصداراتها المتوافقة.
- مستند أثناء التصفّح: هو وصف يمكن قراءته آليًا لواجهة برمجة تطبيقات معيّنة. يصف مستند "اقتراحات" الموقع الإلكتروني لإصدار معيّن من واجهة برمجة التطبيقات. يقدّم المستند تفاصيل حول كيفية الوصول إلى الطرق المختلفة لكل واجهة برمجة تطبيقات من خلال استدعاءات RESTful HTTP. ويتضمّن مستند "اقتراحات" أوصافًا للبيانات والطرق المرتبطة بواجهة برمجة التطبيقات، بالإضافة إلى معلومات حول نطاقات OAuth المتاحة وأوصاف المخططات والأساليب والمعلّمات وقيم المعلّمات المتاحة.
نموذج البيانات
المورد هو كيان بيانات فردي بمعرّف فريد. تعمل خدمة استكشاف واجهات برمجة التطبيقات الخاصة بـ Google على نوعين من الموارد، استنادًا إلى المفاهيم المذكورة أعلاه.
قائمة دليل واجهات برمجة التطبيقات: قائمة بواجهات برمجة التطبيقات
يحتوي كل إدخال في الدليل على زوج اسم واجهة برمجة التطبيقات/الإصدار مع المعلومات التالية:
- معلومات تحديد الهوية والوصف: الاسم والإصدار والعنوان والوصف.
- معلومات المستندات: الرموز ورابط المستندات.
- معلومات الحالة، بما في ذلك تصنيفات الحالة، ومؤشر إلى ما إذا كان هذا هو الإصدار المفضّل من واجهة برمجة التطبيقات أم لا.
- رابط مستند أثناء التصفّح، وهو معرّف الموارد المنتظم (URI) لمستند "اقتراحات" لواجهة برمجة التطبيقات هذه (يتم تقديمه كعنوان URL كامل، مثل https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
مورد الاكتشاف: وصف يمكن قراءته آليًا لواجهة برمجة تطبيقات معينة
بالإضافة إلى المعلومات المقدمة في دليل واجهات برمجة التطبيقات، يتضمن مستند Discovery أيضًا ما يلي:
- المخططات، وهي قائمة بمخططات موارد واجهة برمجة التطبيقات التي تصف البيانات التي يمكنك الوصول إليها في كل واجهة برمجة تطبيقات. تستند مخططات خدمة Google APIs Discovery إلى مخطط JSON.
- الطرق، بما في ذلك قائمة بأساليب واجهة برمجة التطبيقات والمعلّمات المتاحة لكل طريقة
- نطاقات OAuth، التي تحدد قائمة نطاقات OAuth المتاحة لواجهة برمجة التطبيقات هذه.
- المستندات المضمّنة: تقدّم هذه السمة أوصافًا مختصرة للمخططات والأساليب والمعلَمات وقيم المعلّمات المتاحة.
مجموعة الدليل الواحد هي الحاوية النظرية لمورد دليل واجهات برمجة التطبيقات الواحد، ومراجع المستند أثناء التصفّح لكل واجهة برمجة تطبيقات متوافقة.
يتوفر مزيد من التفاصيل حول مورد "دليل واجهات برمجة التطبيقات" ومورد "اقتراحات" في المستندَين استخدام واجهة برمجة التطبيقات والمراجع.
العمليات
يمكنك استدعاء طريقتين مختلفتين في المجموعات والموارد في "خدمة Google APIs Discovery" كما هو موضّح في الجدول التالي.
| العملية | الوصف | تعيينات HTTP لـ REST |
|---|---|---|
| list | يسرد جميع واجهات برمجة التطبيقات المتاحة. | GET في معرف الموارد المنتظم (URI) لمورد الدليل. |
نمط الاتصال
راحة
يتم ربط العمليات المتوافقة مع "خدمة Google APIs أثناء التصفّح" مباشرةً مع فعل HTTP REST HTTP GET، كما هو موضّح في العمليات.
الصيغة المحددة لعناوين URL لخدمة اكتشاف واجهات برمجة تطبيقات Google هي:
https://discovery.googleapis.com/discovery/v1/apis?parameters
حيث يكون api هو معرّف مورد المستند أثناء التصفّح، وversion هو معرّف الإصدار المحدد من واجهة برمجة التطبيقات، و_parameters_، هي أي معلّمات يجب تطبيقها على طلب البحث. يمكنك الاطّلاع على ملخّص معلّمات طلب البحث في المستندات المرجعية لمعرفة التفاصيل.
يتم تلخيص التفاصيل حول المجموعة الكاملة من معرفات الموارد المنتظمة (URI) المستخدمة لكل عملية معتمدة في واجهة برمجة التطبيقات في مستند مرجع خدمة استكشاف واجهات برمجة تطبيقات Google.
في ما يلي مثالان على آلية عمل هذا الإجراء في خدمة Google APIs Discovery.
سرد جميع واجهات برمجة التطبيقات المتوافقة مع خدمة Google APIs Discovery:
GET https://discovery.googleapis.com/discovery/v1/apis
يمكنك تجربتها الآن في "مستكشف واجهات برمجة التطبيقات".
يمكنك الحصول على مستند "اقتراحات" لواجهة برمجة تطبيقات إدارة خدمة Google Cloud، الإصدار 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1