תחילת השימוש ב-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 Gateway באמצעות הגדרת ה-API. פריסת API Gateway
  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, לוחצים על Enable.
  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 לניהול התנועה לקצה העורפי של 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 Config תיצור גם את ה-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 Gateway

עכשיו אתם יכולים לפרוס את ה-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

כאשר:

  • ‫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 כדי לראות את תרשימי הפעילות שלו בדף Overview. יכול להיות שיעברו כמה רגעים עד שהבקשות יופיעו בתרשימים.

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

    בדף API Gateway:

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

הסרת המשאבים

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

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