Discovery API فهرستی از APIهای Google را برای بازیابی فراداده «سند کشف» قابل خواندن توسط ماشین برای هر API ارائه می‌کند.
این سند برای توسعه دهندگانی در نظر گرفته شده است که می خواهند کتابخانه های مشتری، افزونه های IDE و ابزارهای دیگر برای تعامل با Google API بنویسند.
پیشینه خدمات کشف
مفاهیم
Google APIs Discovery Service بر اساس دو مفهوم اساسی ساخته شده است:
- فهرست APIs : فهرستی از تمام APIهایی که توسط سرویس کشف APIs پشتیبانی می شوند. هر ورودی دایرکتوری جزئیات مربوط به یک API پشتیبانی شده را نشان می دهد، از جمله نام آن، شرح مختصری از کاری که انجام می دهد، و پیوند مستندسازی . یک API می تواند چندین ورودی دایرکتوری داشته باشد، یکی برای هر یک از نسخه های پشتیبانی شده آن.
- سند کشف : توصیف قابل خواندن توسط ماشین از یک API خاص. سند Discovery سطح یک نسخه خاص از یک API را توصیف می کند. این سند جزئیاتی در مورد نحوه دسترسی به روش های مختلف هر API از طریق تماس های HTTP RESTful ارائه می دهد. یک سند Discovery شامل توضیحاتی از داده‌ها و روش‌های مرتبط با API، و همچنین اطلاعاتی در مورد دامنه‌های OAuth موجود، و توضیحات طرح‌واره‌ها، روش‌ها، پارامترها و مقادیر پارامترهای موجود است.
مدل داده
یک منبع یک موجودیت داده منفرد با یک شناسه منحصر به فرد است. Google APIs Discovery Service بر اساس مفاهیم فوق بر روی دو نوع منبع عمل می کند.
فهرست دایرکتوری APIs : لیستی از APIها
هر ورودی دایرکتوری شامل یک جفت نام / نسخه API با اطلاعات زیر است:
- اطلاعات شناسایی و توضیحات، : نام، نسخه، عنوان و توضیحات.
- اطلاعات مستندات : نمادها و پیوند اسناد.
- اطلاعات وضعیت ، از جمله برچسب‌های وضعیت، و نشانه‌ای مبنی بر اینکه آیا این نسخه ترجیحی API است یا خیر.
- پیوند سند کشف ، URI سند اکتشاف برای این API (به عنوان یک URL کامل، به عنوان مثال https://servicemanagement.googleapis.com/$discovery/rest?version=v1 ارائه شده است).
منبع سند کشف : یک توصیف قابل خواندن توسط ماشین از یک API خاص
علاوه بر اطلاعات ارائه شده در فهرست APIs، یک سند Discovery نیز شامل موارد زیر است:
- طرحواره ها، که فهرستی از طرحواره های منبع API است که داده هایی را که در هر API به آنها دسترسی دارید، توصیف می کند. طرحواره‌های سرویس کشف APIs Google بر اساس طرحواره JSON هستند.
- روش‌ها ، از جمله فهرستی از روش‌های API و پارامترهای موجود برای هر روش.
- دامنه های OAuth ، که لیستی از محدوده های OAuth موجود برای این API را مشخص می کند.
- مستندات درون خطی ، که توضیحات مختصری از طرحواره ها، روش ها، پارامترها و مقادیر پارامترهای موجود ارائه می دهد.
مجموعه دایرکتوری منفرد محفظه مفهومی منبع واحد APIs Directory و منابع سند کشف برای هر API پشتیبانی شده است.
جزئیات بیشتر در مورد منبع APIs Directory و منبع Discovery Document در استفاده از API و اسناد مرجع ارائه شده است.
عملیات
همانطور که در جدول زیر توضیح داده شده است، می‌توانید دو روش مختلف را در مجموعه‌ها و منابع موجود در Google APIs Discovery Service فراخوانی کنید.
| عمل | شرح | REST نگاشت HTTP |
|---|---|---|
| فهرست | همه API های پشتیبانی شده را فهرست می کند. | URI منبع دایرکتوری را GET کنید. |
سبک تماس
باقی مانده
عملیات سرویس اکتشاف Google APIs پشتیبانی شده مستقیماً به فعل REST HTTP GET ، همانطور که در عملیات توضیح داده شده است، نگاشت.
فرمت خاص برای URI های سرویس اکتشاف Google APIs عبارتند از:
https://discovery.googleapis.com/discovery/v1/apis?parameters
که در آن api شناسه منبع سند کشف است، و version شناسه نسخه خاص API است، و _parameters_ هر پارامتری است که باید در پرس و جو اعمال شود. برای جزئیات بیشتر به خلاصه پارامتر Query در مستندات مرجع مراجعه کنید
جزئیات مجموعه کامل URI های مورد استفاده برای هر عملیات پشتیبانی شده در API در سند مرجع سرویس اکتشاف Google API خلاصه شده است.
در اینجا چند نمونه از نحوه عملکرد این کار در Google APIs Discovery Service آورده شده است.
فهرست همه APIهای Google APIs Discovery Service پشتیبانی شده API:
GET https://discovery.googleapis.com/discovery/v1/apis
اکنون آن را در APIs Explorer امتحان کنید!
سند Discovery را برای Google Cloud Service Management API نسخه 1 دریافت کنید:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1