Personalizar um ponto de extremidade HTTP no Azure Functions

Neste artigo, você aprende como o Azure Functions permite que você crie APIs altamente escalonáveis. O Azure Functions conta com uma coleção de gatilhos e associações HTTP integrados que facilitam a criação de um ponto de extremidade em várias linguagens, como Node.js, C# e muito mais. Neste artigo, você personalizará um gatilho HTTP para lidar com ações específicas em seu projeto de API. Você também preparará a expansão de sua API integrando-a aos Proxies do Azure Functions e configurando APIs de simulação. Essas tarefas são realizadas no ambiente de computação sem servidor do Functions. Assim, você não precisa se preocupar com o dimensionamento de recursos e pode se concentrar apenas na lógica da API.

Importante

Os proxies do Azure Functions são um recurso herdado para versões 1.x a 3.x do Azure Functions runtime. O suporte para proxies pode ser reabilitado na versão 4.x para atualizar com sucesso seus aplicativos de funções para a última versão do runtime. Assim que possível, você deverá alternar para integrar seus aplicativos de funções ao Gerenciamento de API do Azure. O Gerenciamento de API permite aproveitar um conjunto mais completo de recursos para definir, proteger, gerenciar e monetizar as APIs baseadas no Functions. Para obter mais informações, consulte Integração do Gerenciamento de API.

Para saber como reabilitar o suporte a proxies no Functions versão 4.x, consulte Reabilitar proxies no Functions v4.x.

Pré-requisitos

Este tópico usa como ponto de partida os recursos criados em Criar sua primeira função no portal do Azure. Se você ainda não fez isso, conclua estas etapas agora para criar seu aplicativo de funções.

A função resultante será ser usada até o final deste artigo.

Entrar no Azure

Entre no portal do Azure com sua conta do Azure.

Personalizar sua função HTTP

Por padrão, a função do gatilho HTTP é configurada para aceitar qualquer método HTTP. Você também pode usar o URL padrão, https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>. Nesta seção, você modifica a função para responder somente a solicitações GET com /api/hello.

1. Navegue até sua função no Portal do Azure. Selecione Integração no menu à esquerda e escolha HTTP (req) em Gatilho.

   

2. Use as configurações do gatilho HTTP conforme especificado na tabela a seguir.

   Campo	Valor de exemplo	Descrição
   Modelo de rota	hello	Determina qual rota pode ser usada para chamar essa função
   Nível de autorização	Anônima	Opcional: torna sua função acessível sem uma chave de API
   Métodos HTTP selecionados	GET	Permite que apenas os métodos HTTP selecionados possam ser usados para chamar essa função

   Você não incluiu o prefixo de caminho base /api no modelo de rota, pois isso é tratado por uma configuração global.

3. Selecione Salvar.

Para obter mais informações sobre como personalizar funções HTTP, consulte Associações HTTP do Azure Functions.

Testar sua API

Em seguida, teste sua função para ver como ela funciona com a nova superfície de API.

1. Na página de função, selecione Código + Teste no menu à esquerda.

2. Selecione Obter URL da função no menu superior e copie a URL. Confirme se ela está usando o caminho /api/hello.

3. Copie a URL em uma nova guia do navegador ou o cliente REST preferencial.

   Os navegadores usam GET por padrão.

4. Adicione parâmetros à cadeia de consulta na URL.

   Por exemplo, /api/hello/?name=John.

5. Pressione Enter para confirmar o funcionamento. Você verá a resposta “Hello John”.

6. Você também pode tentar chamar o ponto de extremidade com outro método HTTP para confirmar se a função não está funcionando. Para isso, use um cliente REST, como cURL, Postman ou Fiddler.

Visão geral dos proxies

Na próxima seção, você mostrará sua API por meio de um proxy. Os Proxies do Azure Functions permitem o encaminhamento de solicitações para outros recursos. Você define um ponto de extremidade HTTP, assim como com o gatilho HTTP. Porém, em vez de programar um código para execução quando o ponto de extremidade for chamado, forneça uma URL para uma implementação remota. Isso permite compor várias fontes de API em uma única superfície de API, o que é fácil para os clientes consumirem e é útil se você quiser criar a API como microsserviço.

Um proxy pode apontar para qualquer recurso HTTP, como:

• Funções do Azure
• Aplicativos de API no Serviço de Aplicativo do Azure
• Contêineres de docker no Serviço de Aplicativo no Linux
• Qualquer outra API hospedada

Para saber mais sobre proxies, confira Trabalhar com Proxies do Azure Functions.

Observação

Os proxies estão disponíveis nas versões 1.x a 3.x do Azure Functions.

Criar seu primeiro proxy

Nesta seção, você cria um novo proxy, que servirá como um front-end para sua API geral.

Configurar o ambiente front-end

Repita as etapas para Criar um aplicativo de função a fim de criar um novo aplicativo de função no qual você criará o proxy. A URL desse novo aplicativo funciona como o front-end da API, e o aplicativo de funções que você estava editando anteriormente funciona como um back-end.

1. Navegue até seu novo aplicativo de função front-end no portal.

2. Selecione Configuração e escolha Configurações de aplicativos.

3. Role para baixo até Configurações de aplicativo, em que os pares chave/valor são armazenados, e crie uma nova configuração com a chave HELLO_HOST. Defina o valor dela como o host de seu aplicativo de função de back-end, como <YourBackendApp>.azurewebsites.net. Esse valor é parte da URL que você copiou anteriormente ao testar sua função HTTP. Você fará referência a essa configuração mais adiante na configuração.

   Observação

   As configurações do aplicativo são recomendadas para a configuração do host a fim de evitar uma dependência do ambiente embutida no código para o proxy. Usar configurações do aplicativo significa que você pode mover a configuração do proxy entre ambientes, e as configurações de aplicativo específicas ao ambiente serão aplicadas.

4. Selecione Salvar.

Criar um proxy no front-end

1. Navegue novamente até o aplicativo de função front-end no portal.

2. No menu à esquerda, selecione Proxies e Adicionar.

3. Na página Novo proxy, use as configurações na tabela a seguir e selecione Criar.

   Campo	Valor de exemplo	Descrição
   Nome	HelloProxy	Um nome amigável usado apenas para gerenciamento
   Modelo de rota	/api/remotehello	Determina qual rota pode ser usada para chamar esse proxy
   URL do back-end	https://%HELLO_HOST%/api/hello	Especifica o ponto de extremidade ao qual a solicitação deve ser transmitida por proxy

   

   O Proxies do Azure Functions não fornece o prefixo de caminho base /api, e ele deve ser incluído no modelo de rota. A sintaxe %HELLO_HOST% referencia a configuração do aplicativo que você criou anteriormente. A URL resolvida apontará para sua função original.

4. Teste seu novo proxy copiando a URL do proxy e testando-o no navegador ou com seu cliente HTTP favorito:

   • Para habilitar uma função anônima, use: https://YOURPROXYAPP.azurewebsites.net/api/remotehello?name="Proxies".
   • Para habilitar uma função com autorização, use: https://YOURPROXYAPP.azurewebsites.net/api/remotehello?code=YOURCODE&name="Proxies".

Criar uma API de simulação

Em seguida, você usará um proxy para criar uma API fictícia para sua solução. Isso permite que o desenvolvimento do cliente avance sem precisar implementar totalmente o back-end. Durante o desenvolvimento, você pode criar um novo aplicativo de funções, que dê suporte a essa lógica, e redirecionar o proxy para ele.

Para criar essa API de simulação, criaremos um novo proxy. Dessa vez, usaremos o Editor do Serviço de Aplicativo. Para começar, navegue até seu aplicativo de função no portal. Selecione Recursos de plataforma e, em Ferramentas de desenvolvimento, encontre Editor do Serviço de Aplicativo. O Editor do Serviço de Aplicativo é aberto em uma nova guia.

Selecione proxies.json no painel de navegação esquerdo. Este arquivo armazena a configuração de todos os seus proxies. Se você usar um dos métodos de implantação do Functions, manterá o controle de origem desse arquivo. Para saber mais sobre esse arquivo, confira Configuração avançada de proxies.

Se você acompanhou as etapas até agora, o proxies.json deve ser semelhante ao seguinte:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "HelloProxy": {
            "matchCondition": {
                "route": "/api/remotehello"
            },
            "backendUri": "https://%HELLO_HOST%/api/hello"
        }
    }
}

Em seguida, você adicionará a API de simulação. Substitua o arquivo proxies.json pelo código a seguir:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "HelloProxy": {
            "matchCondition": {
                "route": "/api/remotehello"
            },
            "backendUri": "https://%HELLO_HOST%/api/hello"
        },
        "GetUserByName" : {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/users/{username}"
            },
            "responseOverrides": {
                "response.statusCode": "200",
                "response.headers.Content-Type" : "application/json",
                "response.body": {
                    "name": "{username}",
                    "description": "Awesome developer and master of serverless APIs",
                    "skills": [
                        "Serverless",
                        "APIs",
                        "Azure",
                        "Cloud"
                    ]
                }
            }
        }
    }
}

Esse código adiciona um novo proxy, GetUserByName, sem a propriedade backendUri. Em vez de chamar outro recurso, ele modifica a resposta padrão dos Proxies usando uma substituição de resposta. Substituições de solicitação e resposta também podem ser usadas com uma URL de back-end. Essa técnica é útil durante a transmissão por proxy para um sistema herdado, quando você pode precisar modificar cabeçalhos, consultar parâmetros etc. Para saber mais sobre as substituições de solicitação e resposta, Confira Modificar solicitações e respostas em Proxies.

Teste sua API de simulação chamando o ponto de extremidade <YourProxyApp>.azurewebsites.net/api/users/{username} usando um navegador ou seu cliente REST favorito. Não deixe de substituir {username} por um valor de cadeia de caracteres que represente um nome de usuário.

Próximas etapas

Neste artigo, você aprendeu a compilar e personalizar uma API no Azure Functions. Você também aprendeu a unir várias APIs, incluindo objetos fictícios, como uma superfície de API unificada. Use essas técnicas para compilar APIs de qualquer complexidade durante a execução no modelo de computação sem servidor fornecido pelo Azure Functions.

As referências a seguir podem ser úteis durante o desenvolvimento de sua API:

• Associações de HTTP do Azure Functions
• Trabalhar com Proxies do Azure Functions
• Documentar uma API do Azure Functions (visualização)