תחילת השימוש ב-API Gateway וב-Cloud Run

בדף הזה מוסבר איך להגדיר את API Gateway כדי לנהל ולאבטח שירות לקצה העורפי של Cloud Run.

רשימת משימות

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

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

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

  1. במסוף Google Cloud , עוברים לדף Dashboard ובוחרים פרויקט ב- Google Cloud או יוצרים אותו.

    אל לוח הבקרה

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

    הפעלת החיוב

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

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

    הורדת ה-CLI של gcloud

  5. עדכון רכיבים של gcloud:

    gcloud components update

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

    gcloud config set project PROJECT_ID

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

הפעלת שירותים נדרשים

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

שם שם השירות
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

כדי להפעיל את השירותים הנדרשים:

מסוף Google Cloud

  1. במסוף Google Cloud , נכנסים לדף APIs & Services > API Library.

    לדף API Library

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

Google Cloud CLI

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

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

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

יצירת הגדרת API

כדי להשתמש ב-API Gateway לניהול התנועה אל קצה העורף (backend) של Cloud Run שפרסתם, צריך להגדיר את ה-API.

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

פרטים נוספים על תוספי OpenAPI נתמכים זמינים במאמרים הבאים:

כדי ליצור את הגדרות ה-API:

  1. יוצרים קובץ טקסט בשם openapi-run.yaml. לנוחותכם, בדף הזה אנחנו מתייחסים לתיאור OpenAPI לפי שם הקובץ הזה, אבל אתם יכולים לתת לו שם אחר אם אתם מעדיפים.
  2. מעתיקים את התוכן של הקובץ הבא לקובץ openapi-run.yaml:

    OpenAPI 2.0

    # openapi-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string
    • בשדה title, מחליפים את API_ID בשם ה-API ואת optional-string בתיאור קצר לבחירתכם. אם ה-API שלכם עדיין לא קיים, הפקודה ליצירת הגדרת ה-API תיצור גם את ה-API עם השם שציינתם. הערך של השדה title משמש ליצירת מפתחות API שמעניקים גישה ל-API הזה. הנחיות למתן שמות ל-API מופיעות במאמר בנושא דרישות לגבי מזהה API.
    • בשדה address בקטע x-google-backend, מחליפים את APP_URL בכתובת ה-URL בפועל של שירות Cloud Run (הנתיב המלא של ה-API שנקרא). לדוגמה: https://hello-abc1def2gh-uc.a.run.app.

    ‫OpenAPI 3.x

    # openapi-run.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    cloudrun_backend:
      address: APP_URL
      deadline: 30.0
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
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
    • בשדה title, מחליפים את API_ID בשם ה-API ואת optional-string בתיאור קצר לבחירתכם. אם ה-API שלכם עדיין לא קיים, הפקודה ליצירת הגדרת ה-API תיצור גם את ה-API עם השם שציינתם. הערך של השדה title משמש ליצירת מפתחות API שמעניקים גישה ל-API הזה. הנחיות למתן שמות ל-API מופיעות במאמר בנושא דרישות לגבי מזהה API.
    • בשדה address, מחליפים את APP_URL בכתובת ה-URL בפועל של שירות Cloud Run (הנתיב המלא של ה-API שמופעל). לדוגמה: https://hello-687541448612.us-central1.run.app.
  3. מזינים את הפקודה הבאה, כאשר:
    • ‫CONFIG_ID מציין את השם של הגדרת ה-API.
    • ‫API_ID מציין את השם של ה-API. אם ה-API עדיין לא קיים, הפקודה הזו יוצרת אותו.
    • ‫PROJECT_ID מציין את שם הפרויקט ב- Google Cloud .
    • ‫SERVICE_ACCOUNT_EMAIL מציין את חשבון השירות שמשמש לחתימה על אסימונים עבור שרתי קצה עורפיים שהוגדר להם אימות. מידע נוסף מופיע במאמר יצירת חשבון שירות. 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

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

  4. אחרי שיוצרים את הגדרת ה-API, אפשר להריץ את הפקודה הבאה כדי לראות את הפרטים שלה: 
    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

פריסת שער API

עכשיו אפשר לפרוס את ה-API ב-API Gateway. פריסת API ב-API Gateway מגדירה גם כתובת URL חיצונית שבעזרתה לקוחות API יכולים לגשת ל-API שלכם.

מריצים את הפקודה הבאה כדי לפרוס את הגדרת ה-API שיצרתם ב-API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

where:

  • ‫GATEWAY_ID מציין את שם השער.
  • ‫API_ID מציין את השם של ה-API של API Gateway שמשויך לשער הזה.
  • ‫CONFIG_ID מציין את השם של הגדרת ה-API שנפרסה בשער.

  • ‫GCP_REGION הוא Google Cloud האזור של השער שנפרס.

  • ‫PROJECT_ID מציין את שם הפרויקט ב- Google Cloud .

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

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

שימו לב לערך של המאפיין defaultHostname בפלט של הפקודה הזו. זהו שם המארח של כתובת ה-URL של השער שבה תשתמשו כדי לבדוק את הפריסה בשלב הבא.

בדיקת פריסת ה-API

עכשיו אפשר לשלוח בקשות ל-API באמצעות כתובת ה-URL שנוצרה כשפרסתם את השער.

מזינים את כתובת ה-URL הבאה בדפדפן האינטרנט, כאשר:

  • ‫DEFAULT_HOSTNAME מציין את החלק של שם המארח בכתובת ה-URL של השער שפרסתם.
  • ‫hello הוא הנתיב שצוין בהגדרת ה-API.
https://DEFAULT_HOSTNAME/hello

לדוגמה: 

https://my-gateway-687541448612.us-central1.run.app/hello

הקונטיינר של Cloud Run שמריץ את האפליקציה אמור להופיע בדפדפן.

הצלחת, השער מנהל את הגישה לשירות הקצה העורפי של Cloud Run.

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

  1. אפשר לראות את הגרפים של הפעילות ב-API בדף API Gateway במסוףGoogle Cloud . לוחצים על ה-API כדי לראות את תרשימי הפעילות שלו בדף סקירה כללית. יכול להיות שיחלפו כמה רגעים עד שהבקשות יופיעו בתרשימים.

  2. מעיינים ביומני הבקשות של ה-API בדף Logs Explorer. קישור לדף Logs Explorer נמצא בדף API Gateway בGoogle Cloud מסוף.

    בדף API Gateway:

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

הסרת המשאבים

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

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