שימוש במפתחות API

בדף הזה מוסבר איך להשתמש במפתחות API ב-API Gateway.

סקירה כללית

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

אם מציינים דרישה למפתח API בהגדרות ה-API,‏ API Gateway משתמש במפתח ה-API כדי לחפש את הפרויקט המשויך Google Cloud . ‫API Gateway דוחה בקשות אלא אם מפתח ה-API נוצר בפרויקט Google Cloud או בפרויקטים אחריםGoogle Cloud שבהם הופעל ה-API.

יצירה של מפתח API

כדי ליצור מפתח API או להציג מפתחות API שכבר זמינים בפרויקט, עוברים לדף APIs & Services ‏ > Credentials ומשלימים את השלבים שמתוארים במאמר יצירת מפתח API. Google Cloud

כניסה לדף Credentials

הגדרת אימות באמצעות מפתח API ל-API Gateway

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

  1. מפעילים תמיכה במפתחות API בשירות.

    מסוףGoogle Cloud

    צריך לבצע את הפעולות הבאות:

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

      כניסה אל APIs & Services Library

    2. בסרגל החיפוש, מזינים את שם ה-API של השירות המנוהל. אפשר למצוא את הערך הזה בעמודת Managed Service של ה-API בדף הנחיתה של ממשקי ה-API. לדוגמה: 
      my-api-123abc456def1.apigateway.my-project.cloud.goog
    3. לוחצים על כרטיס השירות כדי לראות את דף הנחיתה.
    4. בדף הנחיתה של השירות, לוחצים על הפעלה.

    Google Cloud CLI

    מזינים את הפקודה הבאה, שבה MANAGED_SERVICE_NAME מציין את השם של השירות המנוהל שנוצר כשפרסתם את ה-API. אפשר לראות את המאפיין הזה ברשימת המאפיינים של השירות המנוהל באמצעות הפקודה gcloud api-gateway apis describe.

    gcloud services enable MANAGED_SERVICE_NAME

    לדוגמה:

    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. משנים את מפרט ה-OpenAPI שמשמש ליצירת הגדרות ה-API כך שיכלול הוראות לאכיפת מדיניות אבטחה של אימות מפתח API על כל התנועה. מוסיפים את הסוג security ואת הערך securityDefinitions או securitySchemes, כמו שמוצג:

    OpenAPI 2.0

      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

    ההגדרה securityDefinition קובעת שממשק ה-API ידרוש מפתח API שמועבר כפרמטר של שאילתה בשם key כשמבקשים גישה לכל הנתיבים שמוגדרים במפרט.

    ‫OpenAPI 3.x

    # openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      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: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

    התג securitySchemes מגדיר את ה-API כך שיידרש מפתח API שמועבר כפרמטר של שאילתה בשם key כשמבקשים גישה לכל הנתיבים שמוגדרים במפרט.
  3. יוצרים הגדרת API חדשה עם תיאור OpenAPI ששונה באמצעות הפקודה הבאה: 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     לדוגמה: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. מריצים את הפקודה הבאה כדי לעדכן את השער הקיים עם הגדרת ה-API החדשה: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GATEWAY_LOCATION --project=PROJECT_ID
     לדוגמה: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

הגבלת מפתחות API

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

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

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

הערה: אם אתם משתמשים בHTTP referrers (websites) כהגבלת אפליקציה, אתם צריכים לכלול סכימה (לדוגמה, https://) כשאתם מוסיפים את הגבלת האתר. לדוגמה, https://example.com/* היא הגבלה תקינה, אבל example.com/* היא לא.

כדי להוסיף הגבלות על ממשקי API:

  1. מחפשים את השם של ה-API כפי שמופיע בהגדרות ה-API. בדוגמה הבאה, שם ה-API הוא My Example Config:

    OpenAPI 2.0

    # openapi.yaml
swagger: '2.0'
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

    ‫OpenAPI 3.x

    # openapi.yaml
openapi: 3.0.4
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

  2. במסוף Google Cloud , נכנסים לדף APIs & Services > Credentials.

    כניסה לדף Credentials

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

  4. בקטע API restrictions בדף הפרטים של מפתח ה-API, לוחצים על Restrict key.

  5. בתפריט הנפתח של ממשקי ה-API הזמינים, בוחרים את ממשק ה-API שאליו רוצים לגשת באמצעות מפתח ה-API. לדוגמה, בוחרים באפשרות My Example Config.

  6. לוחצים על Save.

ההגבלה אמורה להיכנס לתוקף תוך כמה רגעים.

שימוש במפתחות API

כדי להשתמש בתכונות של API Gateway כמו מכסות, אפשר להעביר מפתח API כדי ש-API Gateway יוכל לזהות את Google Cloud הפרויקט שאליו משויכת אפליקציית הלקוח.

לדוגמה, אפשר להעביר אותו באמצעות פרמטר השאילתה key בקריאת curl, באופן הבא:

https://GATEWAY_URL/hello?key=API_KEY