הגדרת מכסות

בדף הזה מוסבר איך להגדיר מכסות ל-API. ככלל, השלבים הם:

  1. מוסיפים את המידע על המכסה לקובץ התצורה של OpenAPI.
  2. פורסים את קובץ התצורה של OpenAPI.
  3. פורסים את Extensible Service Proxy ‏ (ESP).

מידע על מכסות

דרישות מוקדמות

כנקודת התחלה, בדף הזה מניחים שיש לכם:

הוספת מכסת שימוש למסמך OpenAPI

בתהליך הבא מוסבר איך להוסיף את התוספים הנדרשים למסמך OpenAPI כדי להגדיר מכסות. כדי לפשט את הדברים, בדף הזה נתייחס למסמך OpenAPI כאל קובץ openapi.yaml, ונספק את התוספים של OpenAPI רק בפורמט YAML.

מוסיפים את שלושת הקטעים הבאים לקובץ openapi.yaml:

  • ‫x-google-management.metrics: מדד עם שם שסופר את הבקשות ל-API. אתם נותנים שם שמתאר את המונה. השם יכול להיות קטגוריה, כמו read-requests או write-requests. לחלופין, אם מגדירים מכסה לשיטה ספציפית, כדאי לכלול את שם השיטה, לדוגמה, echo-api/echo_requests

  • ‫x-google-management.quota.limits: מייצג מגבלה אחת שניתנת לאכיפה על מדד עם שם. כאן מגדירים את מספר הבקשות המותר למדד שהגדרתם. בשלב הזה יש תמיכה רק במגבלות לפי דקה ולפי פרויקט.

  • ‫x-google-quota.metricCosts: metricCosts שיטות המיפוי של המדדים (רבים לרבים). בקשה לשיטה מקצה מונה לכל אחד מהמדדים הממופים. כשמשייכים שיטה למדד, תמיד צריך לציין עלות לבקשה. אתם יכולים להגדיר את העלות של כל שיטה בנפרד. כך אפשר להשתמש בשיטות שונות כדי לצרוך נתונים בקצב שונה מאותו מדד עם שם. אם אין לכם דרישה מורכבת למכסה, אתם יכולים להגדיר את העלות של כל מדד ל-1.

כדי להגדיר מכסות ב-API:

  1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
  2. אם עדיין לא הוספתם את ההרחבה x-google-management, מוסיפים אותה בשורש הקובץ (לא מוזחת או מקוננת) לפני הקטע שמגדיר את הנתיבים.

  3. מוסיפים את ההגדרה metrics עם הזחה מתחת ל-x-google-management.

    x-google-management:
  metrics:
    - name: "YOUR_METRIC_NAME"
      displayName: "YOUR_METRIC-DISPLAY_NAME"
      valueType: INT64
      metricKind: DELTA
    • מחליפים את YOUR_METRIC_NAME בשם שמתאר את מונה בקשות ה-API.
    • מחליפים את YOUR_METRIC_DISPLAY_NAME בטקסט שמוצג בדף Endpoints > Services > Quotas כדי לזהות את המדד.
    • השדה valueType חייב להיות INT64.
    • השדה metricKind חייב להיות DELTA.

  4. מוסיפים שדה quota באותה רמה כמו metrics, ומוסיפים שדה limits בתוך הקטע quota.

    quota:
  limits:
    - name: "YOUR_LIMIT_NAME"
      metric: "YOUR_METRIC_NAME"
      unit: "1/min/{project}"
      values:
        STANDARD: VALUE_FOR_THE_LIMIT
    • מחליפים את YOUR_LIMIT_NAME בשם שמתאר את המגבלה.
    • מחליפים את YOUR_METRIC_NAME ב-metric.name שהוגדר קודם.
    • השדה unit חייב להיות "1/min/{project}". זהו המזהה של המגבלה לדקה לכל פרויקט.
    • השדה values חייב להכיל את הערך STANDARD.
    • מחליפים את VALUE_FOR_THE_LIMIT בערך של מספר שלם. זהו מספר הבקשות שאפליקציה שמשויכת לפרויקט של צרכן Google Cloud יכולה לשלוח בדקה.

  5. אפשר גם להגדיר מדדים נוספים ומגבלות לכל מדד.

  6. בקטע paths של הקובץ openapi.yaml, מוסיפים את התוסף x-google-quota עם הזחה מתחת לכל שיטה שרוצים להחיל עליה מכסה.

    x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
    • מחליפים את YOUR_METRIC_NAME ב-metric.name שהוגדר קודם.
    • מחליפים את YOUR_METRIC_COST במספר שלם. לכל בקשה, מוסיפים למדד של מונה הבקשות את המספר שציינתם בעלות.

  7. שומרים את קובץ ה-openapi.yaml.

דוגמאות להגדרת מכסות

בדוגמאות הבאות מוצגות שלוש דרכים להגדרת מכסות ב-API.

בדוגמה הבאה אפשר לראות איך מגדירים את השדה metric:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA

בדוגמה הבאה אפשר לראות איך מגדירים את השדות quota ו-limits בקטע quota:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000

בדוגמה הבאה אפשר לראות איך מגדירים את התוסף x-google-quota בקטע paths:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          "read-requests": 1
      security:
      - api_key: []

דוגמאות נוספות ותיאורים מפורטים של התוספים x-google-management ו-x-google-quota זמינים במאמר בנושא הרחבות של OpenAPI.

פריסת קובץ openapi.yaml ו-ESP

כדי שהמכסה תיכנס לתוקף, אתם צריכים:

  1. פורסים את הקובץ openapi.yaml ב-Service Management, וכך מעדכנים את ההגדרות ב-Endpoints.
  2. פורסים את ה-ESP. השלבים לפריסת ה-ESP משתנים בהתאם לקצה העורפי שבו ה-API נפרס.

שלבים מפורטים אפשר למצוא במאמר פריסת קצה העורפי של ה-API.