תחילת העבודה עם API Gateway ו-App Engine

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

רשימת משימות

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

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

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

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

    כניסה לדף Dashboard

  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. אם לא פרסתם אפליקציית App Engine משלכם, אתם יכולים לפעול לפי השלבים שבמדריך לתחילת העבודה עם App Engine בשפה שלכם כדי להשתמש ב-Google Cloud CLI לבחירה או ליצירה של פרויקט ולפריסה של אפליקציה לדוגמה. כדאי לרשום את כתובת ה-URL של האפליקציה, את האזור ואת מזהה הפרויקט שבו האפליקציה נפרסה. Google Cloud

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

כדי להשתמש ב-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.

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

כדי לאבטח את אפליקציית App Engine, צריך להשתמש בשרת proxy לאימות זהויות (IAP) כדי לוודא שהבקשות מאומתות. התהליך הזה כולל ציון של החברים שצריכים לקבל את התפקיד IAP-secured Web App User שנדרש לפרויקט.

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

יצירת הגדרת API

כדי להשתמש ב-API Gateway לניהול התנועה אל קצה העורף של App Engine שפרסתם, צריך להגדיר תצורת API.

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

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

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

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

    OpenAPI 2.0

    # openapi-appengine.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with an App Engine backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: APP_URL
        jwt_audience: IAP_CLIENT_ID
      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 בפועל של שירות App Engine (הנתיב המלא של ה-API שנקרא). לדוגמה, https://myapp.an.r.appspot.com/hello.

      מחליפים את IAP_CLIENT_ID במזהה הלקוח ב-OAuth שיצרתם כשאתם מגדירים את IAP.

    ‫OpenAPI 3.x

    # openapi-appengine.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with an App Engine backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    appengine_backend:
      address: APP_URL
      jwtAudience: IAP_CLIENT_ID
      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: appengine_backend
paths:
  /hello:
    get:
      summary: Greet a user
      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, מחליפים את APP_URL בכתובת ה-URL בפועל של שירות App Engine (הנתיב המלא של ה-API שנקרא). לדוגמה, https://myapp.an.r.appspot.com/hello.

      מחליפים את IAP_CLIENT_ID במזהה הלקוח ב-OAuth שיצרתם כשאתם מגדירים את IAP.
  3. מזינים את הפקודה הבאה, כאשר:
    • ‫CONFIG_ID מציין את השם של הגדרת ה-API.
    • ‫API_ID מציין את השם של ה-API. אם ה-API עדיין לא קיים, הפקודה הזו יוצרת אותו.
    • ‫SERVICE_ACCOUNT_EMAIL מציין את חשבון השירות שמשמש לחתימה על אסימונים עבור שרתי קצה עורפיים שהוגדר להם אימות.
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-appengine.yaml \
 --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

כאשר:

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

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

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

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

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

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

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

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

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

לדוגמה: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

הפלט הבא אמור להתקבל:

My-AppEngineApp: Access denied for user gateway-1a2b3c@04d5e6f35FgdsT73dFrty-tp.iam.gserviceaccount.com requesting https://my-project.appspot.com/helloGET. If you should have access, contact myldap@google.com and include the full text of this message.

הצלחת, השער מנהל את הגישה לשירות הקצה העורפי של App Engine. כדי להעניק גישה לאפליקציית App Engine, צריך להגדיר חשבון שירות עם ההרשאות הנכונות לשער.

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

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

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

    כניסה לדף API Gateway

    בדף API Gateway:

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

הסרת המשאבים

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

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