דף זה תורגם על ידי Cloud Translation API.

שימוש ב-Discovery API

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

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

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

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

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

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

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

תיאור בסיסי של ה-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 מותרים להעלאה. נקודת הקצה שמוצגת בדוגמה שלמעלה תקבל כל פורמט תמונה.

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

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

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

הורדת מדיה

אם שיטה תומכת בהורדת מדיה, כמו תמונות, אודיו או וידאו, הדבר מצוין על ידי הפרמטר 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 קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.