Trabalhar com os Proxies de funções do AzureWork with Azure Functions Proxies

Este artigo explica como configurar e trabalhar com os Proxies de funções do Azure.This article explains how to configure and work with Azure Functions Proxies. Com esta funcionalidade, pode especificar pontos finais na sua aplicação de funções que são implementados por outro recurso.With this feature, you can specify endpoints on your function app that are implemented by another resource. Pode utilizar estes proxies para dividir uma API grande em várias aplicações de funções (como numa arquitetura de microsserviços), mas apresentando uma única superfície de API para os clientes.You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.

Estas são informações de referência para programadores das funções do Azure.This is reference information for Azure Functions developers. Se estiver familiarizado com as funções do Azure, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Nota

As funções padrão de faturação que se aplica a execuções de proxy.Standard Functions billing applies to proxy executions. Para obter mais informações, consulte preços de funções do Azure.For more information, see Azure Functions pricing.

Criar um proxyCreate a proxy

Esta secção mostra-lhe como criar um proxy no portal de funções.This section shows you how to create a proxy in the Functions portal.

  1. Abra o portal do Azuree, em seguida, vá para a aplicação de funções.Open the Azure portal, and then go to your function app.
  2. No painel esquerdo, selecione novo proxy.In the left pane, select New proxy.
  3. Forneça um nome para o proxy.Provide a name for your proxy.
  4. Configurar o ponto final que é exposto nesta aplicação de função, especificando o modelo de rota e métodos HTTP.Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. Se comportam estes parâmetros, de acordo com as regras para acionadores HTTP.These parameters behave according to the rules for HTTP triggers.
  5. Definir o URL de back-end para outro ponto final.Set the backend URL to another endpoint. Este ponto final pode ser uma função na outra aplicação de função, ou pode ser qualquer outra API.This endpoint could be a function in another function app, or it could be any other API. O valor não precisa de ser estáticos e pode referenciar Definições da aplicação e parâmetros do pedido de cliente original.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. Clique em Criar.Click Create.

O proxy agora existe como um novo ponto final na sua aplicação de funções.Your proxy now exists as a new endpoint on your function app. Da perspectiva do cliente, é equivalente a um HttpTrigger nas funções do Azure.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. Pode experimentar o seu novo proxy ao copiar o URL de Proxy e testá-lo com o seu cliente favorito de HTTP.You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

Modificar as solicitações e respostasModify requests and responses

Com os Proxies de funções do Azure, pode modificar as solicitações e respostas de back-end.With Azure Functions Proxies, you can modify requests to and responses from the back-end. Essas transformações podem utilizar variáveis, conforme definido na utilizar variáveis.These transformations can use variables as defined in Use variables.

Modificar o pedido de back-endModify the back-end request

Por predefinição, o pedido de back-end é inicializado como uma cópia do pedido original.By default, the back-end request is initialized as a copy of the original request. Além de definir o URL de back-end, pode efetuar alterações para o método HTTP, cabeçalhos e os parâmetros de cadeia de caracteres de consulta.In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. Podem referenciar os valores modificados Definições da aplicação e parâmetros do pedido de cliente original.The modified values can reference application settings and parameters from the original client request.

As solicitações de back-end podem ser modificadas no portal expandindo a seção de substituição de solicitação da página de detalhes do proxy.Back-end requests can be modified in the portal by expanding the request override section of the proxy detail page.

Modificar a respostaModify the response

Por predefinição, a resposta do cliente é inicializada como uma cópia da resposta de back-end.By default, the client response is initialized as a copy of the back-end response. Pode efetuar alterações ao código de estado, frase da razão, cabeçalhos e corpo da resposta.You can make changes to the response's status code, reason phrase, headers, and body. Podem referenciar os valores modificados Definições da aplicação, parâmetros do pedido de cliente original, e parâmetros da resposta de back-end.The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.

As solicitações de back-end podem ser modificadas no portal expandindo a seção de substituição de resposta da página de detalhes do proxy.Back-end requests can be modified in the portal by expanding the response override section of the proxy detail page.

Utilizar variáveisUse variables

A configuração de um proxy não precisa de ser estáticos.The configuration for a proxy does not need to be static. Pode de condição-o para utilizar variáveis a partir do pedido do cliente original, a resposta de back-end ou as definições da aplicação.You can condition it to use variables from the original client request, the back-end response, or application settings.

Funções de locais de referênciaReference local functions

Pode usar localhost para fazer referência a uma função na mesma aplicação de função diretamente, sem um pedido de proxy de ida e volta.You can use localhost to reference a function inside the same function app directly, without a roundtrip proxy request.

"backendurl": "https://localhost/api/httptriggerC#1" fará referência uma função acionada por HTTP local na rota /api/httptriggerC#1"backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

Nota

Se utilizar a sua função função, administrador ou sys níveis de autorização, precisará fornecer o código e o ID de cliente, de acordo com o URL da função original.If your function uses function, admin or sys authorization levels, you will need to provide the code and clientId, as per the original function URL. Nesse caso, a referência ficaria assim: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>"É recomendável armazenar essas chaves nas Definições da aplicação e fazer referência a elas em seus proxies.In this case the reference would look like: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" We recommend storing these keys in application settings and referencing those in your proxies. Isso evita o armazenamento de segredos em seu código-fonte.This avoids storing secrets in your source code.

Parâmetros do pedido de referênciaReference request parameters

Pode utilizar parâmetros do pedido como entradas para a propriedade de URL de back-end ou como parte de modificação de solicitações e respostas.You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. Alguns parâmetros podem ser ligados a partir do modelo de rota que é especificado na configuração do proxy de base e outras pessoas podem vir de propriedades do pedido a receber.Some parameters can be bound from the route template that's specified in the base proxy configuration, and others can come from properties of the incoming request.

Parâmetros de modelo de rotaRoute template parameters

Parâmetros que são utilizados no modelo de rota estão disponíveis para ser referenciado por nome.Parameters that are used in the route template are available to be referenced by name. Os nomes de parâmetro são colocados entre chavetas ({}).The parameter names are enclosed in braces ({}).

Por exemplo, se um proxy, tem um modelo de rota, como /pets/{petId}, o URL de back-end pode incluir o valor de {petId}, como em https://<AnotherApp>.azurewebsites.net/api/pets/{petId}.For example, if a proxy has a route template, such as /pets/{petId}, the back-end URL can include the value of {petId}, as in https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Se o modelo de rota termina no caráter universal, por exemplo, /api/{*restOfPath}, o valor {restOfPath} é uma representação de cadeia de caracteres de segmentos de caminho restantes da solicitação recebida.If the route template terminates in a wildcard, such as /api/{*restOfPath}, the value {restOfPath} is a string representation of the remaining path segments from the incoming request.

Parâmetros de pedido adicionaisAdditional request parameters

Além de parâmetros de modelo de rota, os seguintes valores podem ser utilizados em valores de configuração:In addition to the route template parameters, the following values can be used in config values:

  • {request.method} : O método HTTP usado na solicitação original.{request.method}: The HTTP method that's used on the original request.
  • {Request. Headers< . HeaderName>} : Um cabeçalho que pode ser lido da solicitação original.{request.headers.<HeaderName>}: A header that can be read from the original request. Substitua <HeaderName> com o nome do cabeçalho que queira ler.Replace <HeaderName> with the name of the header that you want to read. Se o cabeçalho não está incluído na solicitação, o valor será a cadeia vazia.If the header is not included on the request, the value will be the empty string.
  • {request.querystring.<ParameterName>} : Um parâmetro de cadeia de caracteres de consulta que pode ser lido da solicitação original.{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. Substitua <ParameterName> com o nome do parâmetro que pretende ler.Replace <ParameterName> with the name of the parameter that you want to read. Se o parâmetro não está incluído na solicitação, o valor será a cadeia vazia.If the parameter is not included on the request, the value will be the empty string.

Parâmetros de resposta de back-end de referênciaReference back-end response parameters

Parâmetros de resposta podem ser utilizados como parte de modificar a resposta ao cliente.Response parameters can be used as part of modifying the response to the client. Os seguintes valores podem ser utilizados em valores de configuração:The following values can be used in config values:

  • {backend.response.statusCode} : O código de status HTTP que é retornado na resposta de back-end.{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason} : A frase de motivo HTTP que é retornada na resposta de back-end.{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {back-end. Response.< Headers. HeaderName>} : Um cabeçalho que pode ser lido da resposta de back-end.{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. Substitua <HeaderName> com o nome do cabeçalho que pretende ler.Replace <HeaderName> with the name of the header you want to read. Se o cabeçalho não está incluído na resposta, o valor será a cadeia vazia.If the header is not included on the response, the value will be the empty string.

Definições da aplicação de referênciaReference application settings

Também pode fazer referência as definições da aplicação definidas para a aplicação de funções rodeando o nome da definição com símbolos de percentagem (%).You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

Por exemplo, um URL de back-end de https://%ORDER_PROCESSING_HOST%/api/orders teria "ORDER_PROCESSING_HOST %" substituída pelo valor da definição ORDER_PROCESSING_HOST.For example, a back-end URL of https://%ORDER_PROCESSING_HOST%/api/orders would have "%ORDER_PROCESSING_HOST%" replaced with the value of the ORDER_PROCESSING_HOST setting.

Dica

Utilize as definições da aplicação para os anfitriões de back-end se tiver várias implementações ou ambientes de teste.Use application settings for back-end hosts when you have multiple deployments or test environments. Dessa forma, pode tornar-se de que estamos a falar sempre para o back-end certo para esse ambiente.That way, you can make sure that you are always talking to the right back-end for that environment.

Resolver problemas de ProxiesTroubleshoot Proxies

Ao adicionar o sinalizador "debug":true para qualquer proxy na sua proxies.json irá ativar o registo de depuração.By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. Os registos são armazenados em D:\home\LogFiles\Application\Proxies\DetailedTrace e acessível através das ferramentas avançadas (kudu).Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). As respostas HTTP também conterá uma Proxy-Trace-Location cabeçalho com um URL para aceder ao ficheiro de registo.Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

Pode depurar um proxy do lado do cliente ao adicionar um Proxy-Trace-Enabled cabeçalho definido como true.You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. Isto também um rastreio de registo para o sistema de ficheiros e retornasse a URL de rastreio como um cabeçalho na resposta.This will also log a trace to the file system, and return the trace URL as a header in the response.

Rastreios de proxy do blocoBlock proxy traces

Por motivos de segurança poderá não permitir que qualquer pessoa que chamar o seu serviço para gerar um rastreamento.For security reasons you may not want to allow anyone calling your service to generate a trace. Não poderão acessar o conteúdo de rastreio sem as suas credenciais de início de sessão, mas a gerar o rastreio consome recursos e expõe o que está a utilizar Proxies de funções.They will not be able to access the trace contents without your login credentials, but generating the trace consumes resources and exposes that you are using Function Proxies.

Desativar completamente os rastreios adicionando "debug":false para qualquer proxy específico na sua proxies.json.Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

Configuração avançadaAdvanced configuration

Os proxies que configurar são armazenados num proxies arquivo, o que está localizado na raiz de um diretório de aplicação de função.The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. Pode editar este ficheiro manualmente e implementá-lo como parte da sua aplicação ao utilizar qualquer um da métodos de implantação que suporta as funções.You can manually edit this file and deploy it as part of your app when you use any of the deployment methods that Functions supports.

Dica

Se não tiver definido um dos métodos de implementação, também pode trabalhar com o proxies ficheiro no portal.If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. Aceda à sua aplicação de função, selecione funcionalidades de plataformae, em seguida, selecione Editor do serviço de aplicações.Go to your function app, select Platform features, and then select App Service Editor. Ao fazer isso, pode ver a estrutura de arquivo inteiro da sua aplicação de função e, em seguida, fazer alterações.By doing so, you can view the entire file structure of your function app and then make changes.

Proxies é definido por um objeto de proxies, que é composto por proxies nomeados e as respetivas definições.Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. Opcionalmente, se o seu editor de suportar, pode referenciar um esquema JSON pela conclusão de código.Optionally, if your editor supports it, you can reference a JSON schema for code completion. Um exemplo de arquivo pode ter o seguinte aspeto:An example file might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Cada proxy tem um nome amigável, como proxy1 no exemplo anterior.Each proxy has a friendly name, such as proxy1 in the preceding example. O objeto de definição de proxy correspondente é definido pelas seguintes propriedades:The corresponding proxy definition object is defined by the following properties:

  • matchCondition: Obrigatório--um objeto que define as solicitações que disparam a execução desse proxy.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. Ele contém duas propriedades que são partilhadas com acionadores HTTP:It contains two properties that are shared with HTTP triggers:
    • métodos: Uma matriz dos métodos HTTP aos quais o proxy responde.methods: An array of the HTTP methods that the proxy responds to. Se não for especificado, o proxy responde a todos os métodos HTTP na rota.If it is not specified, the proxy responds to all HTTP methods on the route.
    • rota: Obrigatório – define o modelo de rota, controlando a quais URLs de solicitação seu proxy responde.route: Required--defines the route template, controlling which request URLs your proxy responds to. Ao contrário de acionadores HTTP, não existe nenhum valor predefinido.Unlike in HTTP triggers, there is no default value.
  • backendUri: A URL do recurso de back-end para o qual a solicitação deve ser proxy.backendUri: The URL of the back-end resource to which the request should be proxied. Este valor pode referenciar as definições da aplicação e os parâmetros do pedido de cliente original.This value can reference application settings and parameters from the original client request. Se esta propriedade não está incluída, as funções do Azure responde com um HTTP 200 OK.If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides: Um objeto que define as transformações para a solicitação de back-end.requestOverrides: An object that defines transformations to the back-end request. Ver definir um objeto de requestOverrides.See Define a requestOverrides object.
  • responseOverrides: Um objeto que define as transformações para a resposta do cliente.responseOverrides: An object that defines transformations to the client response. Ver definir um objeto de responseOverrides.See Define a responseOverrides object.

Nota

O rota propriedade nos Proxies de funções do Azure não cumpra o routePrefix propriedade da configuração do anfitrião de aplicação de funções.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Se quiser incluir um prefixo, como /api, tem de ser incluído nos rota propriedade.If you want to include a prefix such as /api, it must be included in the route property.

Desativar os proxies individuaisDisable individual proxies

Pode desativar os proxies individuais, adicionando "disabled": true para o proxy no proxies.json ficheiro.You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. Isso fará com que as solicitações que atendem ao matchCondition retornem 404.This will cause any requests meeting the matchCondition to return 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Definições da aplicaçãoApplication Settings

O comportamento de proxy pode ser controlado por várias configurações de aplicação.The proxy behavior can be controlled by several app settings. Todos estão descritas no referência das definições de aplicação de funçõesThey are all outlined in the Functions App Settings reference

Carateres reservados (cadeia de caracteres de formatação)Reserved Characters (string formatting)

Os proxies lêem todas as cadeias de caracteres de um arquivo JSON, usando \ como um símbolo de escape.Proxies read all strings out of a JSON file, using \ as an escape symbol. Os proxies também interpretam chaves.Proxies also interpret curly braces. Veja um conjunto completo de exemplos abaixo.See a full set of examples below.

CaráterCharacter Caráter de escapeEscaped Character ExemploExample
{ou}{ or } {{ou}}{{ or }} {{ example }} --> { example }
\ \\ example.com\\text.html --> example.com\text.html
"" \" \"example\" --> "example"

Definir um objeto de requestOverridesDefine a requestOverrides object

O objeto de requestOverrides define as alterações feitas à solicitação quando o recurso de back-end é chamado.The requestOverrides object defines changes made to the request when the back-end resource is called. O objeto é definido pelas seguintes propriedades:The object is defined by the following properties:

  • backend.request.method: O método HTTP usado para chamar o back-end.backend.request.method: The HTTP method that's used to call the back-end.
  • backend.request.querystring.<ParameterName> : Um parâmetro de cadeia de caracteres de consulta que pode ser definido para a chamada para o back-end.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Substitua <ParameterName> com o nome do parâmetro que pretende definir.Replace <ParameterName> with the name of the parameter that you want to set. Se não for fornecida a cadeia vazia, o parâmetro não está incluído no pedido de back-end.If the empty string is provided, the parameter is not included on the back-end request.
  • backend.request.headers.<HeaderName> : Um cabeçalho que pode ser definido para a chamada para o back-end.backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. Substitua <HeaderName> com o nome do cabeçalho que queira definir.Replace <HeaderName> with the name of the header that you want to set. Se fornecer a cadeia vazia, o cabeçalho não está incluído no pedido de back-end.If you provide the empty string, the header is not included on the back-end request.

Valores podem referenciar as definições da aplicação e os parâmetros do pedido de cliente original.Values can reference application settings and parameters from the original client request.

Um exemplo de configuração pode ter um aspeto semelhante ao seguinte:An example configuration might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

Definir um objeto de responseOverridesDefine a responseOverrides object

O objeto de requestOverrides define as alterações efetuadas à resposta que é transmitida ao cliente.The requestOverrides object defines changes that are made to the response that's passed back to the client. O objeto é definido pelas seguintes propriedades:The object is defined by the following properties:

  • response.statusCode: O código de status HTTP a ser retornado ao cliente.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: A frase de motivo HTTP a ser retornada ao cliente.response.statusReason: The HTTP reason phrase to be returned to the client.
  • resposta. corpo: A representação da cadeia de caracteres do corpo a ser retornado ao cliente.response.body: The string representation of the body to be returned to the client.
  • response.headers.<HeaderName> : Um cabeçalho que pode ser definido para a resposta ao cliente.response.headers.<HeaderName>: A header that can be set for the response to the client. Substitua <HeaderName> com o nome do cabeçalho que queira definir.Replace <HeaderName> with the name of the header that you want to set. Se fornecer a cadeia vazia, o cabeçalho não está incluído na resposta.If you provide the empty string, the header is not included on the response.

Valores podem referenciar as definições da aplicação, parâmetros de pedido do cliente original e os parâmetros da resposta de back-end.Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Um exemplo de configuração pode ter um aspeto semelhante ao seguinte:An example configuration might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

Nota

Neste exemplo, o corpo da resposta é definido diretamente, por isso, não backendUri propriedade é necessária.In this example, the response body is set directly, so no backendUri property is needed. O exemplo mostra como pode utilizar os Proxies de funções do Azure para a simulação de APIs.The example shows how you might use Azure Functions Proxies for mocking APIs.