הגדרת Endpoints OpenAPI ל-Cloud Run באמצעות ESPv2

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

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

דיאגרמת ארכיטקטורה שבה מוצגים נקודות קצה עם ESPv2 שפועל כ-API Gateway עבור קצה עורפי של Cloud Run.

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

מעבר ל-ESPv2

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

רשימת משימות

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

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

עלויות

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

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

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

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

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

כדי להגדיר את התוסף:

  1. יצירת Google Cloud פרויקט חדש:

    1. מוודאים שיש לכם את תפקיד ה-IAM 'Project Creator' (roles/resourcemanager.projectCreator). איך מקצים תפקידים

    2. נכנסים לדף לבחירת הפרויקט במסוף Google Cloud .

      כניסה לדף לבחירת הפרויקט

    3. לוחצים על יצירת פרויקט.

    4. נותנים שם לפרויקט. רושמים או זוכרים את מזהה הפרויקט שנוצר.

    5. עורכים את שאר השדות לפי הצורך.

    6. לוחצים על יצירה.

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

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

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

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

    הורדת ה-CLI של gcloud

  5. אם לא פרסתם שירות קצה עורפי משלכם ב-Cloud Run, פועלים לפי השלבים במאמר מדריך למתחילים: פריסת קונטיינר לדוגמה שנוצר מראש כדי לבחור או ליצור פרויקט ולפרוס קצה עורפי לדוגמה. Google Cloud רושמים או זוכרים את האזור ואת מזהה הפרויקט שבהם השירות נפרס. בהמשך הדף הזה, מזהה הפרויקט הזה יופיע בתור BACKEND_PROJECT_ID. השם של השירות שנפרס נקרא BACKEND_SERVICE_NAME. כתובת ה-URL של השירותים הפרוסים האלה נקראת BACKEND_SERVICE_URL.

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

כדי להגדיר את מסמך ה-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-run.yaml. לנוחותכם, בדף הזה אנחנו מתייחסים למסמך OpenAPI לפי שם הקובץ הזה, אבל אתם יכולים לתת לו שם אחר אם אתם מעדיפים.
  2. אפליקציית ה-Backend של Cloud Run מוגדרת בקובץ openapi-run.yaml, בהגדרה x-google-backend (ב-OpenAPI 2.0) או בהגדרה x-google-api-management (ב-OpenAPI 3.x). לדוגמה:

    OpenAPI 2.0

    swagger: '2.0'
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
host: ESPv2_CLOUD_RUN_HOSTNAME
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: BACKEND_SERVICE_URL
  protocol: h2
paths:
  /hello:
    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 + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
servers:
- url: https://ESPv2_CLOUD_RUN_HOSTNAME
  x-google-endpoint: {}
x-google-api-management:
  backends:
    cloudrun_backend:
      address: BACKEND_SERVICE_URL
      protocol: h2
x-google-backend: cloudrun_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

    ההזחה חשובה בפורמט YAML. לדוגמה, השדה host (ב-OpenAPI 2.0) או האובייקט servers צריכים להיות באותה רמה כמו info.

  3. בשדה address, מחליפים את BACKEND_SERVICE_URL בכתובת ה-URL בפועל של שירות ה-Backend של Cloud Run, שנוצר בשלב 6 של לפני שמתחילים.

    בדוגמה הזו מניחים שאתם משתמשים בשירות העורפי hello שנוצר במאמר הפעלה מהירה: פריסת קונטיינר לדוגמה מוכן מראש. אם אתם משתמשים בשירות אחר של Cloud Run backend, מחליפים את BACKEND_SERVICE_URL בכתובת ה-URL של שירות Cloud Run.

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

    OpenAPI 2.0

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

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

    ‫OpenAPI 3.x

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

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

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

    title: Cloud Endpoints + Cloud Run

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

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

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

הגדרת נקודות קצה שדורשות מפתח API

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

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

כדי לבדוק את האכיפה של מפתח API באמצעות מפתח API שמשויך לפרויקט Google Cloud שלכם, פועלים לפי השלבים הבאים:

  1. מפעילים תמיכה במפתחות API בשירות. מזינים את הפקודה הבאה, כאשר:
    • ‫ESPv2_CLOUD_RUN_HOSTNAME הוא רכיב שם המארח של כתובת האתר שמוגדרת לשירות ESPv2 ב-Cloud Run. הוא משמש בשדה host של מסמך OpenAPI כדי לציין את המיקום שבו מתארח ה-API.
    gcloud services enable ESPv2_CLOUD_RUN_HOSTNAME
  2. פותחים את הקובץ openapi-run.yaml של הפרויקט.
  3. מוסיפים את סכימת האבטחה api_key בקטע securityDefinitions. ההגדרה הזו מגדירה תוכנית אבטחה בשם api_key שמחפשת את מפתח ה-API בכותרת x-api-key. 
    swagger: '2.0'
host: ESPv2_CLOUD_RUN_HOSTNAME
info:
  version: 1.0.0
  title: Cloud Endpoints + Cloud Run
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  4. כדי להחיל את תוכנית האבטחה api_key על כל שיטות ה-API, מוסיפים את ההנחיה security: - api_key: [] ברמה העליונה של הקובץ openapi-run.yaml. 
    swagger: '2.0'
host: ESPv2_CLOUD_RUN_HOSTNAME
info:
  version: 1.0.0
  title: Cloud Endpoints + Cloud Run
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
security:
  - api_key: []
  5. אם רוצים להגן על שיטות ספציפיות במקום על ה-API כולו, מוסיפים הוראה ריקה security: [] ברמה העליונה, ואז מוסיפים את ההוראה security: - api_key: [] להגדרה של השיטה הספציפית שרוצים להגן עליה. 
      paths:
    /shelves:
      get:
        summary: Lists all shelves
        operationId: listShelves
        security: []
      post:
        summary: Creates a new shelf
        operationId: createShelf
        security:
        - api_key: []
  6. אחרי שמשנים את הקובץ openapi-run.yaml, פורסים את ההגדרה המעודכנת בשירות Endpoints.

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

אם API או method של API דורשים מפתח API, צריך לספק את המפתח באמצעות פרמטר שאילתה בשם key, כמו בדוגמה הבאה של curl: 

 curl "${ESPv2_CLOUD_RUN_HOSTNAME}/echo?key=${API_KEY}"

שיטות מומלצות

אם אתם מסתמכים על מפתחות API כדי להגן על הגישה ל-API ולנתוני המשתמשים, הקפידו להגדיר את הדגל --service_control_network_fail_policy לערך close כשאתם מגדירים את אפשרויות ההפעלה של Extensible Service Proxy V2‏ (ESPv2). ערך ברירת המחדל של הדגל הוא open.

‫ESPv2 קורא ל-Service Control API כדי לאמת מפתחות API. אם יש כשלים ברשת כשמתחברים ל-Service Control API ו-ESPv2 לא יכול לאמת את מפתח ה-API, כל בקשה פוטנציאלית שנשלחת ל-API עם מפתחות שמקורם בתרמית נדחית.

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

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

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

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

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

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

    כך נוצר שירות Endpoints חדש עם השם שציינתם בשדה host בקובץ openapi-run.yaml. השירות מוגדר בהתאם למסמך OpenAPI.

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

    Service Configuration [CONFIG_ID] uploaded for service [ESPv2_CLOUD_RUN_HOSTNAME]

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

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

    מזהה הגדרות השירות מורכב מחותמת זמן של התאריך וממספר הגרסה. אם פורסים את openapi-run.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 עם האימג' החדש שיצרתם קודם. מחליפים את ESPv2_CLOUD_RUN_SERVICE_NAME באותו שם שירות של Cloud Run שבו השתמשתם כששריינתם את שם המארח בהתחלה, כמו שמתואר בקטע שמירת שם מארח ב-Cloud Run:

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

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

    gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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 הרשאה לבצע קריאה ל-Service Management ול-Service Control.
    • נכנסים לדף Cloud Run במסוף Google Cloud .

      • כניסה לדף Cloud Run

    • תוכלו לראות את מופע Cloud Run שפרסתם ואת חשבון השירות שמשויך אליו.
    • מקצים לחשבון השירות את ההרשאות הנדרשות:
      • gcloud projects add-iam-policy-binding ESPv2_PROJECT_ID \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController
    מידע נוסף זמין במאמר מהם תפקידים והרשאות?
  4. נותנים ל-ESPv2 הרשאה להפעיל את שירותי Cloud Run. מריצים את הפקודה הבאה לכל שירות. בפקודה הבאה:
    • מחליפים את BACKEND_SERVICE_NAME בשם של שירות לקצה העורפי של Cloud Run שמופעל. אם אתם משתמשים בשירות הקצה העורפי שנוצר במדריך למתחילים: פריסת קונטיינר לדוגמה מוכן מראש, אתם צריכים להשתמש בערך hello.
    • מחליפים את ESPv2_PROJECT_NUMBER במספר הפרויקט שיצרתם עבור ESPv2. אחת הדרכים למצוא את זה היא להיכנס לדף IAM במסוף Google Cloud ולחפש את חשבון השירות שמוגדר כברירת מחדל ל-Compute, שהוא חשבון השירות שמשמש בדגל member.
    gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID

מידע נוסף מופיע במאמר ניהול גישה באמצעות 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}/hello"

PowerShell

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הסרת המשאבים

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

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

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