תחילת העבודה עם API Gateway ו-Cloud Run ל-gRPC

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

רשימת משימות

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

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

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

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

    אל לוח הבקרה

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

    הפעלת החיוב

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

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

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

    הורדת ה-CLI של gcloud

  6. כדי להתקין את gRPC ואת כלי gRPC, פועלים לפי השלבים שמפורטים ב מדריך למתחילים של gRPC Python.

  7. פורסים את קצה העורפי לדוגמה python-grpc-bookstore-server, שירות gRPC Cloud Run, לשימוש במדריך הזה. שירות ה-gRPC משתמש בקובץ האימג' של הקונטיינר הבא:

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    פועלים לפי השלבים במאמר מדריך למתחילים: פריסת קונטיינר לדוגמה שנבנה מראש כדי לפרוס את השירות. חשוב להקפיד להחליף את קובץ האימג' בקונטיינר שצוין במדריך להתחלה מהירה ב-gcr.io/endpointsv2/python-grpc-bookstore-server:2

    רושמים את כתובת ה-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 באמצעות gRPC

הדוגמה bookstore-grpc כוללת את הקבצים שצריך להעתיק באופן מקומי ולהגדיר.

  1. יוצרים קובץ תיאור protobuf עצמאי מקובץ השירות .proto:
    1. שומרים עותק של bookstore.proto ממאגר הדוגמאות בספריית העבודה הנוכחית. הקובץ הזה מגדיר את ה-API של שירות חנות הספרים.
    2. יוצרים את הספרייה הבאה בספריית העבודה: mkdir generated_pb2
    3. יוצרים את קובץ התיאור, api_descriptor.pb, באמצעות קומפיילר מאגרי אחסון לפרוטוקולים protoc. מריצים את הפקודה הבאה בספרייה שבה שמרתם את bookstore.proto: 
      python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto

      בפקודה הקודמת, --proto_path מוגדר כספריית העבודה הנוכחית. בסביבת ה-build של gRPC, אם אתם משתמשים בספרייה אחרת לקובצי הקלט של .proto, צריך לשנות את --proto_path כדי שהקומפיילר יחפש בספרייה שבה שמרתם את bookstore.proto.

  2. יוצרים קובץ טקסט בשם api_config.yaml בספריית העבודה הנוכחית (אותה ספרייה שמכילה את bookstore.proto). לצורך הנוחות, בדף הזה מתייחסים למסמך ההגדרה של gRPC API לפי שם הקובץ הזה, אבל אפשר לתת לו שם אחר אם רוצים. מוסיפים את התוכן הבא לקובץ: 
    # The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app
     הזחה חשובה בפורמט yaml. לדוגמה, השדה name חייב להיות באותה רמה כמו type.
  3. בשדה name, שירות בשם *.apigateway.PROJECT_ID.cloud.goog, כאשר PROJECT_ID הוא השם של מזהה הפרויקט ב- Google Cloud .

  4. בשדה address בקטע backend.rules, מחליפים את grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app בכתובת ה-URL בפועל של שירות ה-gRPC של הקצה העורפי python-grpc-bookstore-server ב-Cloud Run, כאשר HASH הוא קוד הגיבוב הייחודי שנוצר כשיוצרים את השירות.

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

  5. שומרים את מסמך ההגדרה של gRPC API.
  6. יוצרים את הגדרות ה-API: 
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     כאשר:
    • ‫CONFIG_ID מציין את השם של הגדרת ה-API.
    • ‫API_ID מציין את השם של ה-API.
    לדוגמה: 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

פריסת שער API

כדי לפרוס את קובץ ההגדרות של gRPC API לשער, מריצים את הפקודה הבאה:

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

where:

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

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

לדוגמה:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

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

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

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

לדוגמה: 

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

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

כדי לשלוח בקשות ל-API לדוגמה, אפשר להשתמש בלקוח gRPC לדוגמה שנכתב ב-Python.

  1. משכפלים את מאגר ה-Git שבו מתארח קוד הלקוח של gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

  2. כדי לשנות את ספריית העבודה:

    cd python-docs-samples/endpoints/bookstore-grpc/

  3. יחסי תלות של התקנות:

    pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

  4. שליחת בקשה ל-API לדוגמה:

    python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

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

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

מעקב אחר פעילות 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. לוחצים על הקישור בקטע יומנים.

הרגע פרסתם ובדקתם API ב-API Gateway באמצעות gRPC!

הסרת המשאבים

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

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