Exemplos de Transformação

Use exemplos para saber como modificar solicitações de entrada e respostas de saída que estão sendo enviadas de e para serviços de back-end com o API Gateway.

Os exemplos nesta seção pressupõem a seguinte definição de implantação de API e a especificação básica de implantação de API em um arquivo JSON:

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        },
        "requestPolicies": {}
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

Observe que os exemplos também se aplicam quando você está definindo uma especificação de implantação de API usando caixas de diálogo na Console.

Exemplo 1: Transformando parâmetros de cabeçalho em parâmetros de consulta

Neste exemplo, suponha que um back-end de HTTP existente trate apenas solicitações contendo parâmetros de consulta, não parâmetros de cabeçalho. No entanto, você deseja que o back-end de HTTP trate solicitações que incluem parâmetros de cabeçalho. Para isso, crie uma especificação de implantação de API que inclua uma política de solicitação de transformação de parâmetro de consulta para informar o valor obtido de um cabeçalho de solicitação para o back-end de HTTP como um parâmetro de consulta.

        "requestPolicies": {
          "queryParameterTransformations":  {
            "setQueryParameters": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[region]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

Neste exemplo, uma solicitação como curl -H "region: west" https://<gateway-hostname>/marketing/weather é resolvida como https://api.weather.gov?region=west.

Exemplo 2: Transformando um cabeçalho em um cabeçalho distinto

Neste exemplo, suponha que um back-end de HTTP existente trate apenas solicitações que contenham um cabeçalho específico. No entanto, você deseja que o back-end de HTTP trate solicitações que incluem um cabeçalho distinto. Para isso, crie uma especificação de implantação de API que inclua uma política de solicitação de transformação de cabeçalho para usar o valor obtido de um cabeçalho de solicitação e informá-lo ao back-end de HTTP como um cabeçalho de solicitação distinto.

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[locale]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

Neste exemplo, uma solicitação como curl -H "locale: west" https://<gateway-hostname>/marketing/weather é resolvida para a solicitação curl -H "region: west" https://api.weather.gov.

Exemplo 3: Adicionando um parâmetro de autenticação obtido de um JWT como cabeçalho de solicitação

Neste exemplo, suponha que um back-end de HTTP existente exija que o valor da reivindicação sub em um JWT (JSON Web Token) validado seja incluído em uma solicitação como um cabeçalho com o nome JWT_SUBJECT. O serviço API Gateway salvou o valor da reivindicação sub incluída no JWT como um parâmetro de autenticação na tabela request.auth.

Para incluir o valor de sub em um cabeçalho chamado JWT_SUBJECT, crie uma especificação de implantação de API que inclua uma política de solicitação de transformação de cabeçalho. A política de solicitação obtém o valor sub da tabela request.auth e o transmite ao back-end de HTTP como o valor do cabeçalho JWT_SUBJECT.

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "JWT_SUBJECT",
                  "values": ["${request.auth[sub]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

Neste exemplo, quando uma solicitação é validada com sucesso, o cabeçalho JWT_SUBJECT é adicionado à solicitação informada ao back-end de HTTP.

Exemplo 4: Adicionando uma chave obtida de uma função de autorizador como um parâmetro de consulta

Neste exemplo, suponha que um back-end de HTTP existente exija solicitações para incluir um parâmetro de consulta chamado access_key para fins de autenticação. Você deseja que o parâmetro de consulta access_key tenha o valor de uma chave chamada apiKey que foi retornada por uma função de autorizador que validou com sucesso a solicitação. O serviço API Gateway salvou o valor apiKey como um parâmetro de autenticação na tabela request.auth.

Para incluir o parâmetro de consulta access_key na solicitação, crie uma especificação de implantação de API que inclua uma política de solicitação de transformação de parâmetro de consulta. A política de solicitação obtém o valor apiKey da tabela request.auth e o informa ao back-end de HTTP como o valor do parâmetro de consulta access_key.

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "access_key",
                  "values": ["${request.auth[apiKey]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

Neste exemplo, o parâmetro de consulta access_key é adicionado à solicitação informada ao back-end de HTTP, com o valor apiKey da tabela request.auth. Uma solicitação como https://<gateway-hostname>/marketing/weather é resolvida para uma solicitação como https://api.weather.gov?access_key=fw5n9abi0ep

Exemplo 5: Adicionando um valor padrão para um parâmetro de consulta opcional

Neste exemplo, suponha que um back-end de HTTP existente exija solicitações para incluir um parâmetro de consulta chamado country. No entanto, o parâmetro de consulta country é opcional e não é incluído por alguns dos clientes de API que enviam solicitações. Se uma solicitação já incluir um parâmetro de consulta country e um valor, você desejará que ambos sejam informados como estão ao back-end de HTTP. No entanto, se uma solicitação ainda não incluir um parâmetro de consulta country, você desejará que o parâmetro de consulta country e um valor padrão sejam adicionados à solicitação.

Para garantir que cada solicitação inclua um parâmetro de consulta country, crie uma especificação de implantação de API que inclua uma política de solicitação de transformação de parâmetro de consulta. A política de solicitação adiciona o parâmetro de consulta country e um valor padrão a qualquer solicitação que ainda não inclua o parâmetro de consulta country.

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "country",
                  "values": ["usa"],
                  "ifExists": "SKIP"
                }
              ]
            }
          }
        }

Neste exemplo, uma solicitação como https://<gateway-hostname>/marketing/weather é resolvida para https://api.weather.gov?country=usa. Uma solicitação como https://<gateway-hostname>/marketing/weather?country=canada é resolvida para https://api.weather.gov?country=canada.