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