הוספת API כספק סוגים

בדף הזה מוסבר איך להוסיף API ל-Google Cloud Deployment Manager כספק סוגים. מידע נוסף על סוגים וספקי סוגים מופיע במאמר סקירה כללית על סוגים.

ספק סוגים חושף את כל המשאבים של API של צד שלישי ל-Deployment Manager כסוגי בסיס שאפשר להשתמש בהם בהגדרות. הסוגים האלה צריכים להיות מוגשים ישירות על ידי RESTful API שתומך ביצירה, קריאה, עדכון ומחיקה (CRUD).

אם אתם רוצים להשתמש ב-API שלא מסופק אוטומטית על ידי Google עם Deployment Manager, אתם צריכים להוסיף את ה-API כספק סוגים. אפשר להוסיף כל API כספק סוגים, כל עוד ל-API הזה יש מפרט OpenAPI (לשעבר Swagger©) או מסמך Google Discovery.

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

לפני שמתחילים

  • אם רוצים להשתמש בדוגמאות לשורת הפקודה במדריך הזה, צריך להתקין את כלי שורת הפקודה`gcloud`.
  • כדי להשתמש בדוגמאות ל-API במדריך הזה, צריך להגדיר גישה ל-API.
  • אם רוצים להשתמש בדוגמאות ל-API במדריך הזה, צריך להגדיר גישה ל-API v2beta.

הרכיבים של ספק סוגים

ספק סוגים מורכב מהרכיבים הבאים:

  • Name: השם הרצוי של ספק הסוגים. תשתמשו בשם הזה כדי להפנות לסוג ולמשאבי ה-API הרלוונטיים שלו.
  • מסמך תיאור: כתובת ה-URL של מסמך התיאור של הסוג. מסמכים נתמכים כוללים מסמכי גילוי של Google או מפרטים של OpenAPI 1.2.
  • אימות: פרטי האימות שנדרשים ל-API. אפשר לציין אימות בסיסי. אם ה-API פועל ב-Cloud Endpoints או ב-Google Kubernetes Engine‏ (GKE), אפשר להשתמש גם בפרטי הכניסה של חשבון השירות של הפרויקט לצורך אימות.
  • אפשרויות מתקדמות: מיפויים מתקדמים של קלט או אפשרויות API.

שם

השם של ספק הסוג. תשתמשו בשם הזה כדי להתייחס לסוג בהגדרות ובתבניות עתידיות. לדוגמה, אם יצרתם ספק סוגים וקראתם לו my-awesome-type-provider, תוכלו להשתמש בו בתבניות הבאות כך:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

כאשר my-project הוא מזהה הפרויקט שאליו שייך הסוג ו-some-collection הוא הנתיב למשאב ה-API שאתם יוצרים.

מסמך מאפיינים

מסמך התיאור של ספק סוגים יכול להיות מפרט OpenAPI בגרסה 1.2 או 2.0, או Google Discovery document. לדוגמה, אפשר למצוא את מסמך Discovery של Google עבור Compute Engine Beta API בכתובת ה-URL הזו:

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

רשימה מלאה של מסמכי גילוי של Google

אפשר גם להשתמש במסמכי OpenAPI 1.2 ו-OpenAPI 2.0.

אימות

אם ה-API שלכם דורש אימות, תוכלו לספק כאן את פרטי האימות. ‫Deployment Manager תומך בפרטי אימות בסיסיים, כמו שם משתמש וסיסמה. ב-Google Kubernetes Engine וב-Endpoints, אפשר להשתמש בכותרת Authorization כדי לספק אסימון גישה מחשבון השירות של הפרויקט. Google Cloud

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

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

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

אם יש לכם אשכול שפועל ב-Google Kubernetes Engine ‏ (GKE) באותו פרויקט שבו אתם משתמשים ב-Deployment Manager, אתם יכולים להוסיף את האשכול כספק סוגים ולהשתמש ב-Deployment Manager כדי לגשת ל-GKE API. במקרה כזה, אפשר לקבל את אסימון הגישה מסוג OAuth 2.0 של חשבון השירות של Google APIs בפרויקט ולספק את אסימון הגישה בכותרת Authorization. בניגוד לסעיף הקודם בנושא פרטי כניסה, אתם צריכים לספק את המיפוי הזה כקלט בבקשה שלכם:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

השיטה googleOauth2AccessToken() תקבל באופן אוטומטי אסימון גישה כשהמשתמש יתקשר לספק הסוג הזה. דוגמה מלאה מופיעה במאמר בנושא דוגמה של אשכול GKE וסוג.

אפשר להשתמש באותה שיטה כדי לבצע אימות ל-Endpoints. Google Cloud

(אופציונלי) אישור בסיס בהתאמה אישית של רשות אישורים

אם רוצים להוסיף API כספק סוגים ל-Deployment Manager, ונקודת הקצה של ה-API ב-HTTPS משתמשת באישור שלא מסופק על ידי רשות אישורים (CA) שמהימנה באופן ציבורי כדי להצפין את החיבור, אפשר להוסיף את ה-API להגדרה כמו בדוגמה הבאה:

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

כאשר my-gke-cluster הוא אשכול GKE שבו אתם משתמשים. דוגמה מפורטת מופיעה במאמר בנושא דוגמה לאשכול ספק GKE.

אפשרויות מתקדמות של סוגים

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

מידע נוסף על מיפוי קלט זמין במאמר בנושא אפשרויות מתקדמות של API.

יצירת ספק סוגים

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

gcloud

כדי ליצור ספק סוגים באמצעות CLI של gcloud, משתמשים בפקודה type-providers create:

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

where:

  • ‫[TYPE_PROVIDER_NAME] הוא השם שרוצים לתת לסוג הזה.

  • ‫[URL] היא כתובת ה-URL המוגדרת במלואה של מסמך התיאור שתומך בסוג הזה. לדוגמה:

    http://petstore.swagger.io/v2/swagger.json

אם רוצים לספק פרטי כניסה לאימות או אפשרויות מתקדמות של API, אפשר ליצור קובץ אפשרויות API בפורמט YAML ולספק אותו באמצעות הדגל --api-options-file. לדוגמה, הקובץ יכול להיראות כך:

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

הפקודה gcloud תהיה:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

אם רוצים לבצע אימות באמצעות רשות אישורים (CA) בהתאמה אישית, אפשר להוסיף את ה-CA כדגל לפקודה gcloud, כמו בדוגמה הבאה:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

כדי ליצור סוג בסיס ב-API, שולחים בקשת POST שמכילה את descriptorUrl ואת אפשרויות ההגדרה (אופציונלי) בגוף הבקשה. לדוגמה:

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

מידע נוסף זמין במאמרי העזרה בנושא השיטה insert.

בדיקה של ספק הסוגים

כדי לוודא שספק הסוג פועל כמצופה:

  1. קוראים לספק הסוג החדש בהגדרה.
  2. מטמיעים כל אוסף שסופק על ידי ספק הסוגים כדי לוודא שה-API פועל כמצופה. אוסף הוא משאב API מספק הסוג שצוין.
  3. מעדכנים כל קולקציה.
  4. מוחקים כל אוסף.

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

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

המאמרים הבאים

‎© 2016 Swagger. כל הזכויות שמורות.