Personalizar um ponto de extremidade HTTP no Azure Functions

Neste artigo, você aprenderá como o Azure Functions permite criar APIs altamente escaláveis. O Azure Functions vem com uma coleção de gatilhos e associações HTTP internos, que facilitam a criação de um ponto de extremidade em vários idiomas, incluindo Node.js, C# e muito mais. Neste artigo, você personalizará um gatilho HTTP para lidar com ações específicas em seu design de API. Você também se preparará para expandir sua API integrando-a aos Proxies do Azure Functions e configurando APIs simuladas. Essas tarefas são realizadas sobre o ambiente de computação sem servidor do Functions, para que você não precise se preocupar com o dimensionamento de recursos - você pode apenas se concentrar na lógica da API.

Importante

Os proxies do Azure Functions são um recurso herdado para as versões 1.x a 3.x do tempo de execução do Azure Functions. O suporte para proxies pode ser reativado na versão 4.x para que você atualize com êxito seus aplicativos de função para a versão de tempo de execução mais recente. Assim que possível, você deve alternar para integrar seus aplicativos de função com o Gerenciamento de API do Azure. O API Management permite-lhe tirar partido de um conjunto de funcionalidades mais completo para definir, proteger, gerir e rentabilizar as suas APIs baseadas em Funções. Para obter mais informações, consulte Integração de gerenciamento de API.

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

Pré-requisitos

Este tópico usa como ponto de partida os recursos criados na função Criar a primeira função a partir do portal do Azure. Se ainda não fez isso, conclua estes passos agora para criar a sua plicação de funções.

A função resultante será usada para o resto deste artigo.

Iniciar sessão no Azure

Inicie sessão no portal do Azure com a sua conta do Azure.

Personalizar a sua função HTTP

Por padrão, sua função de 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 esquerdo e, em seguida, selecione HTTP (req) em Trigger.

   

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

   Campo	Valores de exemplo	Description
   Modelo de rota	hello	Determina qual a rota utilizada para invocar esta função
   Nível de autorização	Anónimo	Opcional: torna a sua função acessível sem uma chave de API
   Métodos HTTP selecionados	GET	Permite apenas a utilização dos métodos HTTP selecionados para invocar esta função

   Você não incluiu o prefixo do /api caminho base no modelo de rota, porque ele é manipulado por uma configuração global.

3. Selecione Guardar.

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

Testar a API

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

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

2. Selecione Obter URL da função no menu superior e copie o URL. Confirme se ele agora usa o /api/hello caminho.

3. Copie o URL para um novo separador do browser ou para o seu cliente REST preferido.

   Os navegadores usam GET por padrão.

4. Adicione parâmetros à cadeia de caracteres de consulta em seu URL.

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

5. Prima Enter para confirmar que está a funcionar. Você deve ver a resposta, "Olá João".

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

Descrição geral dos Proxies

Na próxima seção, você exibirá sua API por meio de um proxy. Os Proxies de Funções do Azure permitem reencaminhar pedidos para outros recursos. Você define um ponto de extremidade HTTP da mesma forma que o gatilho HTTP. No entanto, em vez de escrever código para executar quando esse ponto de extremidade é chamado, você fornece uma URL para uma implementação remota. Isso permite que você componha várias fontes de API em uma única superfície de API, o que é fácil para os clientes consumirem, o que é útil se você deseja criar sua API como microsserviços.

Um proxy pode apontar para qualquer recurso HTTP, como, por exemplo:

• Funções do Azure
• Aplicações API no Serviço de Aplicações Azure
• Contentores do docker no Serviço de Aplicações no Linux
• Qualquer outra API alojada

Para saber mais sobre proxies, veja Trabalhar com os Proxies de Funções do Azure.

Nota

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

Criar o seu primeiro proxy

Nesta seção, você cria um novo proxy, que serve como um frontend para sua API geral.

Configurar o ambiente de front-end

Repita as etapas para Criar um aplicativo de função para criar um novo aplicativo de função no qual você criará seu proxy. O URL deste novo aplicativo serve como frontend para nossa API, e o aplicativo de função que você estava editando anteriormente serve como backend.

1. Navegue para a nova aplicação de funções de front-end no portal.

2. Selecione Configuração e escolha Configurações do aplicativo.

3. Role para baixo até Configurações do aplicativo, onde os pares chave/valor são armazenados, e crie uma nova configuração com a chave HELLO_HOST. Defina o respetivo valor como o sistema anfitrião da sua aplicação de funções de back-end, como, por exemplo <YourBackendApp>.azurewebsites.net. Esse valor faz parte da URL que você copiou anteriormente ao testar sua função HTTP. Vai fazer referência a esta definição na configuração mais à frente.

   Nota

   As definições da aplicação são recomendadas para a configuração do sistema anfitrião para evitar uma dependência de ambiente hard-coded para o proxy. Com as definições da aplicação, pode mover a configuração do proxy entre ambientes e as definições da aplicação específicas do ambiente serão aplicadas.

4. Selecione Guardar.

Criar um proxy no front-end

1. Navegue de volta para seu aplicativo de função front-end no portal.

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

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

   Campo	Valores de exemplo	Description
   Name	HelloProxy	Um nome amigável utilizado apenas para gestão
   Modelo de rota	/api/remotehello	Determina qual a rota utilizada para invocar este proxy
   URL de back-end	https://%HELLO_HOST%/api/hello	Especifica o ponto final para o qual o pedido deve ser transmitido por proxy

   

   Os Proxies do Azure Functions não fornecem o prefixo de /api caminho base, que deve ser incluído no modelo de rota. A %HELLO_HOST% sintaxe faz referência à configuração do aplicativo que você criou anteriormente. O URL resolvido apontará para a sua função original.

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

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

Criar uma API fictícia

Em seguida, você usará um proxy para criar uma API simulada para sua solução. Esse proxy permite que o desenvolvimento do cliente progrida, sem precisar do back-end totalmente implementado. Mais tarde no desenvolvimento, você pode criar um novo aplicativo de função, que suporta essa lógica e redirecionar seu proxy para ela.

Para criar essa API simulada, criaremos um novo proxy, desta vez usando o Editor do Serviço de Aplicativo. Para começar, navegue para a aplicação de funções no portal. Selecione Recursos da plataforma e, em Ferramentas de desenvolvimento, localize 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 para todos os seus proxies. Se você usar um dos métodos de implantação do Functions, manterá esse arquivo no controle do código-fonte. Para saber mais sobre este ficheiro, veja Configuração avançada de proxies.

Se você acompanhou até agora, sua proxies.json deve ser a seguinte:

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

Em seguida, você adicionará sua API simulada. Substitua o arquivo proxies.json pelo seguinte código:

{
    "$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"
                    ]
                }
            }
        }
    }
}

Este código adiciona um novo proxy, GetUserByName, sem a backendUri propriedade. Em vez de chamar outro recurso, modifica a resposta predefinida dos Proxies com uma substituição de resposta. As substituições de solicitação e resposta também podem ser usadas com uma URL de back-end. Essa técnica é útil ao fazer proxy para um sistema herdado, onde talvez seja necessário modificar cabeçalhos, parâmetros de consulta e assim por diante. Para saber mais sobre substituições de pedido e resposta, veja Modificar pedidos e respostas nos Proxies.

Teste a sua API fictícia, chamando o ponto final <YourProxyApp>.azurewebsites.net/api/users/{username} com um browser ou com o seu cliente REST favorito. Não se esqueça de substituir {username} por um valor de cadeia que represente um nome de utilizador.

Próximos passos

Neste artigo, você aprendeu como criar e personalizar uma API no Azure Functions. Também aprendeu a reunir várias APIs, incluindo as fictícias, como uma superfície de API unificada. Pode utilizar estas técnicas para criar APIs com qualquer nível de complexidade, tudo isto enquanto as executa no modelo de computação sem servidor fornecido pelas Funções do Azure.

As referências seguintes podem ser úteis à medida que desenvolve ainda mais a sua API:

• Enlaces HTTP das Funções do Azure
• Trabalhar com Proxies de Funções do Azure
• Documentar uma API de Funções do Azure (pré-visualização)