שימוש ב-Discovery API

המסמך הזה מיועד למפתחים שרוצים לכתוב ספריות לקוח, תוספים ל-IDE וכלים אחרים לאינטראקציה עם Google APIs. ‫Google APIs Discovery Service מאפשר לכם לבצע את כל הפעולות שצוינו למעלה באמצעות חשיפה של מטא-נתונים שניתנים לקריאה על ידי מכונה לגבי ממשקי API אחרים של Google, דרך API פשוט. במדריך הזה יש סקירה כללית של כל קטע במסמך Discovery, וגם טיפים שימושיים לשימוש במסמך.

כל הקריאות ל-API הן בקשות REST לא מאומתות בפורמט JSON שמשתמשות ב-SSL – במילים אחרות, כתובות ה-URL מתחילות ב-https.

פורמט מסמך הגילוי

בקטע הזה מופיעה סקירה כללית של מסמך ה-Discovery.

כל הדוגמאות שבהמשך מבוססות על מסמך הגילוי מ-Service Usage API. אפשר לטעון את מסמך הגילוי של Service Usage API על ידי הפעלת בקשת GET הזו:

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

הפורמט של מסמך Discovery כולל מידע שמתחלק ל-6 קטגוריות עיקריות:

תיאור בסיסי של ה-API.
פרטי האימות של ה-API.
פרטים על המשאב והסכימה שמתארים את הנתונים של ה-API.
פרטים על השיטות של ה-API.
מידע על תכונות מותאמות אישית שנתמכות על ידי ה-API.
תיעוד מוטבע שמתאר את הרכיבים העיקריים של ה-API.

כל אחד מהקטעים האלה במסמך הגילוי מתואר בהמשך.

תיאור בסיסי של ה-API

מסמך ה-Discovery מכיל קבוצה של מאפיינים שספציפיים לממשק ה-API. המאפיינים האלה לא בהכרח מופיעים בסדר הזה או באותו קטע במסמך הגילוי:

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

מאפיינים ברמת ה-API כוללים פרטים על גרסה מסוימת של API, כולל name, version, title ו-description. ל-protocol תמיד יש ערך קבוע של rest, כי שירות ה-Discovery של ממשקי ה-API תומך רק בשיטות RESTful לגישה לממשקי ה-API.

השדה servicePath מציין את קידומת הנתיב של גרסת ה-API הספציפית הזו.

אימות

בקטע auth מפורטים היקפי ההרשאות של OAuth 2.0 ל-API. מידע נוסף על שימוש בהיקפי הרשאות עם OAuth 2.0 זמין במאמר שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs.

הקטע auth מכיל את הקטע המקנן oauth2 ואת הקטע scopes. הקטע scopes הוא מיפוי של מפתח/ערך מערך ההיקף לפרטים נוספים על ההיקף:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

בקטע auth מוגדרים רק היקפי הגישה של API מסוים. כדי ללמוד איך ההיקפים האלה משויכים לשיטת API, אפשר לעיין בקטע Methods שבהמשך.

משאבים וסכימות

הפעולות של API פועלות על אובייקטי נתונים שנקראים resources. מסמך ה-Discovery מבוסס על הקונספט של משאבים. לכל מסמך Discovery יש קטע resources ברמה העליונה שמקבץ את כל המשאבים שמשויכים ל-API. לדוגמה, ל-Service Usage API יש משאב services ומשאב operations ברמה העליונה resources:

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

בכל קטע של משאב מפורטות השיטות שמשויכות למשאב הזה. לדוגמה, ל-Service Usage API יש שש שיטות שמשויכות למשאב services: ‏ get,‏ enable,‏ disable,‏ batchGet,‏ batchEnable ו-list.

סכימות מראות איך נראים המשאבים ב-API. לכל מסמך Discovery יש קטע schemas ברמה העליונה, שמכיל זוג שם/ערך של מזהה סכימה לאובייקט. מזהי הסכימה הם ייחודיים לכל API, והם משמשים לזיהוי ייחודי של הסכימה בקטע methods של מסמך הגילוי. לדוגמה, הנה כמה סכימות במסמך הגילוי של Service Usage API:

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

שירות גילוי ה-API משתמש ב-JSON Schema draft-03 לייצוג הסכימה שלו. הקטע הבא הוא חלק מסכימת ה-JSON של משאב EnableServiceResponse, יחד עם GoogleApiServiceusagev1Service שאליו הוא מפנה. לצד הסכימות האלה יש חלק מתשובה בפועל לבקשה להפעלת Pub/Sub API‏ (pubsub.googleapis.com).

EnableServiceResponse סכימת JSON של משאב: תגובה בפועל להפעלת שירות:

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

השדות שמודגשים מציגים את המיפוי בין סכימת ה-JSON לבין התגובה בפועל.

כפי שרואים בדוגמה הזו, סכימות יכולות להכיל הפניות לסכימות אחרות. אם אתם בונים ספריית לקוח, זה יכול לעזור לכם ליצור מודל יעיל של האובייקטים של API בכיתות של מודל הנתונים. בדוגמה EnableServiceResponse שלמעלה, המאפיין service הוא הפניה לסכימה עם המזהה GoogleApiServiceusageV1Service, סכימה נוספת במסמך Discovery של Service Usage API. אפשר להחליף את המאפיין GoogleApiServiceusageV1Service במשאב EnableServiceResponse בערך של סכימת GoogleApiServiceusageV1Service (שימו לב שהתחביר $ref מגיע ממפרט סכימת ה-JSON).

בנוסף, יכול להיות ששיטות יפנו לסכימות כשהן מציינות את גופי הבקשה והתגובה שלהן. פרטים נוספים זמינים בקטע שיטות.

Methods

הליבה של מסמך הגילוי מבוססת על שיטות. ‫Methods הן הפעולות שאפשר לבצע ב-API. הקטע methods מופיע באזורים שונים במסמך ה-Discovery, כולל ברמה העליונה (שנקראת methods ברמת ה-API) או ברמה resources.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

ל-API יכולות להיות שיטות ברמת ה-API, אבל למשאב חייב להיות קטע methods.

כל קטע methods הוא מיפוי של זוגות מפתח/ערך משם השיטה לפרטים אחרים על השיטה הזו. בדוגמה שלמטה מתועדות שלוש שיטות, get, enable ו-disable:

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

בסוף, בכל קטע של שיטה מפורטים מאפיינים שונים של השיטה. דוגמה לשימוש במתודה enable:

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

בקטע הזה מפורטים פרטים כלליים על השיטה, כמו ID ייחודי לזיהוי השיטה, httpMethod לשימוש וpath של השיטה (לפרטים על השימוש במאפיין path לחישוב כתובת ה-URL המלאה של השיטה, אפשר לעיין בקטע יצירת בקשה). בנוסף למאפיינים הכלליים של שיטות, יש כמה מאפיינים שמקשרים את השיטה לקטעים אחרים במסמך Discovery:

היקפים

בקטע auth שהוגדר מוקדם יותר במסמכי התיעוד האלה מופיע מידע על כל היקפי ההרשאות שנתמכים על ידי API מסוים. אם שיטה תומכת באחד מההיקפים האלה, היא תכלול מערך של היקפים. במערך הזה יש רשומה אחת לכל היקף שנתמך על ידי השיטה.

שימו לב: בחירת היקף ההרשאות לשימוש באפליקציה תלויה בגורמים שונים, כמו השיטות שמופעלות והפרמטרים שנשלחים עם השיטה. לכן, המפתח הוא זה שמחליט באיזה היקף להשתמש. מסמכים של Discovery בלבד שבהם היקפי ההרשאות תקפים לשיטה.

בקשה ותגובה

אם לשיטה יש גוף בקשה או גוף תגובה, הם מתועדים בקטע request או response, בהתאמה. לדוגמה, בשיטה enable, התוכן של הקטע request מציין שהבקשה של השיטה מוגדרת על ידי סכימת JSON עם מזהה EnableServiceRequest. אפשר למצוא את הסכימה הזו בקטע של הסכימות ברמה העליונה.

פרמטרים

אם לשיטה יש פרמטרים שהמשתמש צריך לציין, הפרמטרים האלה מתועדים בקטע parameters ברמת השיטה. בקטע הזה מופיע מיפוי של שם הפרמטר לפרטים נוספים לגבי הפרמטר הזה.

לדוגמה, יש פרמטר אחד לשיטה enable: name. אפשר להוסיף פרמטרים ל-path או לכתובת ה-URL query. המאפיין location מציין איפה ספריית הלקוח צריכה למקם את הפרמטר.

יש עוד הרבה מאפיינים שמתארים את הפרמטר, כולל נתוני הפרמטר type (שימושיים בשפות עם הקלדה חזקה), אם הפרמטר הוא required ואם הפרמטר הוא enum. פרטים נוספים על המאפיינים האלה מופיעים במאמרי העזרה של ה-API הזה.

סדר הפרמטרים

יש הרבה דרכים שבהן ספריות לקוח יכולות לבנות את הממשקים שלהן. אחת הדרכים היא להשתמש ב-method עם כל פרמטר של ה-API בחתימת ה-method. עם זאת, מכיוון ש-JSON הוא פורמט לא מסודר, קשה לדעת באופן פרוגרמטי איך לסדר את הפרמטרים בחתימת השיטה. המערך parameterOrder מספק סדר קבוע של פרמטרים לשליחת בקשות. המערך מפרט את השם של כל פרמטר לפי סדר החשיבות. הוא יכול להכיל פרמטרים של נתיב או של שאילתה, אבל כל פרמטר במערך הוא חובה.

העלאת מדיה

אם שיטה תומכת בהעלאת מדיה, כמו תמונות, אודיו או וידאו, המיקום והפרוטוקולים שנתמכים להעלאת המדיה הזו מתועדים בקטע mediaUpload. בקטע הזה מפורטים פרוטוקולי ההעלאה הנתמכים וסוגי המדיה שאפשר להעלות.

השיטה enable לא מכילה את הקטע mediaUpload. אבל קטע mediaUpload טיפוסי יכול להיראות כך:

"supportsMediaUpload": true,
"mediaUpload": {
  "accept": [
    "image/*"
  ],
  "maxSize": "10MB",
  "protocols": {
    "simple": {
      "multipart": true,
      "path": "/upload/storage/v1beta1/b/{bucket}/o"
    },
    "resumable": {
      "multipart": true,
      "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
    }
  }
}

בדוגמה שלמעלה, המאפיין supportsMediaUpload הוא ערך בוליאני שקובע אם השיטה תומכת בהעלאת מדיה. אם הערך הוא true, בקטע mediaUpload מפורטים סוגי המדיה שאפשר להעלות.

המאפיין accept הוא רשימה של media-ranges שקובעים אילו סוגים של mime-types אפשר להעלות. נקודת הקצה שמוצגת בדוגמה שלמעלה תקבל כל פורמט תמונה.

הגודל של הנכס maxSize הוא הגודל המקסימלי של העלאה. הערך הוא מחרוזת ביחידות של MB, ‏ GB או TB. בדוגמה שלמעלה, ההעלאות מוגבלות לגודל מקסימלי של 10MB. שימו לב שהערך הזה לא משקף את מכסת האחסון שנותרה למשתמש ספציפי ב-API הזה. לכן, גם אם ההעלאה קטנה מ-maxSize, ספריית הלקוח עדיין צריכה להיות מוכנה לטפל בהעלאה שנכשלת בגלל חוסר מקום.

בקטע protocols מפורטים פרוטוקולי ההעלאה שנתמכים בשיטה. פרוטוקול simple פשוט שולח את המדיה לנקודת הקצה שצוינה בבקשת HTTP אחת. פרוטוקול resumable מרמז שנקודת הקצה שצוינה ב-URI של path תומכת בפרוטוקול של העלאה שניתן להמשיך. אם המאפיין multipart הוא true, נקודת הקצה מקבלת העלאות מרובות חלקים. כלומר, אפשר לארוז את בקשת ה-JSON ואת המדיה יחד בגוף mutlipart/related ולשלוח אותם יחד. הערה: יכול להיות שגם פרוטוקולי simple וגם פרוטוקולי resumable יתמכו בהעלאות מרובות חלקים.

המאפיין path הוא תבנית URI, וצריך להרחיב אותו כמו המאפיין path של השיטה, כפי שמתואר בקטע יצירת בקשה.

הורדת מדיה

אם שיטה תומכת בהורדת מדיה, כמו תמונות, אודיו או וידאו, הדבר מצוין על ידי הפרמטר supportsMediaDownload:

"supportsMediaDownload": true,

כשמורידים מדיה, צריך להגדיר את פרמטר השאילתה alt לערך media בכתובת ה-URL של הבקשה.

אם המאפיין useMediaDownloadService של שיטת ה-API הוא true, צריך להוסיף /download לפני servicePath כדי למנוע הפניה מחדש. לדוגמה, נתיב ההורדה הוא /download/youtube/v3/captions/{id} אם השרשור של servicePath ו-path הוא /youtube/v3/captions/{id}. מומלץ ליצור כתובת URL להורדת מדיה באמצעות /download גם כש-useMediaDownloadService מוגדר כ-false.

הערה: מותר ששיטת API אחת תתמוך גם בהורדה וגם בהעלאה של מדיה. הלוגיקה של בניית כתובת ה-URL של הבקשה להעלאה ולהורדה של מדיה פועלת באופן עצמאי, ולא מפריעה לפעולות אחרות. כתוצאה מכך, לשיטת API כזו תהיה כתובת URL אחת /download/... להורדת מדיה וכתובת URL אחת /upload/... להעלאת מדיה. עם זאת, אי אפשר להעלות ולהוריד מדיה בבקשה אחת.

פרמטרים נפוצים

מסמך ה-Discovery ברמה העליונה מכיל את המאפיין parameters. הקטע הזה דומה לקטע הפרמטרים של כל method, אבל אפשר להחיל את הפרמטרים האלה על כל method ב-API.

לדוגמה, לשיטות get ו-list של Service Usage API יכול להיות פרמטר prettyPrint בפרמטרים של הבקשה, שיעצב את התגובה לכל השיטות האלה בפורמט שנוח לקריאה. ריכזנו כאן רשימה של פרמטרים נפוצים:

פרמטר	משמעות	הערות	תחולת המדיניות
`access_token`	אסימון OAuth 2.0 של המשתמש הנוכחי.	דרך אפשרית אחת לספק אסימון OAuth 2.0.
`alt`	פורמט הנתונים של התשובה.	ערכים תקינים: `json`, ‏ `atom`, ‏ `csv`. ערך ברירת המחדל: משתנה בהתאם ל-API. לא כל הערכים זמינים לכל API.	ההגדרה חלה על כל הפעולות של כל המשאבים.
`callback`	פונקציית קריאה חוזרת.	השם של פונקציית הקריאה החוזרת ב-JavaScript שמטפלת בתגובה. משמש בבקשות JSON-P של JavaScript.
`fields`	בורר שמציין קבוצת משנה של שדות שייכללו בתשובה.	השתמשו בה כדי לשפר את הביצועים.
`key`	מפתח API. (חובה)	חובה, אלא אם מספקים אסימון OAuth 2.0. מפתח ה-API מזהה את הפרויקט ומאפשר לכם גישה ל-API, למכסה ולדוחות. מקבלים את מפתח ה-API של הפרויקט מ-APIs console.
`prettyPrint`	מחזירה תגובה עם כניסות ושבירות שורה.	הפונקציה מחזירה את התגובה בפורמט קריא אם `true`. ערך ברירת המחדל: משתנה בהתאם ל-API. אם הערך הוא `false`, יכול להיות שגודל מטען ייעודי (payload) של התגובה יקטן, מה שעשוי להוביל לביצועים טובים יותר בסביבות מסוימות.
`quotaUser`	חלופה ל-`userIp`.	מאפשרת לכם לאכוף מכסות לכל משתמש מאפליקציה בצד השרת, גם במקרים שבהם כתובת ה-IP של המשתמש לא ידועה. לדוגמה, זה יכול לקרות באפליקציות שמריצות משימות cron ב-App Engine בשם משתמש. אפשר לבחור מחרוזת שרירותית כלשהי שמזהה משתמש באופן ייחודי, אבל היא מוגבלת ל-40 תווים. אם מספקים את שני הערכים, הערך של `userIp` מבוטל. מידע נוסף על הגבלת השימוש
`userIp`	כתובת ה-IP של משתמש הקצה שעבורו מתבצעת הקריאה ל-API.	מאפשרת לאכוף מכסות לכל משתמש כשקוראים ל-API מאפליקציה בצד השרת. מידע נוסף על הגבלת השימוש

תיעוד מוטבע

כל מסמך Discovery כולל מספר description שדות שמספקים תיעוד מוטמע של ה-API. אפשר למצוא את השדות של description ברכיבי ה-API הבאים:

ממשק ה-API עצמו
היקפי ההרשאות של OAuth
סכימות של משאבים
שיטות API
פרמטרים של שיטה
ערכים קבילים לפרמטרים מסוימים

השדות האלה שימושיים במיוחד אם רוצים להשתמש ב-Google APIs Discovery Service כדי ליצור תיעוד שקל לקרוא בספריית לקוח – לדוגמה, JavaDoc.

שימוש ב-Discovery API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.