Informazioni sui modelli di percorso

In API Gateway, è possibile instradare le richieste in entrata in base ai modelli di percorso. Il modello di percorso ha tre componenti principali:

• Corrispondenza esatta
• Corrispondenza con un singolo carattere jolly
• Corrispondenza con doppio carattere jolly

Le sezioni seguenti descrivono ciascuno di questi componenti e il loro funzionamento nel contesto di API Gateway.

Corrispondenza esatta

Un percorso basato su un modello senza segmenti con caratteri jolly singoli o doppi (* o **) viene convertito in una corrispondenza esatta del percorso. Ad esempio, la specifica OpenAPI per la configurazione API del gateway potrebbe contenere una sezione come la seguente:

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

In questo esempio, il gateway accetterà solo le richieste a /shelves e nessun altro percorso.

Nota: le barre codificate negli URL (%2F) non verranno trattate come barre effettive, il che significa che %2Fshelves non corrisponderà all'operazione OpenAPI descritta in precedenza nella specifica.

Corrispondenza con un solo carattere jolly

Se un percorso basato su un modello contiene una variabile, un segmento jolly singolare ({var}) o, solo in OpenAPI 2.0, un segmento jolly singolare ({var=*}), il gateway consentirà le richieste in entrata conformi a quanto segue:

• Le richieste non contengono una barra (/), il che significa che la variabile corrisponderà a un solo segmento di percorso.
• Le richieste contengono almeno un carattere.
• Le richieste potrebbero contenere una barra finale aggiuntiva se presente alla fine del percorso.

Nota: per l'espansione delle variabili, tutti i caratteri, ad eccezione di [-_.~/0-9a-zA-Z], sono codificati in percentuale.

Ad esempio, la specifica OpenAPI per la configurazione API del gateway potrebbe contenere una sezione come la seguente:

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

In questo esempio, il gateway accetterà le richieste che corrispondono alla seguente espressione regolare:

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

Nota: se utilizzi una specifica OpenAPI 3.x, la sintassi /shelves/{shelf=*}/books/{book=*} non è supportata e verrà rifiutata.

Corrispondenza con doppio carattere jolly

Se un percorso basato su un modello contiene una variabile indicata da un segmento con doppio carattere jolly (ad es.{var=**}), il gateway consentirà le richieste in entrata conformi a quanto segue:

• Le richieste possono contenere tutti i caratteri, incluse le barre (/).
• Le richieste possono contenere 0 o più caratteri.
• Le richieste potrebbero contenere una barra finale aggiuntiva se presente alla fine del percorso.

Nota: se utilizzi una specifica OpenAPI 3.x, la sintassi con doppio carattere jolly non è supportata. Per le specifiche OpenAPI 2.0, le variabili jolly doppie possono essere utilizzate solo nell'ultimo segmento del percorso fornito. Ciò significa che /shelves/{shelf=**}/books/{book=**} non è consentito perché {shelf=**} non è dichiarato nell'ultimo segmento del percorso. Per l'espansione delle variabili, tutti i caratteri, ad eccezione di [-_.~/0-9a-zA-Z], sono codificati in percentuale.

Ad esempio, la specifica OpenAPI per la configurazione API del gateway potrebbe contenere una sezione come la seguente:

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: '**'
...

In questo esempio, il gateway accetterà le richieste in cui il parametro book corrisponde a qualsiasi carattere, incluse le barre. Ciò corrisponde alla seguente espressione regolare:

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

Barre non rovesciate con codifica URL

API Gateway segue lo standard RFC 3986, che non considera le barre oblique codificate nell'URL (%2F) come barre oblique effettive quando abbina i percorsi URL per il routing o le decisioni di sicurezza. Se sono previste barre codificate nell'URL, il backend deve gestire queste richieste di conseguenza.

Avviso: se il tuo backend prevede che le barre non rovesciate codificate in URL (%2F) vengano trattate come barre effettive durante la corrispondenza dei modelli di percorso API Gateway, le richieste contenenti barre non rovesciate codificate in URL potrebbero corrispondere a operazioni impreviste e comportare un accesso con privilegi eccessivi alle risorse di backend.

Ad esempio, considera la seguente specifica 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: []

In questo esempio, l'operazione /shelves/{shelf}/books/{book} richiede una chiave API, mentre l'operazione /shelves/{shelf} non è soggetta a restrizioni.

Nel caso in cui un utente invii una richiesta a /shelves/shelf_1%2Fbooks%2Fbook_2:

• Il gateway elaborerà la richiesta come operazione GetShelf per l'ID scaffale shelf_1%2Fbooks%2Fbook_2. In questo caso, il controllo della chiave API non viene applicato.
• Se %2F viene normalizzato prima della gestione delle richieste da parte del backend, la richiesta potrebbe invece essere elaborata come operazione GetBook per l'ID libro book_2. In altre parole, il backend elabora /shelves/shelf_1%2Fbooks%2Fbook_2 come /shelves/shelf_1/books/book_2.

In questo esempio, il backend prevede che l'operazione GetBook esegua un controllo della chiave API sul gateway. Tuttavia, poiché il gateway ha letto la richiesta come operazione GetShelf, non è stato eseguito alcun controllo della chiave API.

Normalizzazione di più barre oblique consecutive

API Gateway segue lo standard RFC 3986, che stabilisce che i percorsi con più barre oblique adiacenti verranno trattati come un percorso diverso da quelli con barre oblique singole.

Ad esempio, una richiesta contenente /shelves/// non verrà normalizzata dal gateway nel percorso della richiesta /shelves/ prima di corrispondere a un modello di percorso URI né durante l'inoltro al backend specificato.

Avviso :se il backend normalizza i percorsi URL unendo più barre oblique in una sola, le richieste contenenti più barre oblique adiacenti potrebbero corrispondere a operazioni gateway impreviste e potrebbero comportare un accesso con privilegi eccessivi alle risorse di backend.