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

שימוש ב-API

מבוא

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

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

אם אתם לא מכירים את המושגים של שירות Discovery של Google APIs, מומלץ לקרוא את המאמר תחילת העבודה לפני שמתחילים לקוד.

פורמט מסמך Discovery

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

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

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

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

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

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

תיאור API בסיסי

מסמך ה-Discovery מכיל קבוצה של מאפיינים ספציפיים ל-API:

"kind": "discovery#restDescription",
"name": "servicemanagement",
"version": "v1",
"title": "Service Management API",
"description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.",
"protocol": "rest",
"rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live",
"servicePath": "",

הנכסים האלה ברמת ה-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.read-only": {
        "description": "View your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management.readonly": {
        "description": "View your Google API service configuration"
      },
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "View and manage your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

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

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

הפעולות של ממשק API פועלות על אובייקטים של נתונים שנקראים resources. מסמך Discovery מבוסס על מושגי המשאבים. לכל מסמך Discovery יש קטע resources ברמה העליונה, שכולל את כל המשאבים המשויכים ל-API. לדוגמה, ה-API של Google Cloud Service Management כולל משאב services ומשאב operations ברמה העליונה של resources, למשאב services יש שלושה משאבי משנה: configs, rollouts ו-consumers:

"resources": {
  "services": {
    // Methods and sub-resources associated with the services resource
    "configs": {
      // Methods and sub-resources associated with the services.configs resource
    },
    "rollouts": {
      // Methods and sub-resources associated with the services.rollouts resource
    },
    "consumers": {
      // Methods and sub-resources associated with the services.consumers resource
    }
  },
  "operations": {
    // Methods and sub-resources associated with the operations resource
  }
}

כל קטע משאב כולל את השיטות המשויכות למשאב הזה. לדוגמה, Google Cloud Service Management API כולל שלוש שיטות המשויכות למשאב services.rollouts: get, list ו-create.

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

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

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

סכימת JSON של משאב-פריסה:

התגובה בפועל למשאב ההשקה:

{
  "Rollout": {
    "id": "Rollout",
    "type": "object",
    "description": "...",
    "properties": {
      "serviceName": {
        "type": "string",
        "description": "..."
      },
      "rolloutId": {
        "type": "string",
        "description": "..."
      },
      "status": {
        "type": "string",
        "enum": [
          "ROLLOUT_STATUS_UNSPECIFIED",
          "IN_PROGRESS",
          "SUCCESS",
          "CANCELLED",
          "FAILED",
          "PENDING",
          "FAILED_ROLLED_BACK"
        ],
        "enumDescriptions": [
          ...
        ],
        "description": "..."
      },
      "trafficPercentStrategy": {
        "$ref": "TrafficPercentStrategy",
        "description": "..."
      },
      "deleteServiceStrategy": { ... },
      "createTime": { ... },
      "createdBy": { ... }
    }
  }
}

{
  "serviceName": "discovery.googleapis.com",
  "rolloutId": "2020-01-01R0",
  "status": "SUCCESS",
  "trafficPercentStrategy":{
    "precentages":{
      "2019-12-01R0": 70.00,
      "2019-11-01R0": 30.00
    }
  }
}

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

סכימות עשויות להכיל גם הפניות לסכימות אחרות. אם אתם בונים ספריית לקוח, הדבר יכול לעזור בבניית מודל של האובייקטים של ה-API במודלים של מודל הנתונים. בדוגמה Rollout שלמעלה, הנכס trafficPercentStrategy הוא למעשה הפניה לסכימה עם המזהה TrafficPercentStrategy. אם תעיינו בקטע schemas, תראו את הסכימה TrafficPercentStrategy. אפשר להחליף את הערך של הסכימה הזו בנכס trafficPercentStrategy במשאב Rollout (חשוב לזכור שהתחביר של $ref מגיע ממפרט סכימת JSON).

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

שיטות

הליבה של מסמך ה-Discovery מבוססת על שיטות. שיטות הן הפעולות שניתן לבצע ב-API. הקטע methods נמצא באזורים שונים במסמך Discovery, כולל ברמה העליונה (שנקראת שיטות ברמת ה-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, list ו-create:

"methods": {
  "get": { //details about the "get" method },
  "list": { //details about the "list" method },
  "create": { //details about the "create" method }
}

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

"get": {
  "id": "servicemanagement.services.rollouts.get",
  "path": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "httpMethod": "GET",
  "description": "Gets a service configuration rollout.",
  "response": { "$ref": "Rollout" },
  "parameters": { // parameters related to the method },
  "parameterOrder": [ // parameter order related to the method ],
  "scopes": [ // OAuth 2.0 scopes applicable to this method ],
  "mediaUpload": { // optional media upload information },
},

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

טווחים

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

"scopes": [
  "https://www.googleapis.com/auth/cloud-platform",
  "https://www.googleapis.com/auth/cloud-platform.read-only",
  "https://www.googleapis.com/auth/service.management",
  "https://www.googleapis.com/auth/service.management.readonly"
]

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

בקשה ותגובה

אם לשיטה יש בקשה או גוף תגובה, הם מתועדים בקטעים request או response, בהתאמה. בדוגמה get שלמעלה, לשיטה יש גוף response:

"response": {
  "$ref": "Rollout"
}

התחביר שלמעלה מציין שגוף התגובה מוגדר באמצעות סכימת JSON עם מזהה Rollout. הסכימה הזו נמצאת בקטע סכימות ברמה העליונה. גם גוף הבקשה וגם גוף התגובה משתמשים בתחביר $ref כדי להתייחס לסכימות.

פרמטרים

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

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

בדוגמה שלמעלה, יש שני פרמטרים לשיטה get:serviceName וrolloutId. פרמטרים יכולים להופיע ב-path או בכתובת ה-URL query. המאפיין location מציין איפה נמצאת ספריית הלקוח.

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

סדר הפרמטרים

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

public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);

הערך הראשון במערך parameterOrder, serviceName, הוא גם הרכיב הראשון בחתימת השיטה. אם היו פרמטרים אחרים במערך parameterOrder, הם יופיעו אחרי הפרמטר serviceName. מערך parameterOrder מכיל רק את הפרמטרים הנדרשים, ולכן מומלץ לכלול גם דרך לציין פרמטרים אופציונליים. בדוגמה שלמעלה ניתן לראות זאת במפה של optionalParameters.

המדיה שהעלית

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

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

הקטע protocols מפרט את פרוטוקולי ההעלאה ששיטה נתמכת. הפרוטוקול simple פשוט שולח את המדיה לנקודת הקצה הנתונה בבקשת HTTP אחת. לפי הפרוטוקול resumable, נקודת הקצה שצוינה ב-URI של path תומכת בפרוטוקול ההעלאה הניתנת לחידוש. אם הנכס multipart הוא true, נקודת הקצה מקבלת העלאות מרובות חלקים. כלומר, אפשר לכלול את בקשת ה-JSON וגם את המדיה יחד בגוף משותף/קשור ולשלוח אותם יחד. חשוב לזכור שפרוטוקולים של 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.

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

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

לדוגמה, בשיטות ה-API של קבלה, הוספה או רישום של ה-API של ניהול הענן של Google, יכול להיות פרמטר 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 של הפרויקט ממסוף ה-API.
`prettyPrint`	מחזירה תגובה עם מזהים ועם מעברי שורה.	הפונקציה מחזירה את התגובה בפורמט קריא למשתמשים אם `true`. ערך ברירת המחדל: משתנה לכל API. הערך הזה הוא `false`, והוא יכול להקטין את גודל המטען הייעודי (payload) של התגובות, וכתוצאה מכך הביצועים שלו יהיו טובים יותר בסביבות מסוימות.
`quotaUser`	מוזיקה אלטרנטיבית ל`userIp`.	מאפשרת לכם לאכוף מכסות לכל משתמש מאפליקציה בצד השרת, גם במקרים שבהם כתובת ה-IP של המשתמש לא ידועה. זה יכול לקרות, לדוגמה, באפליקציות שמריצים משימות cron ב-App Engine בשם המשתמש. אתם יכולים לבחור כל מחרוזת שרירותית שמזהה משתמש באופן ייחודי, אבל היא מוגבלת ל-40 תווים. הערך `userIp` מבטל את אם שניהם מסופקים. למידע נוסף על הגבלת השימוש.
`userIp`	כתובת ה-IP של משתמש הקצה שעבורו מתבצעת קריאת ה-API.	מאפשר לך לאכוף מכסות לכל משתמש בעת קריאה ל-API מאפליקציה בצד שרת. למידע נוסף על הגבלת השימוש.

תכונות

יש מקרים שבהם ממשקי API תומכים בתכונות בהתאמה אישית מחוץ להיקף של מסמך Discovery. הנתונים האלה נאספים במערך features. מערך התכונות מכיל תווית מחרוזת עבור כל תכונה מיוחדת שנתמכת על ידי ה-API. כרגע, dataWrapper היא התכונה הנתמכת היחידה, אבל יכול להיות שבתכונות אחרות תהיה תמיכה בעתיד.

"features": dataWrapper

התכונה dataWrapper מציינת שכל הבקשות ל-API והתגובות שלהן עטפות אובייקט JSON מסוג data. זוהי תכונה של ממשקי API ישנים של Google, אבל בקרוב היא תוצא משימוש. ממשקי ה-API הבאים תומכים בתכונה dataWrapper: מנחה v1 ו-Translate v2.

בתור מפתח ספריית לקוח, אם ממשק API תומך בתכונה "dataWrapper", יש לבצע את הפעולות הבאות:

בבקשות: טוענים את משאב הבקשה באובייקט JSON מסוג data.
בתגובות: מוצאים את המשאב בתוך אובייקט JSON מסוג data.

הסכימות במסמך Discovery לא כוללות את wrapper של הנתונים, כך שצריך להוסיף ולהסיר אותן באופן מפורש. לדוגמה, נניח שיש ממשק API עם משאב בשם "foo" שנראה כך:

{
  "id": 1,
  "foo": "bar"
}

לפני שמוסיפים את המשאב הזה באמצעות ה-API, צריך להקיף אותו ברכיב נתונים:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

בצד השני, כשאתם מקבלים תגובה מה-API, הוא מכיל גם את wrapper הנתונים:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

כדי להגדיר את המשאב לפי הסכימה, צריך להסיר את 'wrapper' של הנתונים:

{
  "id": 1,
  "foo": "bar"
}

מסמכים מוטבעים

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

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

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

השלבים הבאים

יצירה של ספריית לקוחות