תחילת העבודה עם Cloud Endpoints Frameworks for Python

בדף הזה מוסבר איך להגדיר, לפרוס ולשלוח בקשות ל-API לדוגמה באמצעות Cloud Endpoints Frameworks for Python. ‫Endpoints Frameworks for Python משולב עם סביבת זמן הריצה הרגילה של Python 2.7 ב-App Engine. ‫Endpoints Frameworks כולל כלים, ספריות ויכולות שמאפשרים לכם ליצור ממשקי API וספריות לקוח מאפליקציית App Engine.

מטרות

במהלך העבודה עם המדריך, תוכלו להשתמש ברשימת המשימות הכללית הבאה. כדי לשלוח בקשות ל-API, צריך לבצע את כל המשימות.

  1. מגדירים Google Cloud פרויקט. לפני שמתחילים
  2. מתקינים את התוכנה הנדרשת ויוצרים אפליקציית App Engine. מידע נוסף זמין במאמר בנושא התקנה והגדרה של תוכנה נדרשת.
  3. מורידים את הקוד לדוגמה. קבלת קוד לדוגמה
  4. ליצור מסמך OpenAPI. איך מגדירים נקודות קצה
  5. פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
  6. מריצים את הדוגמה במחשב. איך מריצים את הדוגמה באופן מקומי
  7. יוצרים קצה עורפי להצגת ה-API ופורסים את ה-API. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
  8. שליחת בקשה ל-API. שליחת בקשה ל-API
  9. מעקב אחר פעילות ב-API. מידע נוסף זמין במאמר בנושא מעקב אחר פעילות של API.
  10. כדי להימנע מחיובים בחשבון Google Cloud , מידע נוסף זמין בקטע הסרת המשאבים.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.

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

  1. כדי להגדיר את סביבת הפיתוח של App Engine Standard, פועלים לפי ההוראות שבמאמר התקנת Google Cloud CLI ל-Python. חשוב לוודא שמתקינים את הרכיבים app-engine-python ו-app-engine-python-extras gcloud.
  2. מריצים את הפקודות הבאות:
    1. מעדכנים את ה-CLI של gcloud.
      gcloud components update
    2. מוודאים ש-Google Cloud CLI ‏ (gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:
      gcloud auth login
    3. בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.
    4. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט.
      gcloud config set project [YOUR_PROJECT_ID]

      מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloud. אם יש לכם פרויקטים אחרים Google Cloud ואתם רוצים להשתמש ב-gcloud כדי לנהל אותם, תוכלו לקרוא את המאמר בנושא ניהול ההגדרות האישיות של ה-CLI של gcloud.

  3. אתם צריכים אפליקציה כדי לשלוח בקשות ל-API לדוגמה.

    • משתמשי Linux ו-macOS: במדריך הזה יש דוגמה לשימוש ב-curl, שבדרך כלל מותקן מראש במערכת ההפעלה. אם אין לכם את curl, אתם יכולים להוריד אותו מcurl דף ההורדות והגרסאות.
    • משתמשי Windows: במדריך הזה יש דוגמה לשימוש ב-Invoke-WebRequest, שנתמך ב-PowerShell 3.0 ואילך.
  4. מוודאים שסביבת הפיתוח בשפת Python כוללת את pip.
  5. חשוב לוודא שאפשר לקמפל תוספי C ל-Python.
    • ‫Windows: נדרשת גרסה 9.0 ומעלה של Microsoft Visual C++. אפשר להוריד את Microsoft Visual C++ Compiler ל-Python 2.7 ממרכז ההורדות של מיקרוסופט .
    • מערכות הפעלה אחרות: בהתאם למערכת ההפעלה, יכול להיות שתצטרכו להתקין כלי קומפילציה (לפעמים בחבילה שנקראת build-essential) או את כותרות הפיתוח של Python (לפעמים בחבילה שנקראת python-dev).
  6. ב-Linux, מגדירים את משתנה הסביבה ENDPOINTS_GAE_SDK לנתיב של תיקיית App Engine SDK: [Path-to-Google-Cloud-SDK]/platform/google_appengine.

    מחליפים את [Path-to-Google-Cloud-SDK] בפלט של הפקודה הבאה:

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

  7. יוצרים אפליקציית App Engine:
    1. בוחרים את האזור שבו רוצים ליצור את אפליקציית App Engine. כדי לקבל רשימה של אזורים, מריצים את הפקודה הבאה:
      gcloud app regions list
    2. יוצרים אפליקציית App Engine באמצעות הפקודה הבאה. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloudואת [YOUR_REGION] באזור שבו רוצים ליצור את אפליקציית App Engine.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      לדוגמה:

      gcloud app create --project=example-project-12345 --region=us-central

קבלת הקוד לדוגמה

כדי לשכפל את ה-API לדוגמה מ-GitHub:

  1. משכפלים את המאגר לדוגמה ומעבירים אותו למכונה המקומית:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. עוברים לספרייה שמכילה את הקוד לדוגמה:

    cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    

הגדרת נקודות קצה

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

התקנה של ספריית Endpoints Frameworks

בקטע הזה מוסבר איך להשתמש ב-pip של Python כדי להוסיף את ספריית Endpoints Frameworks לספריית הפרויקט של ה-API לדוגמה.

כדי להוסיף את ספריית Endpoints Frameworks לדוגמה:

  1. מוודאים שאתם בספרייה הראשית של ה-API לדוגמה, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

  2. יוצרים ספריית משנה /lib בפרויקט:

    mkdir lib
    
  3. מהספרייה הראשית לדוגמה python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, מריצים את פקודת ההתקנה:

    pip install --target lib --requirement requirements.txt --ignore-installed
    

    שימו לב לנקודות הבאות:

    • יכול להיות שהפקודה pip תשתמש ב-GNU Compiler Collection ‏ (GCC) כדי לקמפל מודולים של תוספים. אם אתם משתמשים ב-macOS וזו הפעם הראשונה שאתם מריצים את GCC במערכת, יכול להיות שתצטרכו לאשר את הרישיון של Apple ל-XCode. כדי לעשות זאת, מריצים את sudo xcodebuild -license.

    • אם מותקנות במחשב כמה גרסאות של Python, צריך לוודא שמשתמשים בגרסה של pip שמתאימה לגרסת Python שבה משתמשים במדריך הזה. אי התאמה בין גרסאות (לדוגמה, pip מ-Python 3.4 בזמן השימוש ב-python מ-Python 2.7) עלולה לגרום לשגיאות שקשה להבין. במקרה הצורך, אפשר להריץ את pip כמודול Python: מחליפים את pip בפקודה הקודמת ב-python -m pip.

    • אם pip לא מצליח למצוא חבילה מתאימה כשמריצים את הפקודה, נסו לשדרג אותה על ידי הרצת pip install --upgrade pip. אחרי שהשדרוג יסתיים, נסו להריץ שוב את פקודת ההתקנה.

    • במהדורות מסוימות של Debian ו-Ubuntu, יכול להיות שהפקודה pip תיכשל עם השגיאה DistutilsOptionError. אם השגיאה הזו מוצגת, צריך להוסיף את הדגל ‎--system.

אחרי שהתהליך יסתיים בהצלחה, הספרייה lib תאוכלס בקבצים שנדרשים לבניית האפליקציה של Endpoints Frameworks.

יצירת מסמך OpenAPI

משתמשים בכלי מספריית Endpoints Frameworks כדי ליצור מסמך שמתאר את ה-API בארכיטקטורת REST של קוד הדוגמה.

כדי ליצור את מסמך OpenAPI:

  1. מוודאים שאתם נמצאים בספרייה הראשית לדוגמה:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. יוצרים את מסמך OpenAPI:

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

    מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloud . מתעלמים מהאזהרות שמוצגות. הכלי Endpoints יוצר מסמך OpenAPI בשם echov1openapi.json בספרייה הנוכחית. הכלי Endpoints נותן לקובץ שם על סמך השם והגרסה של השירות שצוינו ב-decorator‏ @endpoints.api. מידע נוסף זמין במאמר בנושא יצירת ה-API.

    ‫Endpoints משתמש בטקסט שצוין בארגומנט hostname כשם השירות. פורמט השם YOUR_PROJECT_ID.appspot.com תואם לרשומת ה-DNS שנוצרת אוטומטית כשפורסים את ה-API בחלק האחורי של App Engine. לכן במקרה הזה, שם השירות של Endpoints ושם הדומיין שמוגדר במלואו (FQDN) זהים.

בסיום מוצלח, מוצגת ההודעה הבאה: OpenAPI spec written to ./echov1openapi.json

פריסת ההגדרה של נקודות הקצה

כדי לפרוס את ההגדרה של Endpoints, משתמשים ב-Service Infrastructure, פלטפורמת השירותים הבסיסית של Google, שמשמשת את Endpoints ושירותים אחרים ליצירה ולניהול של ממשקי API ושירותים.

כדי לפרוס את קובץ התצורה:

  1. מוודאים שאתם נמצאים בספרייה הראשית של הדוגמה:
    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. מריצים את הפקודה הבאה כדי לפרוס את מסמך ה-OpenAPI שנוצר בקטע הקודם:
    gcloud endpoints services deploy echov1openapi.json

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

    במהלך היצירה וההגדרה של השירות, Service Management מציג הרבה מידע במסוף. אפשר להתעלם מהאזהרות לגבי הנתיבים ב-echov1openapi.json שלא דורשים מפתח API. בסיום הפריסה, תוצג הודעה דומה לזו:

    Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
    

    בדוגמה הקודמת, 2017-02-13-r2 הוא מזהה הגדרות השירות ו-example-project-12345.appspot.com הוא שם השירות.

    מידע נוסף מופיע בgcloud endpoints services deploy במאמרי העזרה של gcloud.

בדיקת השירותים הנדרשים

כדי לספק ניהול API, ‏ Endpoints Frameworks דורש את השירותים הבאים:
שם כותרת
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

ברוב המקרים, הפקודה gcloud endpoints services deploy מפעילה את השירותים הנדרשים האלה. עם זאת, הפקודה gcloud מסתיימת בהצלחה אבל לא מפעילה את השירותים הנדרשים בנסיבות הבאות:

  • אם השתמשתם באפליקציה של צד שלישי כמו Terraform ולא כללתם את השירותים האלה.

  • הפריסה של הגדרת ה-Endpoints בוצעה בפרויקטGoogle Cloud קיים שבו השירותים האלה הושבתו באופן מפורש.

כדי לוודא שהשירותים הנדרשים מופעלים, משתמשים בפקודה הבאה:

gcloud services list

אם השירותים הנדרשים לא מופיעים ברשימה, צריך להפעיל אותם:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

צריך גם להפעיל את שירות Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

כדי לדעת מהו ENDPOINTS_SERVICE_NAME, אפשר:

  • אחרי פריסת ההגדרה של Endpoints, נכנסים לדף Endpoints במסוף Cloud. רשימת האפשרויות האפשריות של ENDPOINTS_SERVICE_NAME מוצגת בעמודה שם השירות.

  • ב-OpenAPI, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה host במפרט OpenAPI. ב-gRPC, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה name בהגדרות של נקודות הקצה של gRPC.

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

הרצת הדוגמה באופן מקומי

אחרי פריסת ההגדרה של Endpoints, אפשר להריץ את הדוגמה באופן מקומי באמצעות שרת הפיתוח המקומי.

  1. מוודאים שאתם נמצאים בספרייה הראשית לדוגמה:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. מפעילים את שרת הפיתוח המקומי:

    dev_appserver.py ./app.yaml
    

    כברירת מחדל, שרת הפיתוח מאזין בכתובת http://localhost:8080, כפי שמצוין ביומני המסוף שמודפסים על ידי dev_appserver.py: Google Cloud

    INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
    
  3. שליחת בקשה לשרת הפיתוח המקומי:

‫Linux או Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

במהלך curl הקודמים:

  • האפשרות --data מציינת את הנתונים שיישלחו ל-API.
  • האפשרות --header מציינת שהנתונים הם בפורמט JSON.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.

ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:

{
 "message": "hello world"
}

פריסת ה-API backend

עד עכשיו פרסתם את מסמך ה-OpenAPI ב-Service Management, אבל עדיין לא פרסתם את הקוד שמפעיל את ה-backend של ה-API. בקטע הזה מוסבר איך פורסים את ה-API לדוגמה ב-App Engine.

כדי לפרוס את העורף של ה-API:

  1. מריצים את הפקודה הבאה כדי להציג את מזהה תצורת השירות:

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

    מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט. לדוגמה:

    gcloud endpoints configs list --service=example-project-12345.appspot.com
    

  2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2016-08-01r0
  • מבצעים את השינויים הבאים בקטע env_variables:
    • בשדה ENDPOINTS_SERVICE_NAME, מחליפים את YOUR-PROJECT-ID במזהה הפרויקט Google Cloud .
    • בשדה ENDPOINTS_SERVICE_VERSION, מחליפים את הטקסט במזהה של הגדרת השירות. לדוגמה:
      ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
    
  • מריצים את הפקודה הבאה:
    gcloud app deploy
  • פועלים לפי ההוראות שמוצגות במסך. ממתינים כמה רגעים עד שהפריסה תצליח, ומתעלמים מהודעות האזהרה. בסיום הפריסה, תוצג הודעה דומה לזו:
    File upload done.
    Updating service [default]...done.
    

    אם קיבלתם הודעת שגיאה, תוכלו להיעזר בקטע פתרון בעיות במסמכי App Engine.

    מומלץ להמתין כמה דקות לפני שליחת בקשות ל-API בזמן שהאפליקציה עוברת אתחול מלא ב-App Engine.

  • שליחת בקשה ל-API לדוגמה

    ‫Linux או Mac OS

    שליחת בקשת HTTP באמצעות curl. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב-Google Cloud :

    curl \
        --request POST \
        --header "Content-Type: application/json" \
        --data '{"message":"hello world"}' \
        https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
    

    במהלך curl הקודמים:

    • האפשרות --data מציינת את הנתונים שיישלחו ל-API.
    • האפשרות --header מציינת שהנתונים הם בפורמט JSON.

    PowerShell

    שליחת בקשת HTTP באמצעות Invoke-WebRequest. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloud :

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
        -Headers @{"content-type"="application/json"} -URI `
         "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
    

    בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.

    אפליקציה של צד שלישי

    אפשר להשתמש באפליקציה של צד שלישי, כמו התוסף Postman לדפדפן Chrome, כדי לשלוח את הבקשה:

    • בוחרים באפשרות POST כפועל ה-HTTP.
    • בכותרת, בוחרים את המפתח content-type ואת הערך application/json.
    • בגוף ההודעה, מזינים את הפרטים הבאים:
      {"message":"hello world"}
    • מזינים את כתובת ה-URL של האפליקציה לדוגמה. לדוגמה:
      https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

    ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:

    {
     "message": "hello world"
    }
    

    אם לא קיבלתם תגובה, אפשר להיעזר במאמר בנושא פתרון בעיות שקשורות לתגובות.

    מעקב אחר פעילות ב-API

    1. אפשר לראות את הגרפים של הפעילות ב-API במסוף Google Cloud בדף Endpoints > Service.

      לדף Endpoints Services

      יכול להיות שיחלפו כמה רגעים עד שהבקשה תשתקף בתרשימים.

    2. מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.

      כניסה לדף Logs Explorer

    הסרת המשאבים

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

    1. במסוף Google Cloud , נכנסים לדף Manage resources.

      כניסה לדף Manage resources

    2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
    3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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