Discovery API מספק רשימה של ממשקי Google API לאחזור מטא-נתונים של 'מסמך גילוי' שניתנים לקריאה על ידי מכונה לכל API.
המסמך הזה מיועד למפתחים שרוצים לכתוב ספריות לקוח, תוספים ל-IDE וכלים אחרים לאינטראקציה עם Google APIs.
רקע על שירות Discovery
מושגים
שירות הגילוי של Google APIs מבוסס על שני מושגים בסיסיים:
- APIs Directory: רשימה של כל ממשקי ה-API שנתמכים על ידי שירות גילוי ממשקי ה-API. כל רשומה בספרייה מציגה פרטים על API נתמך, כולל השם, תיאור קצר של הפעולות שהוא מבצע וקישור לתיעוד. ל-API יכולים להיות כמה רשומות בספרייה, אחת לכל גרסה נתמכת.
- מסמך Discovery: תיאור של API מסוים שניתן לקריאה על ידי מכונה. מסמך Discovery מתאר את הממשק של גרסה מסוימת של API. במסמך מוסבר איך לגשת לשיטות השונות של כל API באמצעות קריאות HTTP מסוג RESTful. מסמך Discovery כולל תיאורים של הנתונים והשיטות שמשויכים ל-API, וגם מידע על היקפי OAuth שזמינים, ותיאורים של סכימות, שיטות, פרמטרים וערכי פרמטרים שזמינים.
מודל נתונים
משאב הוא ישות נתונים נפרדת עם מזהה ייחודי. שירות הגילוי של Google APIs פועל על שני סוגים של משאבים, על סמך המושגים שלמעלה.
רשימת ממשקי API בספרייה: רשימה של ממשקי API
כל רשומה בספרייה מכילה זוג של שם/גרסה של API עם המידע הבא:
- פרטי זיהוי ותיאור: שם, גרסה, שם ותיאור.
- מידע על התיעוד: סמלים וקישור לתיעוד.
- פרטי הסטטוס, כולל תוויות סטטוס וציון אם זו הגרסה המועדפת של ה-API.
-
קישור למסמך הגילוי, ה-URI של מסמך הגילוי של ה-API הזה (מופיע ככתובת URL מלאה – לדוגמה,
https://serviceusage.googleapis.com/$discovery/rest?version=v1
).
משאב מסוג Discovery Document: תיאור של API מסוים שניתן לקריאה על ידי מכונה
בנוסף למידע שמופיע בספריית ה-API, מסמך Discovery כולל גם:
- סכימות, שהן רשימה של סכימות של משאבי API שמתארות את הנתונים שיש לכם גישה אליהם בכל API. הסכימות של Google APIs Discovery Service מבוססות על JSON Schema.
- שיטות, כולל רשימה של שיטות API ופרמטרים זמינים לכל שיטה.
- היקפי הרשאות OAuth, שמזהים את רשימת היקפי ההרשאות של OAuth שזמינים ל-API הזה.
- תיעוד מוטבע, שכולל תיאורים קצרים של סכימות, שיטות, פרמטרים וערכי פרמטרים זמינים.
אוסף הספריות היחיד הוא המאגר הרעיוני של משאב הספריות היחיד של ה-API, ושל משאבי מסמכי ה-Discovery לכל API נתמך.
תפעול
אפשר להפעיל שתי שיטות שונות באוספים ובמשאבים ב-Google APIs Discovery Service, כמו שמתואר בטבלה הבאה.
פעולה | תיאור | מיפויים של REST HTTP |
---|---|---|
list | רשימה של כל ממשקי ה-API הנתמכים. | GET ב-URI של משאב הספרייה. |
סגנון השיחה
REST
הפעולות הנתמכות של Google APIs Discovery Service ממופות ישירות לפועל HTTP GET
מסוג REST, כפי שמתואר בפעולות.
אלה הם הפורמטים שספציפיים למזהי URI של Google APIs Discovery Service:
https://API/$discovery/rest?version=VERSION
כאשר API הוא המזהה של משאב מסוג Discovery Document, ו-VERSION הוא המזהה של הגרסה הספציפית של ה-API.
הנה כמה דוגמאות שממחישות איך זה עובד בשירות הגילוי של ממשקי Google API.
רשימה של כל ממשקי ה-API שנתמכים על ידי Google APIs Discovery Service:
GET https://discovery.googleapis.com/discovery/v1/apis
רוצים לנסות עכשיו ב-APIs Explorer?
קבלת מסמך ה-Discovery של Service Usage API, גרסה 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1