הוספת ניהול API

‫Cloud Endpoints Frameworks מספק תכונות לניהול API שדומות לתכונות שExtensible Service Proxy (ESP) מספק ל-Cloud Endpoints. ‫Endpoints Frameworks כולל API gateway מובנה, שתפקידו ליירט את כל הבקשות ולבצע את הבדיקות הנדרשות, כמו אימות, לפני העברת הבקשה אל ה-API backend. כששרת הקצה העורפי מגיב, Endpoints Frameworks אוסף נתוני טלמטריה ומדווח עליהם. אפשר לראות את המדדים של ה-API בדף Endpoints > Services בGoogle Cloud מסוף.

התכונות לניהול ממשקי API שזמינות ב-Endpoints Frameworks כוללות:

כדי שמערכת Endpoints תנהל את ה-API שלכם, אתם צריכים לפרוס מסמך OpenAPI שמתאר את ה-API באמצעות גרסה 2.0 של מפרט OpenAPI. בדף הזה מוסבר איך ליצור ולפרוס מסמך OpenAPI שמאפשר ל-Endpoints לנהל את ה-API שלכם.

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

התקנה והגדרה של תוכנה נדרשת

אם עדיין לא עשיתם זאת, מתקינים ומגדירים את Google Cloud CLI ל-Python, ומוסיפים את ספריית Endpoints Frameworks Python לספריית פרויקט ה-API כדי שהיא תועלה עם קוד ה-API בזמן הפריסה.

התקנה והגדרה של ה-CLI של gcloud ל-Python

  1. מתקינים ומפעילים את ה-CLI של gcloud:

    הורדה והתקנה של ה-CLI של gcloud

  2. מתקינים את הרכיב gcloud שכולל את התוסף App Engine ל-Python:

    gcloud components install app-engine-python

  3. מעדכנים את ה-CLI של gcloud:

    gcloud components update

  4. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:

    gcloud auth login

    תיפתח כרטיסייה חדשה בדפדפן ותתבקשו לבחור חשבון.

  5. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט. מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב- Google Cloud .

    gcloud config set project YOUR_PROJECT_ID

  6. ב-Linux, מגדירים את משתנה הסביבה ENDPOINTS_GAE_SDK לנתיב של תיקיית App Engine SDK:

    PATH_TO_CLOUD_SDK/platform/google_appengine

    מחליפים את PATH_TO_CLOUD_SDK בפלט של הפקודה הבאה:

    gcloud info --format="value(installation.sdk_root)"

הוספה של ספריית Python של Endpoints Frameworks

  1. חשוב לוודא שאפשר לקמפל תוספי C ל-Python.

    • ‫Windows: נדרשת גרסה 9.0 ומעלה של Microsoft Visual C++. אפשר להוריד את Microsoft Visual C++ Compiler ל-Python 2.7 ממרכז ההורדות של מיקרוסופט

    • מערכות הפעלה אחרות: בהתאם למערכת ההפעלה, יכול להיות שתצטרכו להתקין כלי קומפילציה (לפעמים בחבילה שנקראת build-essential) או את כותרות הפיתוח של Python (לפעמים בחבילה שנקראת python-dev).

  2. עוברים לספרייה הראשית של ה-API.

  3. יוצרים ספריית משנה בשם /lib בספרייה הראשית של ה-API:

    mkdir lib

  4. מתקינים את הספרייה:

    pip install -t lib google-endpoints --ignore-installed

יצירת מסמך OpenAPI

בספרייה הראשית של ה-API, יוצרים מסמך OpenAPI באמצעות כלי המסגרת. לדוגמה:

כיתה יחידה

בפקודה הבאה, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט. Google Cloud 

python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \
    --hostname YOUR_PROJECT_ID.appspot.com

מתעלמים מהאזהרות שמוצגות.

כיתות מרובות

אפשר לציין כמה כיתות בשורת הפקודה. ‫Endpoints יוצר מסמך OpenAPI לכל שילוב של שם וגרסה של API.

אם רוצים לפרוס כמה מחלקות API עם שמות API שונים כחלק משירות יחיד, צריך להוסיף גם את הדגל --x-google-api-name. הפעלת הדגל הזה מוסיפה הגבלות נוספות על שמות ה-API. באופן ספציפי, השמות צריכים להתאים לביטוי הרגולרי [a-z][a-z0-9]{0,39}, כלומר, השם צריך לכלול 1-40 תווים, שיכולים להיות אותיות קטנות או מספרים, למעט התו הראשון שלא יכול להיות מספר. לדוגמה:

בפקודה הבאה, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט. Google Cloud 

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname YOUR_PROJECT_ID.appspot.com \
   --x-google-api-name

מתעלמים מהאזהרות שמוצגות.

‫Endpoints משתמש בטקסט שאתם מציינים בארגומנט hostname כשם השירות. כשפורסים את ה-API ב-App Engine, נוצרת אוטומטית רשומת DNS עם שם בפורמט YOUR_PROJECT_ID.appspot.com.

פריסת מסמך OpenAPI

כיתה יחידה

gcloud endpoints services deploy echov1openapi.json

כיתות מרובות

אם יש לכם כמה מסמכי OpenAPI, צריך לציין את כולם בשורת הפקודה. לדוגמה:

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

בפעם הראשונה שמבצעים פריסה של מסמך (או מסמכים) OpenAPI, נוצר שירות Endpoints חדש בשם YOUR_PROJECT_ID.appspot.com.

בסיום מוצלח, שורה שדומה לזו מציגה את מזהה ההגדרה של השירות ואת שם השירות:

Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com

בדוגמה שלמעלה, 2017-02-13r0 הוא מזהה הגדרות השירות. המזהה של הגדרות השירות מורכב מחותמת זמן ואחריה מספר הגרסה. אם פורסים מחדש את מסמך OpenAPI, מספר התיקון גדל במזהה תצורת השירות.

אם אתם צריכים להציג שוב את מזהה הגדרת השירות, מריצים את הפקודה הבאה, אבל מחליפים את YOUR_PROJECT_ID במזהה הפרויקט של פרויקט Google Cloud :

gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com

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

פריסה מחדש של ה-API ובדיקה

  1. עורכים את הקובץ app.yaml של הפרויקט ומוסיפים את הקטע env_variables באופן הבא:

    env_variables:
  ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
  ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION

    מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud ואת YOUR_SERVICE_VERSION במזהה הגדרת השירות מהקטע הקודם. אחרי שמוסיפים את השורה הזו לקובץ app.yaml,‏ Endpoints מנהל את ה-API אחרי שפורסים מחדש את האפליקציה.

  2. פורסים מחדש את האפליקציה:

    gcloud app deploy

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

    File upload done.
Updating service [default]...done.

  4. בודקים אם הפריסה מחדש הצליחה, למשל באמצעות curl:

    curl --request POST \
    --header "Content-Type: application/json" \
    --data '{"content":"echo"}' \
    https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2

    מחליפים את echo בשם ה-API.

    התוצאות אמורות להיראות בערך כך:

    {
 "content": "echo echo"
}

  5. שולחים עוד כמה בקשות ל-API.

  6. כדי לראות את מדדי ה-API, פותחים את הדף Endpoints > Services במסוף Google Cloud של הפרויקט:

    לדף Endpoints Services