Personalizar um ponto de extremidade HTTP no Azure FunctionsCustomize an HTTP endpoint in Azure Functions

Neste artigo, você aprende como Azure Functions permite que você crie APIs altamente escalonáveis.In this article, you learn how Azure Functions allows you to build highly scalable APIs. O Azure Functions vem com uma coleção interna de gatilhos e associações HTTP que facilitam a criação de um ponto de extremidade em várias linguagens, incluindo Node.JS, C# e muito mais.Azure Functions comes with a collection of built-in HTTP triggers and bindings, which make it easy to author an endpoint in a variety of languages, including Node.JS, C#, and more. Neste artigo, você personalizará um gatilho HTTP para manipular ações específicas em seu design de API.In this article, you will customize an HTTP trigger to handle specific actions in your API design. Você também preparará a expansão de sua API integrando-a aos Proxies do Azure Functions e configurando APIs de simulação.You will also prepare for growing your API by integrating it with Azure Functions Proxies and setting up mock APIs. Tudo isso é realizado no ambiente de computação sem servidor do Functions, portanto você não precisa se preocupar com o dimensionamento de recursos, você pode se concentrar apenas na lógica de sua API.All of this is accomplished on top of the Functions serverless compute environment, so you don't have to worry about scaling resources - you can just focus on your API logic.

Pré-requisitosPrerequisites

Este tópico usa como ponto de partida os recursos criados em Criar sua primeira função no portal do Azure.This topic uses as its starting point the resources created in Create your first function from the Azure portal. Se você ainda não fez isso, conclua estas etapas agora para criar seu aplicativo de funções.If you haven't already done so, please complete these steps now to create your function app.

A função resultante será usada para o restante deste artigo.The resulting function will be used for the rest of this article.

Entrar no AzureSign in to Azure

Abra o portal do Azure.Open the Azure portal. Para fazer isso, entre no https://portal.azure.com com sua conta do Azure.To do this, sign in to https://portal.azure.com with your Azure account.

Personalizar sua função HTTPCustomize your HTTP function

Por padrão, sua função disparada por HTTP é configurada para aceitar qualquer método HTTP.By default, your HTTP-triggered function is configured to accept any HTTP method. Também há uma URL padrão no formato http://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>.There is also a default URL of the form http://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>. Se você seguiu o guia de início rápido, <funcname> provavelmente se parece com algo como "HttpTriggerJS1".If you followed the quickstart, then <funcname> probably looks something like "HttpTriggerJS1". Nesta seção, você modificará a função para responder apenas a solicitações GET na rota /api/hello.In this section, you will modify the function to respond only to GET requests against /api/hello route instead.

  1. Navegue até sua função no Portal do Azure.Navigate to your function in the Azure portal. Selecione Integrar no painel de navegação esquerdo.Select Integrate in the left navigation.

    Personalizar uma função HTTP

  2. Use as configurações do gatilho HTTP conforme especificado na tabela.Use the HTTP trigger settings as specified in the table.

    CampoField Valor de exemploSample value DescriçãoDescription
    Métodos HTTP selecionadosAllowed HTTP methods Métodos selecionadosSelected methods Determina quais métodos HTTP podem ser usados para chamar essa funçãoDetermines what HTTP methods may be used to invoke this function
    Métodos HTTP selecionadosSelected HTTP methods OBTERGET Permite que apenas os métodos HTTP selecionados possam ser usados para chamar essa funçãoAllows only selected HTTP methods to be used to invoke this function
    Modelo de rotaRoute template /hello/hello Determina qual rota pode ser usada para chamar essa funçãoDetermines what route is used to invoke this function
    Nível de autorizaçãoAuthorization Level AnônimoAnonymous Opcional: Torna sua função acessível sem uma chave de APIOptional: Makes your function accessible without an API key

    Observação

    Observe que você não incluiu o prefixo de caminho base /api no modelo de rota, pois isso é tratado por uma configuração global.Note that you did not include the /api base path prefix in the route template, as this is handled by a global setting.

  3. Clique em Salvar.Click Save.

Você pode aprender mais sobre a personalização de funções HTTP em Associações de HTTP do Azure Functions.You can learn more about customizing HTTP functions in Azure Functions HTTP bindings.

Testar sua APITest your API

Em seguida, teste sua função para vê-la funcionando com a nova superfície de API.Next, test your function to see it working with the new API surface.

  1. Navegue de volta para a página de desenvolvimento clicando no nome da função no painel de navegação esquerdo.Navigate back to the development page by clicking on the function's name in the left navigation.
  2. Clique em Obter URL de função e copie a URL.Click Get function URL and copy the URL. Você verá que agora ela usa a rota /api/hello.You should see that it uses the /api/hello route now.
  3. Copie a URL em uma nova guia do navegador ou o cliente REST preferencial.Copy the URL into a new browser tab or your preferred REST client. Navegadores usarão GET por padrão.Browsers will use GET by default.
  4. Adicione parâmetros à cadeia de consulta na URL, por exemplo, /api/hello/?name=JohnAdd parameters to the query string in your URL e.g. /api/hello/?name=John
  5. Pressione “Enter” para confirmar se ela está funcionando.Hit 'Enter' to confirm that it is working. Você deverá ver a resposta “Hello JohnYou should see the response "Hello John"
  6. Você também pode tentar chamar o ponto de extremidade com outro método HTTP para confirmar a não execução da função.You can also try calling the endpoint with another HTTP method to confirm that the function is not executed. Para isso, será necessário usar um cliente REST, como cURL, Postman ou Fiddler.For this, you will need to use a REST client, such as cURL, Postman, or Fiddler.

Visão geral dos proxiesProxies overview

Na próxima seção, você mostrará sua API através de um proxy.In the next section, you will surface your API through a proxy. Os Proxies do Azure Functions permitem o encaminhamento de solicitações para outros recursos.Azure Functions Proxies allows you to forward requests to other resources. Defina um ponto de extremidade HTTP, como com o gatilho HTTP, mas em vez de escrever um código para executar durante a chamada para o ponto de extremidade, forneça uma URL para uma implementação remota.You define an HTTP endpoint just like with HTTP trigger, but instead of writing code to execute when that endpoint is called, you provide a URL to a remote implementation. Isso permite a composição de várias fontes de API em uma única superfície de API, o que é fácil para os clientes usarem.This allows you to compose multiple API sources into a single API surface which is easy for clients to consume. Isso é particularmente útil se você quiser criar sua API como microsserviços.This is particularly useful if you wish to build your API as microservices.

Um proxy pode apontar para qualquer recurso HTTP, como:A proxy can point to any HTTP resource, such as:

Para saber mais sobre proxies, confira Trabalhar com Proxies do Azure Functions.To learn more about proxies, see Working with Azure Functions Proxies.

Criar seu primeiro proxyCreate your first proxy

Nesta seção, você criará um novo proxy que servirá como um front-end para sua API geral.In this section, you will create a new proxy which serves as a frontend to your overall API.

Configurar o ambiente front-endSetting up the frontend environment

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.Repeat the steps to Create a function app to create a new function app in which you will create your proxy. A URL desse novo aplicativo funcionará como o front-end de nossa API e o aplicativo de função que você estava editando anteriormente funcionará como um back-end.This new app's URL will serve as the frontend for our API, and the function app you were previously editing will serve as a backend.

  1. Navegue até seu novo aplicativo de função front-end no portal.Navigate to your new frontend function app in the portal.

  2. Selecione Recursos de Plataforma e escolha Configurações de Aplicativo.Select Platform Features and choose Application Settings.

  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”.Scroll down to Application settings where key/value pairs are stored and create a new setting with key "HELLO_HOST". Defina o valor dela como o host de seu aplicativo de função de back-end, como <YourBackendApp>.azurewebsites.net.Set its value to the host of your backend function app, such as <YourBackendApp>.azurewebsites.net. Isso faz parte da URL que você copiou anteriormente ao testar sua função HTTP.This is part of the URL that you copied earlier when testing your HTTP function. Você fará referência a essa configuração mais adiante na configuração.You'll reference this setting in the configuration later.

    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.App settings are recommended for the host configuration to prevent a hard-coded environment dependency for the 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.Using app settings means that you can move the proxy configuration between environments, and the environment-specific app settings will be applied.

  4. Clique em Salvar.Click Save.

Criar um proxy no front-endCreating a proxy on the frontend

  1. Navegue novamente até seu aplicativo de função front-end no portal.Navigate back to your frontend function app in the portal.

  2. No painel de navegação esquerdo, clique no sinal '+' ao lado de "Proxies".In the left-hand navigation, click the plus sign '+' next to "Proxies". Criação de um proxyCreating a proxy

  3. Use as configurações de proxy conforme especificado na tabela.Use proxy settings as specified in the table.

    CampoField Valor de exemploSample value DescriçãoDescription
    NomeName HelloProxyHelloProxy Um nome amigável usado apenas para gerenciamentoA friendly name used only for management
    Modelo de rotaRoute template /api/remotehello/api/remotehello Determina qual rota pode ser usada para chamar esse proxyDetermines what route is used to invoke this proxy
    URL de Back-endBackend URL https://%HELLO_HOST%/api/hello Especifica o ponto de extremidade ao qual a solicitação deve ser transmitida por proxySpecifies the endpoint to which the request should be proxied
  4. Observe que os Proxies não fornecem o prefixo de caminho base /api, e ele deve ser incluído no modelo de rota.Note that Proxies does not provide the /api base path prefix, and this must be included in the route template.

  5. A sintaxe %HELLO_HOST% fará referência a configuração do aplicativo que você criou anteriormente.The %HELLO_HOST% syntax will reference the app setting you created earlier. A URL resolvida apontará para sua função original.The resolved URL will point to your original function.

  6. Clique em Criar.Click Create.

  7. Você pode testar seu novo proxy copiando a URL do Proxy e o testando no navegador ou com seu cliente HTTP favorito.You can try out your new proxy by copying the Proxy URL and testing it in the browser or with your favorite HTTP client.

    1. Para uma função anônima, use:For an anonymous function use:
      1. https://YOURPROXYAPP.azurewebsites.net/api/remotehello?name="Proxies"
    2. Para uma função com autorização, use:For a function with authorization use:
      1. https://YOURPROXYAPP.azurewebsites.net/api/remotehello?code=YOURCODE&name="Proxies"

Criar uma API de simulaçãoCreate a mock API

Em seguida, você usará um proxy para criar uma API de simulação para sua solução.Next, you will use a proxy to create a mock API for your solution. Isso permite o progresso do desenvolvimento do cliente, sem a necessidade de implementar totalmente o back-end.This allows client development to progress, without needing the backend fully implemented. Posteriormente no desenvolvimento, você poderá criar um novo aplicativo de função que oferece suporte a essa lógica e redirecionar seu proxy até ele.Later in development, you could create a new function app which supports this logic and redirect your proxy to it.

Para criar essa API de simulação, criaremos um novo proxy, dessa vez usando o Editor do Serviço de Aplicativo.To create this mock API, we will create a new proxy, this time using the App Service Editor. Para começar, navegue até seu aplicativo de função no portal.To get started, navigate to your function app in the portal. Selecione Recursos de plataforma e, em Ferramentas de Desenvolvimento, encontre Editor do Serviço de Aplicativo.Select Platform features and under Development Tools find App Service Editor. Clique nele para abrir o Editor de Serviço de Aplicativo em uma nova guia.Clicking this will open the App Service Editor in a new tab.

Selecione proxies.json no painel de navegação esquerdo.Select proxies.json in the left navigation. Este é o arquivo que armazena a configuração de todos os seus proxies.This is the file which stores the configuration for all of your proxies. Se você usar um dos métodos de implantação do Functions, esse será o arquivo mantido no controle de origem.If you use one of the Functions deployment methods, this is the file you will maintain in source control. Para saber mais sobre esse arquivo, confira Configuração avançada de proxies.To learn more about this file, see Proxies advanced configuration.

Se você acompanhou até agora, o proxies.json deve ser semelhante ao seguinte:If you've followed along so far, your proxies.json should look like the following:

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

Em seguida, você adicionará sua API de simulação.Next you'll add your mock API. Substitua o arquivo proxies.json pelo seguinte:Replace your proxies.json file with the following:

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

Isso adiciona um novo proxy "GetUserByName", sem a propriedade backendUri.This adds a new proxy, "GetUserByName", without the backendUri property. Em vez de chamar outro recurso, ele modifica a resposta padrão dos Proxies usando uma substituição de resposta.Instead of calling another resource, it modifies the default response from Proxies using a response override. Substituições de solicitação e resposta também podem ser usadas em conjunto com uma URL de back-end.Request and response overrides can also be used in conjunction with a backend URL. Isso é particularmente útil ao transmitir por proxy para um sistema herdado, quando talvez você precise 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.This is particularly useful when proxying to a legacy system, where you might need to modify headers, query parameters, etc. To learn more about request and response overrides, see Modifying requests and responses in 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.Test your mock API by calling the <YourProxyApp>.azurewebsites.net/api/users/{username} endpoint using a browser or your favorite REST client. Não deixe de substituir {username} por um valor de cadeia de caracteres que represente um nome de usuário.Be sure to replace {username} with a string value representing a username.

Próximas etapasNext steps

Neste artigo, você aprendeu como criar e personalizar uma API no Azure Functions.In this article, you learned how to build and customize an API on Azure Functions. Você também aprendeu a unir várias APIs, incluindo objetos fictícios, como uma superfície de API unificada.You also learned how to bring multiple APIs, including mocks, together as a unified API surface. 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.You can use these techniques to build out APIs of any complexity, all while running on the serverless compute model provided by Azure Functions.

As referências a seguir podem ser úteis durante o desenvolvimento de sua API:The following references may be helpful as you develop your API further: