מסמך Discovery

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

שיטות

מסמך ה-Discovery מתמקד בשיטת RESTful להפעלת API. השיטה discovery.apis.list מחזירה את הרשימה של כל ממשקי ה-API שנתמכים על ידי שירות Google APIs Discovery, כולל כתובות URL לאחזור מסמכי Discovery המבוססים על REST.

list
אחזור של רשימת ממשקי ה-API הנתמכים בנקודת הקצה הזו.

ייצוגי משאבים

{
  "kind": "discovery#restDescription",
  "discoveryVersion": "v1",
  "id": string,
  "name": string,
  "canonicalName": string,
  "version": string,
  "revision": string,
  "title": string,
  "description": string,
  "icons": {
    "x16": string,
    "x32": string
  },
  "documentationLink": string,
  "labels": [
    string
  ],
  "protocol": "rest",
  "baseUrl": string,
  "basePath": string,
  "rootUrl": string,
  "servicePath": string,
  "batchPath": "batch",
  "parameters": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "auth": {
    "oauth2": {
      "scopes": {
        (key): {
          "description": string
        }
      }
    }
  },
  "features": [
    string
  ],
  "schemas": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "methods": {
    (key): {
      "id": string,
      "path": string,
      "httpMethod": string,
      "description": string,
      "parameters": {
        (key): {
          "id": string,
          "type": string,
          "$ref": string,
          "description": string,
          "default": string,
          "required": boolean,
          "format": string,
          "pattern": string,
          "minimum": string,
          "maximum": string,
          "enum": [
            string
          ],
          "enumDescriptions": [
            string
          ],
          "repeated": boolean,
          "location": string,
          "properties": {
            (key): (JsonSchema)
          },
          "additionalProperties": (JsonSchema),
          "items": (JsonSchema),
          "annotations": {
            "required": [
              string
            ]
          }
        }
      },
      "parameterOrder": [
        string
      ],
      "request": {
        "$ref": string
      },
      "response": {
        "$ref": string
      },
      "scopes": [
        (value)
      ],
      "supportsMediaDownload": boolean,
      "supportsMediaUpload": boolean,
      "mediaUpload": {
        "accept": [
          string
        ],
        "maxSize": string,
        "protocols": {
          "simple": {
            "multipart": true,
            "path": string
          },
          "resumable": {
            "multipart": true,
            "path": string
          }
        }
      },
      "supportsSubscription": boolean
    }
  },
  "resources": {
    (key): {
      "methods": {
        (key): {
          "id": string,
          "path": string,
          "httpMethod": string,
          "description": string,
          "parameters": {
            (key): {
              "id": string,
              "type": string,
              "$ref": string,
              "description": string,
              "default": string,
              "required": boolean,
              "format": string,
              "pattern": string,
              "minimum": string,
              "maximum": string,
              "enum": [
                string
              ],
              "enumDescriptions": [
                string
              ],
              "repeated": boolean,
              "location": string,
              "properties": {
                (key): (JsonSchema)
              },
              "additionalProperties": (JsonSchema),
              "items": (JsonSchema),
              "annotations": {
                "required": [
                  string
                ]
              }
            }
          },
          "parameterOrder": [
            string
          ],
          "request": {
            "$ref": string
          },
          "response": {
            "$ref": string
          },
          "scopes": [
            (value)
          ],
          "supportsMediaDownload": boolean,
          "supportsMediaUpload": boolean,
          "mediaUpload": {
            "accept": [
              string
            ],
            "maxSize": string,
            "protocols": {
              "simple": {
                "multipart": true,
                "path": string
              },
              "resumable": {
                "multipart": true,
                "path": string
              }
            }
          },
          "supportsSubscription": boolean
        }
      },
      "resources": {
        (key): (RestResource)
      }
    }
  }
}
שם הנכס ערך תיאור הערות
kind string סוג התגובה הזו.מחרוזת קבועה discovery#restDescription.
discoveryVersion string יש לציין את גרסת ה-API של Discovery המשמשת ליצירת המסמך.
id string מזהה מסמך ה-Discovery ל-API. לדוגמה, urlshortener:v1.
name string שם ה-API. לדוגמה, urlshortener.
canonicalName string השם הקנוני של ה-API. לדוגמה, Url Shortener.
version string גרסת ה-API. לדוגמה, v1.
revision string גרסת ה-API.
title string שם ה-API. לדוגמה, "Google Url Shortener API".
description string התיאור של ה-API.
icons object קישורים לסמלים בגודל 16x16 ו-32x32 המייצגים את ה-API.
icons.x16 string כתובת ה-URL של הסמל בגודל 16x16.
icons.x32 string כתובת ה-URL של הסמל בגודל 32x32.
labels[] list תוויות לסטטוס ה-API הזה. הערכים החוקיים הם limited_availability או deprecated.
protocol string הפרוטוקול שמתואר במסמך. לדוגמה, REST.
rootUrl string כתובת ה-URL הבסיסית מתחתיה כל שירותי ה-API.
parameters object פרמטרים נפוצים שחלים על כל ממשקי ה-API.
parameters.(key) nested object תיאור של פרמטר יחיד.
parameters.(key).id string מזהה ייחודי לסכימה הזו.
parameters.(key).type string סוג הערך של הסכימה הזו. ניתן למצוא רשימה של ערכים בקטע "type" בסכימת ה-JSON.
parameters.(key).$ref string הפניה לסכימה אחרת. הערך של המאפיין הזה הוא המזהה של סכימה אחרת.
parameters.(key).description string תיאור של האובייקט הזה.
parameters.(key).default string ערך ברירת המחדל של הנכס (אם קיים).
parameters.(key).required boolean אם הפרמטר נדרש.
parameters.(key).format string ביטוי רגולרי נוסף או מפתח שעוזר להגביל את הערך. לפרטים נוספים, ניתן לעיין בסיכום הסוג והפורמט.
parameters.(key).pattern string הביטוי הרגולרי שפרמטר זה חייב להיות תואם לו.
parameters.(key).minimum string הערך המינימלי של הפרמטר הזה.
parameters.(key).maximum string הערך המקסימלי של הפרמטר הזה.
parameters.(key).enum[] list ערכים שייתכן שהפרמטר הזה יקבל (אם הוא Enum).
parameters.(key).enumDescriptions[] list התיאורים של הקבועים. כל מיקום ממופה לערך המתאים במערך ה-enum.
parameters.(key).repeated boolean אם הפרמטר הזה עשוי להופיע כמה פעמים.
parameters.(key).location string האם הפרמטר הזה נכלל בשאילתה או בנתיב של בקשות REST.
parameters.(key).properties object אם זוהי סכימה של אובייקט, ציינו את הסכימה לכל מאפיין של אובייקט זה.
parameters.(key).properties.(key) nested object מאפיין יחיד של האובייקט הזה. הערך עצמו הוא אובייקט סכימת JSON שמתאר את הנכס הזה.
parameters.(key).additionalProperties nested object אם זו סכימה לאובייקט, הנכס הזה הוא הסכימה של נכסים נוספים עם מפתחות דינמיים לאובייקט הזה.
parameters.(key).items nested object אם זו סכימה למערך, הנכס הזה הוא הסכימה לכל רכיב במערך.
parameters.(key).annotations object מידע נוסף על הנכס הזה.
parameters.(key).annotations.required[] list רשימה של שיטות שמחייבות את הנכס הזה בבקשות.
auth object פרטי אימות.
auth.oauth2 object פרטי אימות OAuth 2.0.
auth.oauth2.scopes object היקפי ההרשאות של OAuth 2.0 הזמינים.
auth.oauth2.scopes.(key) object ערך ההיקף.
auth.oauth2.scopes.(key).description string תיאור ההיקף.
features[] list רשימה של תכונות נתמכות ל-API זה.
schemas object הסכימות של ה-API הזה.
schemas.(key) nested object תיאור של סכימה ספציפית.
schemas.(key).id string מזהה ייחודי לסכימה הזו. דוגמה: URL
schemas.(key).type string סוג הערך של הסכימה הזו. ניתן למצוא רשימה של ערכים בקטע "type" בסכימת ה-JSON.
schemas.(key).$ref string הפניה לסכימה אחרת. הערך של המאפיין הזה הוא המזהה של סכימה אחרת.
schemas.(key).description string תיאור של האובייקט הזה.
schemas.(key).default string ערך ברירת המחדל של הנכס (אם קיים).
schemas.(key).required boolean אם הפרמטר נדרש.
schemas.(key).format string ביטוי רגולרי נוסף או מפתח שעוזר להגביל את הערך.פרטים נוספים זמינים בסיכום הסוג והפורמט.
schemas.(key).pattern string הביטוי הרגולרי שפרמטר זה חייב להיות תואם לו.
schemas.(key).minimum string הערך המינימלי של הפרמטר הזה.
schemas.(key).maximum string הערך המקסימלי של הפרמטר הזה.
schemas.(key).enum[] list ערכים שייתכן שהפרמטר הזה יקבל (אם הוא Enum).
schemas.(key).enumDescriptions[] list התיאורים של הקבועים. כל מיקום ממופה לערך המתאים במערך enum.
schemas.(key).repeated boolean אם הפרמטר הזה עשוי להופיע כמה פעמים.
schemas.(key).location string האם הפרמטר הזה נכלל בשאילתה או בנתיב של בקשות REST.
schemas.(key).properties object אם זוהי סכימה של אובייקט, ציינו את הסכימה לכל מאפיין של אובייקט זה.
schemas.(key).properties.(key) nested object מאפיין יחיד של האובייקט הזה. הערך עצמו הוא אובייקט סכימת JSON שמתאר את הנכס הזה.
schemas.(key).additionalProperties nested object אם זו סכימה לאובייקט, הנכס הזה הוא הסכימה של נכסים נוספים עם מפתחות דינמיים לאובייקט הזה.
schemas.(key).items nested object אם זו סכימה למערך, הנכס הזה הוא הסכימה לכל רכיב במערך.
schemas.(key).annotations object מידע נוסף על הנכס הזה.
schemas.(key).annotations.required[] list רשימה של שיטות שמחייבות את הנכס הזה בבקשות.
methods object שיטות ברמת ה-API.
methods.(key) nested object תיאור שיטה בודדת.
methods.(key).id string מזהה ייחודי לשיטה הזו. אפשר להשתמש בנכס הזה כדי להתאים בין שיטות של Discovery.
methods.(key).description string תיאור השיטה הזו.
methods.(key).parameters object פרטים לכל הפרמטרים בשיטה הזו.
methods.(key).parameters.(key) nested object פרטים על פרמטר אחד בשיטה הזו.
methods.(key).parameters.(key).id string מזהה ייחודי לסכימה הזו.
methods.(key).parameters.(key).type string סוג הערך של הסכימה הזו. ניתן למצוא רשימה של ערכים בקטע "type" בסכימת ה-JSON.
methods.(key).parameters.(key).$ref string הפניה לסכימה אחרת. הערך של המאפיין הזה הוא המזהה של סכימה אחרת.
methods.(key).parameters.(key).description string תיאור של האובייקט הזה.
methods.(key).parameters.(key).default string ערך ברירת המחדל של הנכס (אם קיים).
methods.(key).parameters.(key).required boolean אם הפרמטר נדרש.
methods.(key).parameters.(key).format string ביטוי רגולרי נוסף או מפתח שעוזר להגביל את הערך.פרטים נוספים זמינים בסיכום הסוג והפורמט.
methods.(key).parameters.(key).pattern string הביטוי הרגולרי שפרמטר זה חייב להיות תואם לו.
methods.(key).parameters.(key).minimum string הערך המינימלי של הפרמטר הזה.
methods.(key).parameters.(key).maximum string הערך המקסימלי של הפרמטר הזה.
methods.(key).parameters.(key).enum[] list ערכים שייתכן שהפרמטר הזה יקבל (אם הוא Enum).
methods.(key).parameters.(key).enumDescriptions[] list התיאורים של הקבועים. כל מיקום ממופה לערך המתאים במערך enum.
methods.(key).parameters.(key).repeated boolean אם הפרמטר הזה עשוי להופיע כמה פעמים.
methods.(key).parameters.(key).location string האם הפרמטר הזה נכלל בשאילתה או בנתיב של בקשות REST.
methods.(key).parameters.(key).properties object אם זוהי סכימה של אובייקט, ציינו את הסכימה לכל מאפיין של אובייקט זה.
methods.(key).parameters.(key).properties.(key) nested object מאפיין יחיד של האובייקט הזה. הערך עצמו הוא אובייקט סכימת JSON שמתאר את הנכס הזה.
methods.(key).parameters.(key).additionalProperties nested object אם זו סכימה לאובייקט, הנכס הזה הוא הסכימה של נכסים נוספים עם מפתחות דינמיים לאובייקט הזה.
methods.(key).parameters.(key).items nested object אם זו סכימה למערך, הנכס הזה הוא הסכימה לכל רכיב במערך.
methods.(key).parameters.(key).annotations object מידע נוסף על הנכס הזה.
methods.(key).parameters.(key).annotations.required[] list רשימה של שיטות שבהן הנכס הזה נדרש בבקשות.
methods.(key).parameterOrder[] list רשימה ממוינת של פרמטרים נדרשים. כך הלקוחות מקבלים רמז למבנה חתימות השיטה שלהם. המערך מסודר כך שהפרמטר המשמעותי ביותר יופיע ראשון.
methods.(key).scopes[] list היקפי OAuth 2.0 החלים על השיטה הזו.
methods.(key).supportsMediaDownload boolean אם השיטה הזו תומכת בהורדות מדיה.
methods.(key).supportsMediaUpload boolean אם השיטה הזו תומכת בהעלאות מדיה.
methods.(key).mediaUpload object פרמטרים של העלאת מדיה.
methods.(key).mediaUpload.accept[] list טווחי מדיה של MIME עבור העלאות מדיה קבילות לשיטה זו.
methods.(key).mediaUpload.maxSize string גודל מקסימלי של העלאת מדיה, כגון "1MB", "2GB" או "3TB".
methods.(key).supportsSubscription boolean אם השיטה הזו תומכת במינויים.
baseUrl string [DEPRECATED] כתובת ה-URL הבסיסית לבקשות REST.
basePath string [DEPRECATED] הנתיב הבסיסי לבקשות REST.
servicePath string הנתיב הבסיסי לכל בקשות ה-REST.
batchPath string הנתיב לבקשות אצווה של REST.
methods.(key).path string נתיב ה-URI של שיטת REST זו. מיועד לשימוש בשילוב עם המאפיין servicePath ברמת ה-API.
methods.(key).httpMethod string השיטה הזו נמצאת בשימוש בשיטה הזו ב-HTTP.
methods.(key).request object הסכימה של הבקשה.
methods.(key).request.$ref string מזהה הסכימה של סכימת הבקשה.
methods.(key).request.parameterName string [הוצא משימוש] חלק מממשקי ה-API כוללים את השדה הזה מסיבות של תאימות לאחור. אפשר להתעלם ממנה ללא חשש.
methods.(key).response object הסכימה לתגובה.
methods.(key).response.$ref string מזהה הסכימה של סכימת התגובה.
methods.(key).mediaUpload.protocols object פרוטוקולים נתמכים להעלאה.
methods.(key).mediaUpload.protocols.simple object תומך בהעלאה כבקשת HTTP אחת.
methods.(key).mediaUpload.protocols.simple.multipart boolean אם נקודת הקצה תומכת בהעלאת מדיה מרובת חלקים, צריך לציין True.
methods.(key).mediaUpload.protocols.simple.path string נתיב ה-URI שישמש להעלאה. מיועד לשימוש בשילוב עם המאפיין rootURL ברמת ה-API.
methods.(key).mediaUpload.protocols.resumable object תומך בפרוטוקול להעלאת מדיה מתחדשת.
methods.(key).mediaUpload.protocols.resumable.multipart boolean true אם נקודת הקצה הזו תומכת בהעלאת מדיה מרובת חלקים.
methods.(key).mediaUpload.protocols.resumable.path string נתיב ה-URI שישמש להעלאה. מיועד לשימוש בשילוב עם המאפיין rootURL ברמת ה-API.
resources object המשאבים ב-API הזה.
resources.(key) nested object תיאור של משאב ספציפי. מכיל שיטות ומשאבי משנה הקשורים למשאב הזה.
resources.(key).methods object שיטות במשאב הזה.
resources.(key).methods.(key) nested object התיאור של כל השיטות במשאב הזה.
resources.(key).methods.(key).id string מזהה ייחודי לשיטה הזו. אפשר להשתמש בנכס הזה כדי להתאים בין שיטות של Discovery.
resources.(key).methods.(key).path string נתיב ה-URI של שיטת REST זו. מיועד לשימוש בשילוב עם המאפיין servicePath ברמת ה-API.
resources.(key).methods.(key).flatPath string נתיב ה-URI של שיטת REST זו בפורמט (RFC 6570) ללא רמה 2 ({+var}). כתוספת לנכס של path.
resources.(key).methods.(key).httpMethod string השיטה הזו נמצאת בשימוש בשיטה הזו ב-HTTP.
resources.(key).methods.(key).description string תיאור השיטה הזו.
resources.(key).methods.(key).parameters object פרטים לכל הפרמטרים בשיטה הזו.
resources.(key).methods.(key).parameters.(key) nested object פרטים על פרמטר אחד בשיטה הזו.
resources.(key).methods.(key).parameters.(key).id string מזהה ייחודי לסכימה הזו.
resources.(key).methods.(key).parameters.(key).type string סוג הערך של הסכימה הזו. ניתן למצוא רשימה של ערכים בקטע "type" בסכימת ה-JSON.
resources.(key).methods.(key).parameters.(key).$ref string הפניה לסכימה אחרת. הערך של המאפיין הזה הוא ה-"ID" של סכימה אחרת.
resources.(key).methods.(key).parameters.(key).description string תיאור של האובייקט הזה.
resources.(key).methods.(key).parameters.(key).default string ערך ברירת המחדל של הנכס (אם קיים).
resources.(key).methods.(key).parameters.(key).required boolean אם הפרמטר נדרש.
resources.(key).methods.(key).parameters.(key).format string ביטוי רגולרי נוסף או מפתח שעוזר להגביל את הערך.פרטים נוספים זמינים בסיכום הסוג והפורמט.
resources.(key).methods.(key).parameters.(key).pattern string הביטוי הרגולרי שפרמטר זה חייב להיות תואם לו.
resources.(key).methods.(key).parameters.(key).minimum string הערך המינימלי של הפרמטר הזה.
resources.(key).methods.(key).parameters.(key).maximum string הערך המקסימלי של הפרמטר הזה.
resources.(key).methods.(key).parameters.(key).enum[] list ערכים שייתכן שהפרמטר הזה יקבל (אם הוא Enum).
resources.(key).methods.(key).parameters.(key).enumDescriptions[] list התיאורים של הקבועים. כל מיקום ממופה לערך המתאים במערך enum.
resources.(key).methods.(key).parameters.(key).repeated boolean אם הפרמטר הזה עשוי להופיע כמה פעמים.
resources.(key).methods.(key).parameters.(key).location string האם הפרמטר הזה נכלל בשאילתה או בנתיב של בקשות REST.
resources.(key).methods.(key).parameters.(key).properties object אם זוהי סכימה של אובייקט, ציינו את הסכימה לכל מאפיין של אובייקט זה.
resources.(key).methods.(key).parameters.(key).properties.(key) nested object מאפיין יחיד של האובייקט הזה. הערך עצמו הוא אובייקט סכימת JSON שמתאר את הנכס הזה.
resources.(key).methods.(key).parameters.(key).additionalProperties nested object אם זו סכימה לאובייקט, הנכס הזה הוא הסכימה של נכסים נוספים עם מפתחות דינמיים לאובייקט הזה.
resources.(key).methods.(key).parameters.(key).items nested object אם זו סכימה למערך, הנכס הזה הוא הסכימה לכל רכיב במערך.
resources.(key).methods.(key).parameters.(key).annotations object מידע נוסף על הנכס הזה.
resources.(key).methods.(key).parameters.(key).annotations.required[] list רשימה של שיטות שמחייבות את הנכס הזה בבקשות.
resources.(key).methods.(key).parameterOrder[] list רשימה ממוינת של פרמטרים נדרשים. כך הלקוחות מקבלים רמז למבנה חתימות השיטה שלהם. המערך מסודר כך שהפרמטר המשמעותי ביותר יופיע ראשון.
resources.(key).methods.(key).request object הסכימה של הבקשה.
resources.(key).methods.(key).request.$ref string מזהה הסכימה של סכימת הבקשה.
resources.(key).methods.(key).response object הסכימה לתגובה.
resources.(key).methods.(key).response.$ref string מזהה הסכימה של סכימת התגובה.
resources.(key).methods.(key).scopes[] list היקפי OAuth 2.0 החלים על השיטה הזו.
resources.(key).methods.(key).supportsMediaDownload boolean אם השיטה הזו תומכת בהורדות מדיה.
resources.(key).methods.(key).supportsMediaUpload boolean אם השיטה הזו תומכת בהעלאות מדיה.
resources.(key).methods.(key).mediaUpload object פרמטרים של העלאת מדיה.
resources.(key).methods.(key).mediaUpload.accept[] list טווחי מדיה של MIME עבור העלאות מדיה קבילות לשיטה זו.
resources.(key).methods.(key).mediaUpload.maxSize string גודל מקסימלי של העלאת מדיה, כגון "1MB", "2GB" או "3TB".
resources.(key).methods.(key).mediaUpload.protocols object פרוטוקולים נתמכים להעלאה.
resources.(key).methods.(key).mediaUpload.protocols.simple object תומך בהעלאה כבקשת HTTP אחת.
resources.(key).methods.(key).mediaUpload.protocols.simple.multipart boolean true אם נקודת הקצה הזו תומכת בהעלאת מדיה מרובת חלקים.
resources.(key).methods.(key).mediaUpload.protocols.simple.path string נתיב ה-URI שישמש להעלאה. מיועד לשימוש בשילוב עם המאפיין rootURL ברמת ה-API.
resources.(key).methods.(key).mediaUpload.protocols.resumable object תומך בפרוטוקול להעלאת מדיה מתחדשת.
resources.(key).methods.(key).mediaUpload.protocols.resumable.multipart boolean true אם נקודת הקצה הזו תומכת בהעלאת מדיה מרובת חלקים.
resources.(key).methods.(key).mediaUpload.protocols.resumable.path string נתיב ה-URI שישמש להעלאה. מיועד לשימוש בשילוב עם המאפיין rootURL ברמת ה-API.
resources.(key).methods.(key).supportsSubscription boolean אם השיטה הזו תומכת במינויים.
resources.(key).resources object משאבי משנה במשאב הזה.
resources.(key).resources.(key) nested object תיאור של כל משאבי המשנה במשאב הזה.