Noções básicas sobre modelos de caminho

No gateway de API, é possível rotear solicitações recebidas com base no modelo de caminho. Um modelo de caminho tem três componentes principais:

• Correspondência exata
• Correspondência de caractere curinga único
• Correspondência de caractere curinga dupl

As seções a seguir descrevem cada um desses componentes e como eles funcionam no contexto do gateway de API.

Correspondência exata

Um caminho com modelo sem segmentos curinga únicos ou duplos (* ou **) é convertido em uma correspondência de caminho exata. Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta

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

Neste exemplo, o gateway aceita apenas solicitações para /shelves e nenhum outro caminho.

Correspondência de caractere curinga único

Se um caminho com modelo tiver uma variável, um segmento de caractere curinga singular ({var}) ou, somente no OpenAPI 2.0, um segmento de caractere curinga singular ({var=*}), o gateway permitirá solicitações de entrada que estejam em conformidade com o seguinte:

• As solicitações não contêm uma barra (/), o que significa que a variável corresponderá apenas a um único segmento de caminho.
• As solicitações contêm pelo menos um caractere.
• As solicitações podem conter uma barra extra no final do caminho.

Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta

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

Neste exemplo, o gateway aceitará solicitações que correspondam à seguinte expressão regular:

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

Correspondência de caracteres curinga duplos

Se um caminho com modelo contiver uma variável indicada por um segmento de caractere curinga duplo (por exemplo, {var=**}), o gateway permitirá solicitações recebidas que estejam em conformidade com o seguinte:

• As solicitações podem conter todos caracteres, incluindo barras (/).
• As solicitações podem conter 0 ou mais caracteres.
• As solicitações podem conter uma barra extra no final do caminho.

Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta

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

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

Neste exemplo, o gateway aceitará solicitações em que o parâmetro book corresponda a qualquer caractere, incluindo barras. Isso corresponde à seguinte expressão regular:

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

Barras codificadas por URL

O gateway de API segue RFC 3986, que não trata barras de URL codificadas (%2F) como barras reais ao corresponder caminhos de URL para roteamento ou decisões de segurança. Se forem esperadas barras codificadas de URL, o back-end deverá processar essas solicitações adequadamente.

Por exemplo, considere a seguinte especificação 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: