Transformando Solicitações de Entrada e Respostas de Saída

Usando a Console para Adicionar Políticas de Solicitação de Transformação de Cabeçalho

Para adicionar políticas de solicitação de transformação de cabeçalho a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

2. Selecione Próximo e especifique opções de autenticação na página Autenticação.

   Para obter mais informações sobre opções de autenticação, consulte Adicionando Autenticação e Autorização às Implantações de API.

3. Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Rotas.

4. Na página Rotas, selecione a rota para a qual você deseja especificar as políticas de solicitação de transformação de cabeçalho.
5. Selecione Mostrar Políticas de Solicitação de Rota.
6. Selecione o botão Adicionar ao lado de Transformações de Cabeçalho para atualizar os cabeçalhos incluídos em uma solicitação para o gateway de API da rota atual.

7. Para limitar os cabeçalhos incluídos em uma solicitação, especifique:

   • Ação: Filtrar.
   • Tipo: Bloquear para remover da solicitação os cabeçalhos listados explicitamente ou Permitir para permitir na solicitação apenas os cabeçalhos listados explicitamente (quaisquer outros cabeçalhos são removidos da solicitação).
   • Nomes de Cabeçalho: A lista de cabeçalhos a serem removidos da solicitação ou permitidos na solicitação (dependendo da definição de Tipo). Os nomes especificados não diferenciam maiúsculas de minúsculas e não devem ser incluídos em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, User-Agent.

8. Para alterar o nome de um cabeçalho incluído em uma solicitação (mantendo seu valor original), especifique:

   • Ação: Renomear.
   • De: O nome original do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota. Por exemplo, X-Username.
   • Para: O novo nome do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-User-ID.

9. Para adicionar um novo cabeçalho a uma solicitação (ou para alterar ou manter os valores de um cabeçalho existente já incluído em uma solicitação), especifique:

   • Ação: Definir.

   • Comportamento: Se o cabeçalho já existir, especifique o que fazer com o valor existente do cabeçalho:

     • Substituir, para substituir o valor existente do cabeçalho pelo valor especificado.
     • Anexar, para anexar o valor especificado ao valor existente do cabeçalho.
     • Ignorar, para manter o valor existente do cabeçalho.
   • Nome: O nome do cabeçalho a ser adicionado à solicitação (ou para alterar o valor de). O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-Api-Key.
   • Valores: O valor do novo cabeçalho (ou o valor a ser substituído ou acrescentado ao valor de um cabeçalho existente, dependendo da definição de Comportamento). Você pode especificar vários valores. O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto (exceto request.body) entre delimitadores ${...}. Por exemplo, "value": "zyx987wvu654tsu321", "value": "${request.path[region]}", "value": "${request.headers[opc-request-id]}".
10. Selecione Salvar Alterações e, em seguida, selecione Próximo para revisar os detalhes informados para rotas individuais.
11. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
12. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Editando um Arquivo JSON para Adicionar Políticas de Solicitação de Transformação de Cabeçalho

Para adicionar políticas de solicitação de transformação de cabeçalho a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar políticas de solicitação de transformação de cabeçalho ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Insira uma seção requestPolicies após a seção backend da rota à qual você deseja que a política de solicitação de transformação de cabeçalho seja aplicada. Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {}
       }
     ]
   }

3. Adicione uma seção headerTransformations à seção requestPolicies.

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations":{}
         }
       }
     ]
   }

4. Para limitar os cabeçalhos incluídos em uma solicitação, especifique uma política de solicitação de transformação de cabeçalho filterHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "filterHeaders": {
               "type": "<BLOCK|ALLOW>",
               "items": [
                 {
                   "name": "<header-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "type": "<BLOCK|ALLOW>" indica o que fazer com os cabeçalhos especificados por "items":[{"name":"<header-name>"}]:
     • Use BLOCK para remover da solicitação os cabeçalhos listados explicitamente.
     • Use ALLOW para permitir na solicitação apenas os cabeçalhos listados explicitamente (quaisquer outros cabeçalhos serão removidos da solicitação).
   • "name":"<header-name> é um cabeçalho a ser removido da solicitação ou permitido na solicitação (dependendo da definição de "type": "<BLOCK|ALLOW>"). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, User-Agent.

   Você pode remover e permitir até 50 cabeçalhos em uma política de solicitação de transformação de cabeçalho filterHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "filterHeaders": {
               "type": "BLOCK",
               "items": [
                 {
                   "name": "User-Agent"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API remove o cabeçalho User-Agent de todas as solicitações de entrada.

5. Para alterar o nome de um cabeçalho incluído em uma solicitação (mantendo seu valor original), especifique uma política de solicitação de transformação de cabeçalho renameHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "renameHeaders": {
               "items": [
                 {
                   "from": "<original-name>",
                   "to": "<new-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "from": "<original-name>" é o nome original do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota. Por exemplo, X-Username.
   • "to": "<new-name>" é o novo nome do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-User-ID.

   Você pode renomear até 20 cabeçalhos em uma política de solicitação de transformação de cabeçalho renameHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "renameHeaders": {
               "items": [
                 {
                   "from": "X-Username",
                   "to": "X-User-ID"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API renomeia qualquer cabeçalho X-Username como X-User-ID, mantendo o valor original do cabeçalho.

6. Para adicionar um novo cabeçalho a uma solicitação (ou para alterar ou manter os valores de um cabeçalho existente já incluído em uma solicitação), especifique uma política de solicitação de transformação de cabeçalho setHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "setHeaders": {
               "items": [
                 {
                   "name": "<header-name>",
                   "values": ["<header-value>"],
                   "ifExists": "<OVERWRITE|APPEND|SKIP>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "name":"<header-name> é o nome do cabeçalho a ser adicionado à solicitação (ou para alterar o valor de). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-Api-Key.
   • "values": ["<header-value>"] é o valor do novo cabeçalho (ou o valor a ser substituído ou acrescentado ao valor de um cabeçalho existente, dependendo da definição de "ifExists": "<OVERWRITE|APPEND|SKIP>"). O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto (exceto request.body) entre delimitadores ${...}. Por exemplo, "values": "zyx987wvu654tsu321", "values": "${request.path[region]}", "values": "${request.headers[opc-request-id]}".

     É possível especificar até 10 valores. Se você especificar vários valores, o gateway da API adicionará um cabeçalho para cada valor.

   • "ifExists": "<OVERWRITE|APPEND|SKIP>" indica o que fazer com o valor existente do cabeçalho se o cabeçalho especificado por <header-name> já existir:

     • Use OVERWRITE para substituir o valor existente do cabeçalho pelo valor especificado.
     • Use APPEND para adicionar o valor especificado ao valor existente do cabeçalho.
     • Use SKIP para manter o valor existente do cabeçalho.

     Se não for especificado, o padrão será OVERWRITE.

   Você pode adicionar (ou alterar os valores de) até 20 cabeçalhos em uma política de solicitação de transformação de cabeçalho setHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "headerTransformations": {
             "setHeaders": {
               "items": [
                 {
                   "name": "X-Api-Key",
                   "values": ["zyx987wvu654tsu321"],
                   "ifExists": "OVERWRITE"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API adiciona o cabeçalho X-Api-Key:zyx987wvu654tsu321 a todas as solicitações de entrada. Se uma solicitação de entrada já tiver um cabeçalho X-Api-Key definido com um valor distinto, o gateway da API substituirá o valor existente por zyx987wvu654tsu321.

7. Salve o arquivo JSON que contém a especificação de implantação de API.

8. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

9. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Usando a Console para Adicionar Políticas de Solicitação de Transformação de Parâmetro de Consulta

Para adicionar políticas de solicitação de transformação de parâmetro de consulta a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

2. Selecione Próximo e especifique opções de autenticação na página Autenticação.

   Para obter mais informações sobre opções de autenticação, consulte Adicionando Autenticação e Autorização às Implantações de API.

3. Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Rotas.

4. Na página Rotas, selecione a rota para a qual deseja especificar políticas de solicitação de transformação de parâmetro de consulta.
5. Selecione Mostrar Políticas de Solicitação de Rota.
6. Selecione o botão Adicionar ao lado de Transformações de Parâmetro de Consulta para atualizar os parâmetros de consulta incluídos em uma solicitação para o gateway de API da rota atual.

7. Para limitar os parâmetros de consulta incluídos em uma solicitação, especifique:

   • Ação: Filtrar.
   • Tipo: Bloquear para remover da solicitação os parâmetros de consulta listados explicitamente ou Permitir para permitir na solicitação apenas os parâmetros de consulta listados explicitamente (quaisquer outros parâmetros de consulta são removidos da solicitação).
   • Nomes de Parâmetro de Consulta: A lista de parâmetros de consulta a serem removidos da solicitação ou permitidos na solicitação (dependendo da definição de Tipo). Os nomes especificados diferenciam maiúsculas de minúsculas e não devem ser incluídos em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, User-Agent.

8. Para alterar o nome de um parâmetro de consulta incluído em uma solicitação (mantendo seu valor original), especifique:

   • Ação: Renomear.
   • De: O nome original do parâmetro de consulta que você está renomeando. O nome especificado faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota. Por exemplo, X-Username.
   • Para: O novo nome do parâmetro de consulta que você está renomeando. O nome especificado faz distinção entre maiúsculas e minúsculas (a capitalização é respeitada) e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-User-ID.

9. Para adicionar um novo parâmetro de consulta a uma solicitação (ou para alterar ou manter os valores de um parâmetro de consulta existente já incluído em uma solicitação), especifique:

   • Ação: Definir.

   • Comportamento: Se o parâmetro de consulta já existir, especifique o que fazer com o valor existente do parâmetro de consulta:

     • Substituir, para substituir o valor existente do parâmetro de consulta pelo valor especificado.
     • Anexar, para acrescentar o valor especificado ao valor existente do parâmetro de consulta.
     • Ignorar, para manter o valor existente do parâmetro de consulta.
   • Nome do Parâmetro de Consulta: O nome do parâmetro de consulta a ser adicionado à solicitação (ou para alterar o valor de). O nome especificado faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-Api-Key.
   • Valores: O valor do novo parâmetro de consulta (ou o valor a ser substituído ou acrescentado ao valor de um parâmetro de consulta existente, dependendo da definição de Comportamento). O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto entre delimitadores ${...}. Por exemplo, "value": "zyx987wvu654tsu321", "value": "${request.path[region]}", "value": "${request.headers[opc-request-id]}". Você pode especificar vários valores.
10. Selecione Salvar Alterações e, em seguida, selecione Próximo para revisar os detalhes informados para rotas individuais.
11. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
12. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Editando um Arquivo JSON para Adicionar Políticas de Solicitação de Transformação de Parâmetro de Consulta

Para adicionar políticas de solicitação de transformação de parâmetro de consulta a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar políticas de solicitação de transformação de parâmetro de consulta ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Insira uma seção requestPolicies após a seção backend da rota à qual você deseja que a política de solicitação de transformação do parâmetro de consulta seja aplicada. Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {}
       }
     ]
   }

3. Adicione uma seção queryParameterTransformations à seção requestPolicies.

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations":{}
         }
       }
     ]
   }

4. Para limitar os parâmetros de consulta incluídos em uma solicitação, especifique uma política de solicitação de transformação de parâmetros de consulta filterQueryParameters:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "filterQueryParameters": {
               "type": "<BLOCK|ALLOW>",
               "items": [
                 {
                   "name": "<query-parameter-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "type": "<BLOCK|ALLOW>" indica o que fazer com os parâmetros de consulta especificados por "items":[{"name":"<query-parameter-name>"}]:
     • Use BLOCK para remover da solicitação os parâmetros de consulta listados explicitamente.
     • Use ALLOW para permitir na solicitação apenas os parâmetros de consulta listados explicitamente (quaisquer outros parâmetros de consulta são removidos da solicitação).
   • "name":"<query-parameter-name> é um parâmetro de consulta a ser removido da solicitação ou permitido na solicitação (dependendo da definição de "type": "<BLOCK|ALLOW>"). O nome especificado faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, User-Agent.

   Você pode remover e permitir até 50 parâmetros de consulta em uma política de solicitação de transformação de parâmetro de consulta filterQueryParameters.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "filterQueryParameters": {
               "type": "BLOCK",
               "items": [
                 {
                   "name": "User-Agent"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API remove o parâmetro de consulta User-Agent de todas as solicitações de entrada.

5. Para alterar o nome de um parâmetro de consulta incluído em uma solicitação (mantendo seu valor original), especifique uma política de solicitação de transformação de parâmetro de consulta renameQueryParameters:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "renameQueryParameters": {
               "items": [
                 {
                   "from": "<original-name>",
                   "to": "<new-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "from": "<original-name>" é o nome original do parâmetro de consulta que você está renomeando. O nome especificado faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota. Por exemplo, X-Username.
   • "to": "<new-name>" é o novo nome do parâmetro de consulta que você está renomeando. O nome especificado faz distinção entre maiúsculas e minúsculas (a capitalização é respeitada) e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-User-ID.

   Você pode renomear até 20 parâmetros de consulta em uma política de solicitação de transformação de parâmetro de consulta renameQueryParameters.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "renameQueryParameters": {
               "items": [
                 {
                   "from": "X-Username",
                   "to": "X-User-ID"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API renomeia qualquer parâmetro de consulta X-Username como X-User-ID, mantendo o valor original do parâmetro de consulta.

6. Para adicionar um novo parâmetro de consulta a uma solicitação (ou para alterar ou manter os valores de um parâmetro de consulta existente já incluído em uma solicitação), especifique uma política de solicitação de transformação de parâmetro de consulta setQueryParameters:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "setQueryParameters": {
               "items": [
                 {
                   "name": "<query-parameter-name>",
                   "values": ["<query-parameter-value>"],
                   "ifExists": "<OVERWRITE|APPEND|SKIP>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "name": "<query-parameter-name>" é o nome do parâmetro de consulta a ser adicionado à solicitação (ou para alterar o valor de). O nome especificado faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de solicitação de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-Api-Key.
   • "values": ["<query-parameter-value>"] é o valor do novo parâmetro de consulta (ou o valor a ser substituído ou anexado ao valor de um parâmetro de consulta existente, dependendo da definição de "ifExists": "<OVERWRITE|APPEND|SKIP>"). O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto entre delimitadores ${...}. Por exemplo, "values": "zyx987wvu654tsu321", "values": "${request.path[region]}", "values": "${request.headers[opc-request-id]}".

     É possível especificar até 10 valores. Se você especificar vários valores, o gateway da API adicionará um parâmetro de consulta para cada valor.

   • "ifExists": "<OVERWRITE|APPEND|SKIP>" indica o que fazer com o valor existente do parâmetro de consulta se o parâmetro de consulta especificado por <query-parameter-name> já existir:

     • Use OVERWRITE para substituir o valor existente do parâmetro de consulta pelo valor especificado.
     • Use APPEND para acrescentar o valor especificado ao valor existente do parâmetro de consulta.
     • Use SKIP para manter o valor existente do parâmetro de consulta.

     Se não for especificado, o padrão será OVERWRITE.

   Você pode adicionar (ou alterar os valores de) até 20 parâmetros de consulta em uma política de solicitação de transformação de parâmetro de consulta setQueryParameters.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "queryParameterTransformations": {
             "setQueryParameters": {
               "items": [
                 {
                   "name": "X-Api-Key",
                   "values": ["zyx987wvu654tsu321"],
                   "ifExists": "OVERWRITE"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API adiciona o parâmetro de consulta X-Api-Key:zyx987wvu654tsu321 a todas as solicitações de entrada. Se uma solicitação de entrada já tiver um parâmetro de consulta X-Api-Key definido com um valor distinto, o gateway da API substituirá o valor existente por zyx987wvu654tsu321.

7. Salve o arquivo JSON que contém a especificação de implantação de API.

8. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

9. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Usando a Console para Adicionar Políticas de Resposta de Transformação de Cabeçalho

Para adicionar políticas de resposta de transformação de cabeçalho a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

2. Selecione Próximo e especifique opções de autenticação na página Autenticação.

   Para obter mais informações sobre opções de autenticação, consulte Adicionando Autenticação e Autorização às Implantações de API.

3. Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Rotas.

4. Na página Rotas, selecione a rota para a qual você deseja especificar políticas de resposta de transformação de cabeçalho.
5. Selecione Mostrar Políticas de Resposta de Rota.
6. Selecione o botão Adicionar ao lado de Transformações de Cabeçalho para atualizar os cabeçalhos incluídos em uma resposta do gateway de API da rota atual.

7. Para limitar os cabeçalhos incluídos em uma resposta, especifique:

   • Ação: Filtrar.
   • Tipo: Bloquear para remover da resposta os cabeçalhos listados explicitamente ou Permitir para permitir na resposta apenas os cabeçalhos listados explicitamente (quaisquer outros cabeçalhos são removidos da resposta).
   • Nomes de Cabeçalho: A lista de cabeçalhos a serem removidos da reposta ou permitidos na reposta (dependendo da definição de Tipo). Os nomes especificados não diferenciam maiúsculas de minúsculas e não devem ser incluídos em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, User-Agent.

8. Para alterar o nome de um cabeçalho incluído em uma resposta (mantendo seu valor original), especifique:

   • Ação: Renomear.
   • De: O nome original do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota. Por exemplo, X-Username.
   • Para: O novo nome do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-User-ID.

9. Para adicionar um novo cabeçalho a uma resposta (ou para alterar ou manter os valores de um cabeçalho existente já incluído em uma resposta), especifique:

   • Ação: Definir.

   • Comportamento: Se o cabeçalho já existir, especifique o que fazer com o valor existente do cabeçalho:

     • Substituir, para substituir o valor existente do cabeçalho pelo valor especificado.
     • Anexar, para anexar o valor especificado ao valor existente do cabeçalho.
     • Ignorar, para manter o valor existente do cabeçalho.
   • Nome: O nome do cabeçalho a ser adicionado à resposta (ou para alterar o valor de). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-Api-Key.
   • Valores: O valor do novo cabeçalho (ou o valor a ser substituído ou acrescentado ao valor de um cabeçalho existente, dependendo da definição de Comportamento). O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto entre delimitadores ${...}. Por exemplo, "value": "zyx987wvu654tsu321". Você pode especificar vários valores.
10. Selecione Salvar Alterações e, em seguida, selecione Próximo para revisar os detalhes informados para rotas individuais.
11. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
12. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Editando um Arquivo JSON para Adicionar Políticas de Resposta de Transformação de Cabeçalho

Para adicionar políticas de resposta de transformação de cabeçalho a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar políticas de resposta de transformação de cabeçalho ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Insira uma seção responsePolicies após a seção backend da rota à qual você deseja que a política de resposta de transformação de cabeçalho seja aplicada. Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {}
       }
     ]
   }

3. Adicione uma seção headerTransformations à seção responsePolicies.

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations":{}
         }
       }
     ]
   }

4. Para limitar os cabeçalhos incluídos em uma resposta, especifique uma política de resposta de transformação de cabeçalho filterHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "filterHeaders": {
               "type": "<BLOCK|ALLOW>",
               "items": [
                 {
                   "name": "<header-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "type": "<BLOCK|ALLOW>" indica o que fazer com os cabeçalhos especificados por "items":[{"name":"<header-name>"}]:
     • Use BLOCK para remover da resposta os cabeçalhos listados explicitamente.
     • Use ALLOW para permitir na resposta apenas os cabeçalhos listados explicitamente (quaisquer outros cabeçalhos serão removidos da resposta).
   • "name":"<header-name> é um cabeçalho a ser removido da resposta ou permitido na resposta (dependendo da definição de "type": "<BLOCK|ALLOW>"). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, User-Agent.

   Você pode remover e permitir até 20 cabeçalhos em uma política de resposta de transformação de cabeçalho filterHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "filterHeaders": {
               "type": "BLOCK",
               "items": [
                 {
                   "name": "User-Agent"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API remove o cabeçalho User-Agent de todas as respostas de saída.

5. Para alterar o nome de um cabeçalho incluído em uma resposta (mantendo seu valor original), especifique uma política de resposta de transformação de cabeçalho renameHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "renameHeaders": {
               "items": [
                 {
                   "from": "<original-name>",
                   "to": "<new-name>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "from": "<original-name>" é o nome original do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota. Por exemplo, X-Username.
   • "to": "<new-name>" é o novo nome do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-User-ID.

   Você pode renomear até 20 cabeçalhos em uma política de resposta de transformação de cabeçalho renameHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "renameHeaders": {
               "items": [
                 {
                   "from": "X-Username",
                   "to": "X-User-ID"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API renomeia qualquer cabeçalho X-Username como X-User-ID, mantendo o valor original do cabeçalho.

6. Para adicionar um novo cabeçalho a uma resposta (ou para alterar ou manter os valores de um cabeçalho existente já incluído em uma resposta), especifique uma política de resposta de transformação de cabeçalho setHeaders:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "setHeaders": {
               "items": [
                 {
                   "name": "<header-name>",
                   "values": ["<header-value>"],
                   "ifExists": "<OVERWRITE|APPEND|SKIP>"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   em que:

   • "name":"<header-name> é o nome do cabeçalho a ser adicionado à resposta (ou para alterar o valor de). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-Api-Key.
   • "values": ["<header-value>"] é o valor do novo cabeçalho (ou o valor a ser substituído ou acrescentado ao valor de um cabeçalho existente, dependendo da definição de "ifExists": "<OVERWRITE|APPEND|SKIP>"). O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto entre delimitadores ${...}. Por exemplo, "values": "zyx987wvu654tsu321".

     É possível especificar até 10 valores. Se você especificar vários valores, o gateway da API adicionará um cabeçalho para cada valor.

   • "ifExists": "<OVERWRITE|APPEND|SKIP>" indica o que fazer com o valor existente do cabeçalho se o cabeçalho especificado por <header-name> já existir:

     • Use OVERWRITE para substituir o valor existente do cabeçalho pelo valor especificado.
     • Use APPEND para adicionar o valor especificado ao valor existente do cabeçalho.
     • Use SKIP para manter o valor existente do cabeçalho.

     Se não for especificado, o padrão será OVERWRITE.

   Você pode adicionar (ou alterar os valores de) até 20 cabeçalhos em uma política de resposta de transformação de cabeçalho setHeaders.

   Por exemplo:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "responsePolicies": {
           "headerTransformations": {
             "setHeaders": {
               "items": [
                 {
                   "name": "X-Api-Key",
                   "values": ["zyx987wvu654tsu321"],
                   "ifExists": "OVERWRITE"
                 }
               ]
             }
           }
         }
       }
     ]
   }

   Neste exemplo, o gateway da API adiciona o cabeçalho X-Api-Key:zyx987wvu654tsu321 a todas as respostas de saída. Se uma resposta de saída já tiver um cabeçalho X-Api-Key definido com um valor distinto, o gateway da API substituirá o valor existente por zyx987wvu654tsu321.

7. Salve o arquivo JSON que contém a especificação de implantação de API.

8. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

9. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

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.