הסבר על תבניות של נתיבים

ב-API Gateway, אפשר לנתב בקשות נכנסות על סמך תבנית הנתיב. תבנית של נתיב מורכבת משלושה רכיבים עיקריים:

• התאמה מדויקת
• התאמה לתו כללי יחיד לחיפוש
• התאמה לתווים כלליים לחיפוש כפולים

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

התאמה מדויקת

נתיב עם תבנית ללא מקטעים של תו כללי יחיד או כפול (* או **) מומר להתאמה מדויקת של נתיב. לדוגמה, מפרט OpenAPI של תצורת ה-API של השער עשוי להכיל קטע כמו זה:

...
paths:
  /shelves:
    get:
      summary: List shelves
...

בדוגמה הזו, שער הכניסה יקבל רק בקשות אל /shelves ולא אל נתיבים אחרים.

הערה: לוכסנים רגילים (%2F) שעברו קידוד URL לא ייחשבו כלוכסנים רגילים בפועל, כלומר %2Fshelves לא יתאים לפעולת OpenAPI שמתוארת בהמשך המפרט.

התאמה של תו כללי יחיד לחיפוש

אם נתיב עם תבנית מכיל משתנה, פלח תו כללי יחיד ({var}), או ב-OpenAPI 2.0 בלבד, פלח תו כללי יחיד ({var=*}), השער יאפשר בקשות נכנסות שעומדות בתנאים הבאים:

• הבקשות לא מכילות לוכסן נוסף (/), כלומר המשתנה יתאים רק לפלח נתיב יחיד.
• הבקשות מכילות לפחות תו אחד.
• הבקשות עשויות להכיל לוכסן נוסף בסוף הנתיב, אם הוא מופיע שם.

הערה: כדי להרחיב משתנים, כל התווים חוץ מ-[-_.~/0-9a-zA-Z] מקודדים באחוזים.

לדוגמה, מפרט OpenAPI של תצורת ה-API של השער עשוי להכיל קטע כמו זה:

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
...

בדוגמה הזו, השער יקבל בקשות שתואמות לביטוי הרגולרי הבא:

‫

^/shelves/[^/]+/books/[^/]+/?$

הערה: אם אתם משתמשים במפרט OpenAPI 3.x, התחביר /shelves/{shelf=*}/books/{book=*} לא נתמך ויידחה.

התאמה של תווים כלליים לחיפוש כפולים

אם נתיב עם תבנית מכיל משתנה שמסומן על ידי מקטע של תו כללי כפול (למשל, {var=**}), השער יאפשר בקשות נכנסות שעומדות בתנאים הבאים:

• הבקשות יכולות להכיל כל תו, כולל לוכסנים (/).
• הבקשות יכולות להכיל 0 תווים או יותר.
• הבקשות עשויות להכיל לוכסן נוסף בסוף הנתיב, אם הוא מופיע שם.

הערה: אם אתם משתמשים במפרט OpenAPI 3.x, תחביר של תו כללי כפול לחיפוש לא אפשרי. במפרטים של OpenAPI 2.0, אפשר להשתמש במשתנים עם שני כוכביות רק בפלח האחרון של הנתיב שצוין. כלומר, אי אפשר להשתמש ב-/shelves/{shelf=**}/books/{book=**} כי {shelf=**} לא מוצהר בפלח האחרון של הנתיב. בהרחבת משתנים, כל התווים חוץ מ-[-_.~/0-9a-zA-Z] מקודדים בפורמט percent-encoded.

לדוגמה, מפרט OpenAPI של תצורת ה-API של השער עשוי להכיל קטע כמו זה:

OpenAPI 2.0

...
paths:
  /shelves/{shelf=*}/books/{book=**}:
    get:
      summary: Retrieve a book
...

‫OpenAPI 3.x

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
      parameters:
      - name: shelf
        in: path
        schema:
          type: string
      - name: book
        in: path
        schema:
          type: string
        x-google-parameter:
          pattern: '**'
...

בדוגמה הזו, השער יקבל בקשות שבהן הפרמטר book תואם לכל התווים, כולל לוכסנים. הביטוי הרגולרי הזה:

^/shelves/[^/]+/books/.*/?$

קו נטוי מקודד בכתובת URL

‫API Gateway פועל לפי RFC 3986, שלא מתייחס לקווים אלכסוניים (%2F) בכתובות URL מקודדות כאל קווים אלכסוניים בפועל כשמתאימים נתיבי כתובות URL לניתוב או להחלטות אבטחה. אם צפויים קווים אלכסוניים עם קידוד URL, מערכת ה-Backend צריכה לטפל בבקשות האלה בהתאם.

אזהרה: אם ה-Backend שלכם מצפה שקו נטוי לפנים שעבר קידוד URL ‏ (%2F) יטופל כקו נטוי אמיתי כשמתאימים תבניות נתיב של API Gateway, יכול להיות שבקשות שמכילות קו נטוי לפנים שעבר קידוד URL יתאימו לפעולות לא צפויות ויגרמו לגישה עם הרשאות יתר למשאבי ה-Backend.

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

securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
paths:
  /shelves/{shelf}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        summary: List shelves
        operationId: GetShelf
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    /shelves/{shelf}/books/{book}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        - in: path
          name: book
          type: string
          required: true
          description: Book ID
        summary: Retrieve a book
        operationId: GetBook
          responses:
            '200':
              description: A successful response
              schema:
                type: string
         security:
         - api_key: []

בדוגמה הזו, הפעולה /shelves/{shelf}/books/{book} דורשת מפתח API, אבל הפעולה /shelves/{shelf} לא מוגבלת.

במקרה שמשתמש שולח בקשה אל /shelves/shelf_1%2Fbooks%2Fbook_2:

• השער יעבד את הבקשה כפעולת GetShelf עבור מזהה המדף shelf_1%2Fbooks%2Fbook_2. במקרה הזה, לא מתבצעת בדיקה של מפתח API.
• אם ה-%2F עובר נורמליזציה לפני הטיפול בבקשה על ידי ה-backend, יכול להיות שהבקשה תעובד במקום זאת כפעולת GetBook עבור מזהה הספר book_2. במילים אחרות, תהליכי ה-Backend מעבדים את /shelves/shelf_1%2Fbooks%2Fbook_2 כ-/shelves/shelf_1/books/book_2.

בדוגמה הזו, ה-backend מצפה שהפעולה GetBook תבצע בדיקה של מפתח API בשער. עם זאת, מכיוון שהשער קרא את הבקשה כפעולת GetShelf, לא בוצעה בדיקה של מפתח API.

נורמליזציה של כמה לוכסנים סמוכים

‫API Gateway פועל לפי RFC 3986, שבו מצוין שיינתן טיפול שונה לנתיבים עם כמה לוכסנים סמוכים קדימה מאשר לנתיבים עם לוכסנים בודדים קדימה.

לדוגמה, בקשה שמכילה /shelves/// לא תנורמל על ידי השער לנתיב הבקשה /shelves/ לפני התאמה לתבנית של נתיב URI וגם לא לפני העברה לחלק האחורי שצוין.

אזהרה: אם ה-Backend שלכם מבצע נורמליזציה של נתיבי כתובות URL על ידי מיזוג של כמה לוכסנים קדימה ללוכסן אחד, יכול להיות שבקשות שמכילות כמה לוכסנים קדימה סמוכים יתאימו לפעולות לא צפויות של שער, ויגרמו לגישה עם הרשאות יתר למשאבי ה-Backend שלכם.

כללי תחביר

‫API Gateway אוכף כמה כללי אימות של תחביר לתבניות נתיבים:

• מוסכמות למתן שמות למשתנים: שמות של משתנים חייבים להתחיל באות (קטנה או גדולה) או בקו תחתון (_), ויכולים להכיל רק אותיות, מספרים, קווים תחתונים, נקודות (.) ומקפים (-).
  • תוקף: {my_var}, {var-1}, {var.name}
  • לא תקין: {1var}, {my var}
• אין אפשרות לערבב פרמטרים וערכים מילוליים: פלח נתיב יחיד לא יכול להכיל גם פרמטר וגם תווים מילוליים.
  • תוקף: /prefix/{var}
  • לא תקין: /prefix-{var}, /{var}suffix
• סיומת מותרת של שיטה בהתאמה אישית: היוצא מן הכלל היחיד לערבוב פרמטרים וערכים קבועים הוא בפלח האחרון של הנתיב, שבו מותרת סיומת של שיטה בהתאמה אישית שמתחילה בנקודתיים (:).
  • תוקף: /{var}:customMethod
  • לא תקין: /{var}:customMethod/suffix
• אין כמה פרמטרים לכל פלח: פלח יחיד של נתיב לא יכול להכיל יותר מפרמטר אחד.
  • תוקף: /{var1}/{var2}
  • לא תקין: /{var1}{var2}
• אין פרמטרים מקוננים: אי אפשר לקנן פרמטרים אחד בתוך השני.
  • תוקף: /{var}
  • לא תקין: /{{var}}
• תו כללי כפול: פלחים עם תו כללי כפול יכולים להיות רק בפלח הנתיב האחרון.
  • תוקף: /prefix/{var=**}, /prefix/**
  • לא תקין: /{var=**}/suffix, /**/suffix

מגבלות

הגבלה	ערך
מספר הפרמטרים בכל נתיב	60
אורך שם המשתנה	100
אורך הנתיב (עם או בלי תבניות)	512