Informazioni sui modelli di percorso

In API Gateway è possibile instradare le richieste in entrata in base al modello di percorso. Un modello di percorso è composto da tre elementi principali:

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

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

Corrispondenza esatta

Un percorso con modello senza segmenti con un singolo o doppio carattere jolly (* o **) viene convertito in una corrispondenza esatta del percorso. Ad esempio, la specifica OpenAPI per la configurazione API del gateway potrebbe contenere una sezione simile alla 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 (%2F) codificate in URL non verranno trattate come barre effettive, il che significa che %2Fshelves non corrisponderà all'operazione OpenAPI descritta in precedenza nella specifica.

Corrispondenza con un singolo carattere jolly

Se un percorso con modello contiene una variabile, un segmento con un singolo carattere jolly ({var}) o, solo in OpenAPI 2.0, un segmento con un singolo carattere jolly ({var=*}), il gateway consentirà le richieste in entrata che rispettano quanto segue:

• Le richieste non contengono una barra aggiuntiva (/), il che significa che la variabile corrisponderà solo a un singolo segmento di percorso.
• Le richieste contengono almeno un carattere.
• Le richieste possono 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 simile alla 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 un doppio carattere jolly

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

• Le richieste possono contenere tutti i caratteri, incluse le barre (/).
• Le richieste possono contenere 0 o più caratteri.
• Le richieste possono 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 con doppio carattere jolly 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 simile alla 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 codificate in URL

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

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

Ad esempio, prendi in considerazione 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, ma 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 nel gateway. Tuttavia, poiché il gateway ha letto la richiesta come operazione GetShelf, non è stato eseguito alcun controllo della chiave API.

Normalizzazione di più barre adiacenti

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

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

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

Regole di sintassi

API Gateway applica diverse regole di convalida della sintassi per i modelli di percorso:

• Convenzioni di denominazione delle variabili: i nomi delle variabili devono iniziare con una lettera (maiuscola o minuscola) o un trattino basso (_) e possono contenere solo lettere, numeri, trattini bassi, punti (.) e trattini (-).
  • Valido: {my_var}, {var-1}, {var.name}
  • Non valido: {1var}, {my var}
• Nessuna combinazione di parametri e valori letterali: un singolo segmento di percorso non può contenere sia un parametro sia caratteri letterali.
  • Valido: /prefix/{var}
  • Non valido: /prefix-{var}, /{var}suffix
• Suffisso del metodo personalizzato consentito: l'unica eccezione alla combinazione di parametri e valori letterali è nell'ultimo segmento del percorso, in cui è consentito un suffisso del metodo personalizzato che inizia con i due punti (:).
  • Valido: /{var}:customMethod
  • Non valido: /{var}:customMethod/suffix
• Nessun parametro multiplo per segmento: un singolo segmento di percorso non può contenere più di un parametro.
  • Valido: /{var1}/{var2}
  • Non valido: /{var1}{var2}
• Nessun parametro nidificato: i parametri non possono essere nidificati l'uno nell'altro.
  • Valido: /{var}
  • Non valido: /{{var}}
• Doppio carattere jolly: i segmenti con doppio carattere jolly possono essere solo nell'ultimo segmento del percorso.
  • Valido: /prefix/{var=**}, /prefix/**
  • Non valido: /{var=**}/suffix, /**/suffix

Limiti

Limite	Valore
Numero di parametri per percorso	60
Lunghezza del nome della variabile	100
Lunghezza del percorso (con o senza modelli)	512