הגדרת Endpoints OpenAPI לסביבה רגילה עם ESPv2

בדף הזה מוסבר איך להגדיר Cloud Endpoints ל-App Engine. ‫Endpoints משתמש ב-Extensible Service Proxy V2 ‏ (ESPv2) כשער API. כדי לספק ניהול API ל-App Engine, פורסים את קונטיינר ESPv2 שנוצר מראש ב-Cloud Run. לאחר מכן מאבטחים את האפליקציה באמצעות שרת proxy לאימות זהויות (IAP) כדי שרק ESPv2 יוכל להפעיל אותה.

במקרה כזה,‏ ESPv2 מיירט את כל הבקשות לאפליקציה ומבצע את כל הבדיקות הנדרשות (כמו אימות) לפני הפעלת האפליקציה. כשהאפליקציה מגיבה, ESPv2 אוסף ומדווח על טלמטריה, כמו שמוצג באיור הבא. אפשר לראות את המדדים של האפליקציה בדף Endpoints > Services במסוף Google Cloud .

דיאגרמת ארכיטקטורה שמראה איך ESPv2 מעביר בקשות ל-App Engine.

סקירה כללית של Cloud Endpoints זמינה במאמרים מידע על Endpoints וארכיטקטורת Endpoints.

מעבר ל-ESPv2

בגרסאות קודמות של Endpoints הייתה תמיכה בשימוש ב-Extensible Service Proxy (ESP) עם Cloud Run. אם יש לכם ממשקי API קיימים שאתם רוצים להעביר ל-ESPv2, תוכלו לקרוא מידע נוסף במאמר מעבר ל-Extensible Service Proxy V2.

רשימת משימות

אפשר להשתמש ברשימת המשימות הבאה במהלך העבודה עם המדריך. כל המשימות נדרשות כדי ש-Endpoints יוכל לנהל את האפליקציה שלכם.

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

עלויות

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

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

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

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

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

כדי להגדיר:

  1. במסוף Google Cloud , נכנסים לדף Manage resources ויוצרים פרויקט.

    כניסה לדף Manage resources

  2. מוודאים שהחיוב מופעל בפרויקט.

    איך מפעילים את החיוב

  3. חשוב לרשום את מזהה הפרויקט כי תצטרכו אותו בהמשך. בהמשך הדף הזה, מזהה הפרויקט הזה יופיע בתור ESPv2_PROJECT_ID.

  4. חשוב לשמור את מספר הפרויקט כי תצטרכו אותו בהמשך. בהמשך הדף הזה, מספר הפרויקט הזה יופיע כ-ESPv2_PROJECT_NUMBER.

  5. מורידים ומתקינים את Google Cloud CLI.

    הורדת ה-CLI של gcloud

  6. אם לא פרסתם אפליקציית backend משלכם ב-App Engine, פועלים לפי השלבים שבמדריך למתחילים של App Engine. רושמים את האזור ואת מזהה הפרויקט שבהם האפליקציות נפרסות. בהמשך הדף הזה, מזהה הפרויקט הזה יופיע בתור APP_PROJECT_ID.

הגדרת רכישות מתוך האפליקציה כדי לאבטח את האפליקציה

כדי לאבטח את אפליקציית App Engine, צריך להשתמש בשרת proxy לאימות זהויות (IAP) כדי לוודא שהבקשות מאומתות.

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

בנוסף, כשמגדירים את לקוח OAuth, צריך לשים לב ל-OAuth client_id, שנקרא IAP_CLIENT_ID במדריך הזה.

שמירת שם מארח ב-Cloud Run

כדי להגדיר את מסמך ה-OpenAPI או את הגדרת שירות ה-gRPC, צריך לשריין שם מארח של Cloud Run לשירות ESPv2. כדי לשריין שם מארח, פורסים קונטיינר לדוגמה ב-Cloud Run ומשתמשים בחלק מכתובת ה-URL שנוצרה כשם המארח. בהמשך, תפרסו את קונטיינר ESPv2 באותו שירות לדוגמה של Cloud Run.

  1. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם.
    1. מתחברים לחשבון. 
      gcloud auth login
    2. בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון שיש לו תפקיד עורך או בעלים בפרויקט Google Cloud שיצרתם כדי לפרוס את ESPv2 ב-Cloud Run.
  2. מגדירים את האזור. 
    gcloud config set run/region us-central1
  3. פורסים את התמונה לדוגמה gcr.io/cloudrun/hello ב-Cloud Run. מחליפים את ESPv2_CLOUD_RUN_SERVICE_NAME בשם שרוצים לתת לשירות. 
    gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESPv2_PROJECT_ID

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

    Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at ESPv2_CLOUD_RUN_SERVICE_URL

    לדוגמה, אם מגדירים את ESPv2_CLOUD_RUN_SERVICE_NAME ל-gateway:

    Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

    בדוגמה הזו:

    • ‫ESPv2_CLOUD_RUN_SERVICE_URL היא כתובת ה-URL של השירות https://gateway-12345-uc.a.run.app
    • ‫ESPv2_CLOUD_RUN_HOSTNAME הוא שם המארח gateway-12345-uc.a.run.app.

  4. תציין את ESPv2_CLOUD_RUN_SERVICE_NAME ואת ESPv2_CLOUD_RUN_HOSTNAME. בהמשך פורסים את ESPv2 בשירות ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. מציינים את ESPv2_CLOUD_RUN_HOSTNAME בשדה host במסמך OpenAPI.

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

צריך ליצור מסמך OpenAPI שמבוסס על OpenAPI 2.0 או על OpenAPI 3.x, ומתאר את הסביבה של האפליקציות ואת דרישות האימות. מידע נוסף זמין במאמר גרסאות נתמכות של OpenAPI.

צריך גם להוסיף שדה ספציפי ל-Google שמכיל את כתובת ה-URL של כל אפליקציה, כדי של-ESPv2 יהיה המידע שהוא צריך כדי להפעיל אפליקציה. אם אתם חדשים ב-OpenAPI, תוכלו לקרוא מידע נוסף בסקירה כללית של OpenAPI.

  1. יוצרים קובץ טקסט בשם openapi-appengine.yaml. לנוחותכם, בדף הזה אנחנו מתייחסים למסמך OpenAPI לפי שם הקובץ הזה, אבל אתם יכולים לתת לו שם אחר אם אתם מעדיפים.
  2. אפליקציית ה-backend של App Engine מוגדרת בקובץ openapi-appengine.yaml, בהגדרה x-google-backend (ל-OpenAPI 2.0) או בהגדרה x-google-api-management (ל-OpenAPI 3.x). לדוגמה:

    OpenAPI 2.0

      swagger: '2.0'
  info:
    title: Cloud Endpoints + App Engine
    description: Sample API on Cloud Endpoints with an App Engine backend
    version: 1.0.0
  host: CLOUD_RUN_HOSTNAME
  schemes:
    - https
  produces:
    - application/json
  x-google-backend:
    address: https://APP_PROJECT_ID.REGION.r.appspot.com
    jwt_audience: IAP_CLIENT_ID
    protocol: h2
  paths:
    /:
      get:
        summary: Greet a user
        operationId: hello
        responses:
          '200':
            description: A successful response
            schema:
              type: string

    ‫OpenAPI 3.x

    openapi: 3.0.4
info:
  title: Cloud Endpoints + App Engine
  description: Sample API on Cloud Endpoints with an App Engine backend
  version: 1.0.0
servers:
- url: https://CLOUD_RUN_HOSTNAME
  x-google-endpoint: {}
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    appengine_backend:
      address: https://APP_PROJECT_ID.REGION.r.appspot.com
      jwtAudience: IAP_CLIENT_ID
      protocol: h2
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: appengine_backend
paths:
  /:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
    הזחה חשובה בפורמט yaml. לדוגמה, השדה host או השדה servers חייבים להיות באותה רמה כמו info.
  3. בשדה address, מחליפים את APP_PROJECT_ID בGoogle Cloud מזהה הפרויקט, את REGION ב Google Cloud אזור שבו פרסתם את App Engine ואת IAP_CLIENT_ID במזהה הלקוח ב-OAuth שיצרתם כשמגדירים את IAP.

  4. מציינים את שם המארח של השירות. הערך הנדרש תלוי בגרסה של מפרט OpenAPI שבה אתם משתמשים.

    OpenAPI 2.0

    בשדה host מציינים את CLOUD_RUN_HOSTNAME, החלק של שם המארח בכתובת ה-URL שהוזמנה בהזמנת שם מארח ב-Cloud Run. לא כוללים את מזהה הפרוטוקול, https://. לדוגמה:

    swagger: '2.0'
info:
  title: Cloud Endpoints + App Engine
  description: Sample API on Cloud Endpoints with an App Engine backend
  version: 1.0.0
host: gateway-12345-uc.a.run.app

    ‫OpenAPI 3.x

    בשדה url של האובייקט servers, מציינים את כתובת ה-URL המלאה, כולל מזהה הפרוטוקול https:// ו-CLOUD_RUN_HOSTNAME, וחלק שם המארח של כתובת ה-URL שהוזמן בהזמנת שם מארח ב-Cloud Run. לדוגמה:

    openapi: 3.0.4
info:
  title: Cloud Endpoints + App Engine
  description: Sample API on Cloud Endpoints with an App Engine backend
  version: 1.0.0
servers:
- url: https://gateway-12345-uc.a.run.app
  x-google-endpoint: {}

  5. שימו לב לערך של מאפיין title בקובץ openapi-appengine.yaml:

    title: Cloud Endpoints + App Engine

    הערך של המאפיין title הופך לשם של שירות Endpoints אחרי שפורסים את ההגדרה.

  6. שומרים את מסמך OpenAPI.

מידע על השדות במסמך OpenAPI שנדרשים ל-Endpoints מופיע במאמר בנושא הגדרת Endpoints.

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

כדי לפרוס את ההגדרה של Endpoints, משתמשים בפקודה gcloud endpoints services deploy. בפקודה הזו נעשה שימוש ב-Service Management כדי ליצור שירות מנוהל.

כדי לפרוס את ההגדרה של Endpoints:

  1. מוודאים שאתם נמצאים בספרייה שמכילה את מסמך OpenAPI.

  2. מעלים את ההגדרה ויוצרים שירות מנוהל.

    gcloud endpoints services deploy openapi-appengine.yaml \
  --project ESPv2_PROJECT_ID

    כך נוצר שירות Endpoints חדש עם השם שציינתם כשם המארח במסמך OpenAPI. השירות מוגדר בהתאם למסמך OpenAPI.

    במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. בסיום הפריסה, תוצג הודעה שדומה לזו:

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    ‫CONFIG_ID הוא המזהה הייחודי של הגדרת שירות Endpoints שנוצר על ידי הפריסה. לדוגמה:

    Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

    מזהה הגדרות השירות מורכב מחותמת זמן של התאריך וממספר הגרסה. אם פורסים את openapi-appengine.yaml שוב באותו יום, מספר הגרסה גדל במזהה תצורת השירות. אפשר לראות את הגדרות השירות ואת היסטוריית הפריסה בדף Endpoints > Services במסוף Google Cloud .

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

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

לפחות, צריך להפעיל את שירותי Google הבאים כדי להשתמש ב-Endpoints וב-ESP:
שם כותרת
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.

יצירת תמונה חדשה של ESPv2

יוצרים קובץ אימג' חדש של ESPv2 Docker מהגדרות השירות של Endpoints. בהמשך תפרסו את האימג' הזה בשירות Cloud Run השמור.

כדי ליצור את קובץ ההגדרות של השירות בקובץ אימג' חדש של ESPv2 Docker:

  1. מורידים את הסקריפט הזה למחשב המקומי שבו מותקן ה-CLI של gcloud.

  2. מריצים את הסקריפט באמצעות הפקודה הבאה: 

    chmod +x gcloud_build_image

./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESPv2_PROJECT_ID

    בשדה ESPv2_CLOUD_RUN_HOSTNAME, מציינים את שם המארח של כתובת ה-URL שהזמנתם למעלה בקטע הזמנת שם מארח ב-Cloud Run. לא כוללים את מזהה הפרוטוקול, https://.

    לדוגמה:

    chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id

  3. הסקריפט משתמש בפקודה gcloud כדי להוריד את הגדרות השירות, ליצור מהן קובץ אימג' חדש של ESPv2 ולהעלות את קובץ האימג' החדש למאגר הקונטיינרים של הפרויקט. הסקריפט משתמש אוטומטית בגרסה האחרונה של ESPv2, שמסומנת ב-ESPv2_VERSION בשם של תמונת הפלט. התמונה שנוצרה מועלית אל:

    gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID

    לדוגמה:

    gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

פריסת הקונטיינר של ESPv2

  1. פורסים את שירות ESPv2 Cloud Run עם האימג' החדש שיצרתם קודם. מחליפים את CLOUD_RUN_SERVICE_NAME באותו שם שירות של Cloud Run שבו השתמשתם כששריינתם את שם המארח במקור, כפי שמתואר במאמר שריון שם מארח ב-Cloud Run:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID

  2. אם רוצים להגדיר את Endpoints כך שישתמש באפשרויות נוספות להפעלה של ESPv2, כמו הפעלת CORS, אפשר להעביר את הארגומנטים במשתנה הסביבה ESPv2_ARGS:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESPv2_PROJECT_ID

    למידע נוסף ולדוגמאות על הגדרת משתנה הסביבה ESPv2_ARGS, כולל רשימת האפשרויות הזמינות ומידע על ציון כמה אפשרויות, אפשר לעיין במאמר Extensible Service Proxy V2 flags.

  3. נותנים ל-ESPv2 הרשאה להפעיל את האפליקציה שמאובטחת באמצעות IAP. מריצים את הפקודה הבאה לכל שירות. בפקודה הבאה:
    • מחליפים את APP_PROJECT_ID במזהה הפרויקט ב-App Engine.
    • מחליפים את ESPv2_PROJECT_NUMBER במספר הפרויקט שיצרתם עבור ESPv2. אחת הדרכים למצוא את זה היא לעבור אל מסוף IAM ולחפש את חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine, שהוא חשבון השירות שמשמש בדגל member.
      gcloud projects add-iam-policy-binding APP_PROJECT_ID \
      --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/iap.httpsResourceAccessor"

מידע נוסף זמין במאמר ניהול גישה באמצעות IAM.

שליחת בקשות ל-API

בקטע הזה נסביר איך לשלוח בקשות ל-API.

  1. יוצרים משתנה סביבה לשם של שירות Endpoints. זה השם שציינתם בשדה host במסמך OpenAPI. לדוגמה:

    • ‫Linux או macOS:

      export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

    • ‫Windows PowerShell:

      $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

‫Linux או Mac OS

משתמשים ב-curl כדי לשלוח בקשת HTTP באמצעות משתנה הסביבה ENDPOINTS_HOST שהגדרתם בשלב הקודם.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/"

PowerShell

משתמשים ב-Invoke-WebRequest כדי לשלוח בקשת HTTP באמצעות משתנה הסביבה ENDPOINTS_HOST שהגדרתם בשלב הקודם.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/").Content

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

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

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

  • בוחרים באפשרות GET כפועל ה-HTTP.
  • בכותרת, בוחרים את המפתח content-type ואת הערך application/json.

  • משתמשים בכתובת ה-URL בפועל במקום במשתנה הסביבה, לדוגמה:

    https://gateway-12345-uc.a.run.app/

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

הרגע פרסתם ובדקתם API ב-Endpoints!

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

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

    הצגת גרפים של פעילות ב-Endpoints

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

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

    הצגת יומני הבקשות של Endpoints

הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם בדף הזה, פועלים לפי השלבים הבאים:

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

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