Trabalhar com proxies herdados

Artigo
02/28/2024

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.

Para ajudar a facilitar a migração de implementações de proxy existentes, este artigo contém links para conteúdo equivalente de Gerenciamento de API, quando disponível.

Este artigo explica como configurar e trabalhar com Proxies do Azure Functions. Com esse recurso, você pode especificar pontos de extremidade em seu aplicativo de função que são implementados por outro recurso. Você pode usar esses proxies para dividir uma API grande em vários aplicativos de função (como em uma arquitetura de microsserviço), enquanto ainda apresenta uma única superfície de API para clientes.

A cobrança de Funções Padrão aplica-se a execuções de proxy. Para obter mais informações, consulte Preços do Azure Functions.

Reativar proxies no Functions v4.x

Depois de migrar seu aplicativo de função para a versão 4.x do tempo de execução do Functions, você precisará reativar especificamente os proxies. Você ainda deve alternar para integrar seus aplicativos de função com o Gerenciamento de API do Azure o mais rápido possível, e não depender apenas de proxies.

A reativação de proxies requer que você defina um sinalizador na configuração do AzureWebJobsFeatureFlags aplicativo de uma das seguintes maneiras:

Se a AzureWebJobsFeatureFlags configuração ainda não existir, adicione essa configuração ao seu aplicativo de função com o valor de EnableProxies.
Se essa configuração já existir, adicione ,EnableProxies ao final do valor existente.

AzureWebJobsFeatureFlags é uma matriz delimitada por vírgulas de sinalizadores usados para habilitar a visualização e outros recursos temporários. Para saber mais sobre como criar e modificar configurações de aplicativos, consulte Trabalhar com configurações de aplicativos.

Nota

Mesmo quando reativado usando o EnableProxies sinalizador, você não pode trabalhar com proxies no portal do Azure. Em vez disso, você deve trabalhar diretamente com o arquivo de proxies.json para seu aplicativo de função. Para obter mais informações, consulte Configuração avançada.

Criar um proxy

Importante

Para obter conteúdo equivalente usando o Gerenciamento de API, consulte Expor APIs sem servidor de pontos de extremidade HTTP usando o Gerenciamento de API do Azure.

Os proxies são definidos no arquivo proxies.json na raiz do seu aplicativo de função. As etapas nesta seção mostram como usar o portal do Azure para criar esse arquivo em seu aplicativo de função. Nem todos os idiomas e combinações de sistemas operacionais suportam edição no portal. Se não for possível modificar os arquivos do aplicativo de função no portal, você poderá criar e implantar o arquivo equivalente proxies.json a partir da raiz da pasta do projeto local. Para saber mais sobre o suporte à edição do portal, consulte Detalhes do suporte de idiomas.

Abra o portal do Azure e vá para seu aplicativo de função.
No painel esquerdo, selecione Proxies e, em seguida, selecione +Adicionar.
Forneça um nome para seu proxy.
Configure o ponto de extremidade exposto neste aplicativo de função especificando o modelo de rota e os métodos HTTP. Esses parâmetros se comportam de acordo com as regras para gatilhos HTTP.
Defina a URL de back-end para outro ponto de extremidade. Esse ponto de extremidade pode ser uma função em outro aplicativo de função ou pode ser qualquer outra API. O valor não precisa ser estático e pode fazer referência às configurações e parâmetros do aplicativo a partir da solicitação original do cliente.
Selecione Criar.

Seu proxy agora existe como um novo ponto de extremidade em seu aplicativo de função. Do ponto de vista do cliente, é o mesmo que um HttpTrigger no Functions. Você pode experimentar seu novo proxy copiando a URL do proxy e testando-a com seu cliente HTTP favorito.

Modificar solicitações e respostas

Importante

O Gerenciamento de API permite que você altere o comportamento da API por meio da configuração usando políticas. As políticas são uma coleção de instruções que são executadas sequencialmente no pedido ou na resposta de uma API. Para obter mais informações sobre políticas de Gerenciamento de API, consulte Políticas no Gerenciamento de API do Azure.

Com proxies, você pode modificar solicitações e respostas do back-end. Essas transformações podem usar variáveis conforme definido em Variáveis de uso.

Modificar a solicitação de back-end

Por padrão, a solicitação de back-end é inicializada como uma cópia da solicitação original. Além de definir a URL de back-end, você pode fazer alterações no método HTTP, cabeçalhos e parâmetros de cadeia de caracteres de consulta. Os valores modificados podem fazer referência às configurações e parâmetros do aplicativo a partir da solicitação original do cliente.

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.

Modificar a resposta

Por padrão, a resposta do cliente é inicializada como uma cópia da resposta de back-end. Você pode fazer alterações no código de status, na frase de motivo, nos cabeçalhos e no corpo da resposta. Os valores modificados podem fazer referência às configurações do aplicativo, parâmetros da solicitação do cliente original e parâmetros da resposta de back-end.

As respostas de back-end podem ser modificadas no portal expandindo a seção de substituição de resposta da página de detalhes do proxy.

Utilizar variáveis

A configuração de um proxy não precisa ser estática. Você pode condicioná-lo para usar variáveis da solicitação original do cliente, da resposta de back-end ou das configurações do aplicativo.

Funções locais de referência

Você pode usar localhost para fazer referência a uma função dentro do mesmo aplicativo de função diretamente, sem uma solicitação de proxy de ida e volta.

"backendUri": "https://localhost/api/httptriggerC#1" fará referência a uma função acionada HTTP local na rota /api/httptriggerC#1

Nota

Se sua função usa níveis de autorização de função, admin ou sys , você precisará fornecer o código e clientId, de acordo com a URL da função original. Neste caso, a referência seria semelhante a: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" Recomendamos armazenar essas chaves nas configurações do aplicativo e fazer referência a elas em seus proxies. Isso evita armazenar segredos em seu código-fonte.

Parâmetros de solicitação de referência

Você pode usar parâmetros de solicitação como entradas para a propriedade URL de back-end ou como parte da modificação de solicitações e respostas. Alguns parâmetros podem ser vinculados a partir do modelo de rota especificado na configuração de proxy base, e outros podem vir das propriedades da solicitação de entrada.

Parâmetros do modelo de rota

Os parâmetros usados no modelo de rota estão disponíveis para serem referenciados pelo nome. Os nomes dos parâmetros são colocados entre chaves ({}).

Por exemplo, se um proxy tiver um modelo de rota, como /pets/{petId}, a URL de back-end poderá incluir o valor de {petId}, como em https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Se o modelo de rota terminar em um curinga, como /api/{*restOfPath}, o valor {restOfPath} será uma representação de cadeia de caracteres dos segmentos de caminho restantes da solicitação de entrada.

Parâmetros de solicitação adicionais

Além dos parâmetros do modelo de rota, os seguintes valores podem ser usados em valores de configuração:

{request.method}: O método HTTP usado na solicitação original.
{request.headers.<HeaderName>}: Um cabeçalho que pode ser lido a partir da solicitação original. Substitua <HeaderName> pelo nome do cabeçalho que você deseja ler. Se o cabeçalho não estiver incluído na solicitação, o valor será a cadeia de caracteres vazia.
{Request.queryString.<ParameterName>}: um parâmetro de cadeia de caracteres de consulta que pode ser lido a partir da solicitação original. Substitua <ParameterName> pelo nome do parâmetro que você deseja ler. Se o parâmetro não estiver incluído na solicitação, o valor será a cadeia de caracteres vazia.

Parâmetros de resposta back-end de referência

Os parâmetros de resposta podem ser usados como parte da modificação da resposta ao cliente. Os seguintes valores podem ser usados em valores de configuração:

{backend.response.statusCode}: O código de status HTTP retornado na resposta de back-end.
{backend.response.statusReason}: A frase de razão HTTP que é retornada na resposta de back-end.
{backend.response.headers.<HeaderName>}: Um cabeçalho que pode ser lido a partir da resposta de back-end. Substitua <HeaderName> pelo nome do cabeçalho que você deseja ler. Se o cabeçalho não estiver incluído na resposta, o valor será a cadeia de caracteres vazia.

Configurações do aplicativo de referência

Você também pode fazer referência às configurações do aplicativo definidas para o aplicativo de função cercando o nome da configuração com sinais de porcentagem (%).

Por exemplo, uma URL de back-end de https://%ORDER_PROCESSING_HOST%/api/orders teria "%ORDER_PROCESSING_HOST%" substituído pelo valor da configuração ORDER_PROCESSING_HOST.

Gorjeta

Use as configurações do aplicativo para hosts back-end quando tiver várias implantações ou ambientes de teste. Dessa forma, você pode ter certeza de que está sempre conversando com o back-end certo para aquele ambiente.

Solucionar problemas de proxies

Ao adicionar o sinalizador "debug":true a qualquer proxy no , proxies.jsonvocê habilitará o log de depuração. Os logs são armazenados D:\home\LogFiles\Application\Proxies\DetailedTrace e acessíveis através das ferramentas avançadas (kudu). Todas as respostas HTTP também conterão um Proxy-Trace-Location cabeçalho com uma URL para acessar o arquivo de log.

Você pode depurar um proxy do lado do cliente adicionando um Proxy-Trace-Enabled cabeçalho definido como true. Isso também registrará um rastreamento no sistema de arquivos e retornará a URL de rastreamento como um cabeçalho na resposta.

Bloquear rastreamentos de proxy

Por motivos de segurança, talvez você não queira permitir que qualquer pessoa que ligue para o seu serviço gere um rastreamento. Eles não poderão acessar o conteúdo do rastreamento sem suas credenciais de entrada, mas gerar o rastreamento consome recursos e expõe que você está usando Proxies de Função.

Desative completamente os rastreamentos adicionando "debug":false a qualquer proxy específico em seu proxies.json.

Configuração avançada

Os proxies que você configura são armazenados em um arquivo proxies.json , que está localizado na raiz de um diretório de aplicativo de função. Você pode editar manualmente esse arquivo e implantá-lo como parte do seu aplicativo quando usar qualquer um dos métodos de implantação suportados pelo Functions.

Gorjeta

Se você não configurou um dos métodos de implantação, também pode trabalhar com o arquivo proxies.json no portal. Aceda à sua aplicação funcional, selecione Funcionalidades da plataforma e, em seguida, selecione Editor do Serviço de Aplicação. Ao fazer isso, você pode exibir toda a estrutura de arquivos do seu aplicativo de função e, em seguida, fazer alterações.

Proxies.json é definido por um objeto proxies, que é composto por proxies nomeados e suas definições. Opcionalmente, se o editor oferecer suporte a ele, você poderá fazer referência a um esquema JSON para conclusão de código. Um arquivo de exemplo pode ter a seguinte aparência:

{
    "$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. O objeto de definição de proxy correspondente é definido pelas seguintes propriedades:

matchCondition: Required--um objeto que define as solicitações que acionam a execução desse proxy. Ele contém duas propriedades que são compartilhadas com gatilhos HTTP:
- métodos: Uma matriz dos métodos HTTP aos quais o proxy responde. Se não for especificado, o proxy responderá a todos os métodos HTTP na rota.
- route: Required--define o modelo de rota, controlando a quais URLs de solicitação seu proxy responde. Ao contrário dos gatilhos HTTP, não há nenhum valor padrão.
backendUri: A URL do recurso de back-end para o qual a solicitação deve ser intermediada. Esse valor pode fazer referência às configurações e parâmetros do aplicativo a partir da solicitação original do cliente. Se essa propriedade não estiver incluída, o Azure Functions responderá com um HTTP 200 OK.
requestOverrides: um objeto que define transformações para a solicitação de back-end. Consulte Definir um objeto requestOverrides.
responseOverrides: um objeto que define transformações para a resposta do cliente. Consulte Definir um objeto responseOverrides.

Nota

A propriedade route nos Proxies do Azure Functions não honra a propriedade routePrefix da configuração de host do Aplicativo de Função. Se você quiser incluir um prefixo como /api, ele deve ser incluído na propriedade route.

Desativar proxies individuais

Você pode desativar proxies individuais adicionando "disabled": true ao proxy no proxies.json arquivo. Isso fará com que todas as solicitações que atendam à matchCondition retornem 404.

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

Definições de Aplicação

O comportamento do proxy pode ser controlado por várias configurações do aplicativo. Todos eles estão descritos na referência Configurações do aplicativo Functions

Caracteres reservados (formatação de cadeia de caracteres)

Os proxies leem todas as cadeias de caracteres de um arquivo JSON, usando \ como um símbolo de escape. Os proxies também interpretam chaves encaracoladas. Veja um conjunto completo de exemplos abaixo.

Caráter	Personagem escapado	Exemplo
{ ou }	{{ ou }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

Definir um objeto requestOverrides

O objeto requestOverrides define as alterações feitas na solicitação quando o recurso back-end é chamado. O objeto é definido pelas seguintes propriedades:

backend.request.method: O método HTTP usado para chamar o 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. Substitua <ParameterName> pelo nome do parâmetro que você deseja definir. Se uma cadeia de caracteres vazia for fornecida, o parâmetro ainda será incluído na solicitação de back-end.
backend.request.headers.<HeaderName>: um cabeçalho que pode ser definido para a chamada para o back-end. Substitua <HeaderName> pelo nome do cabeçalho que você deseja definir. Se uma cadeia de caracteres vazia for fornecida, o parâmetro ainda será incluído na solicitação de back-end.

Os valores podem fazer referência às configurações e parâmetros do aplicativo a partir da solicitação original do cliente.

Um exemplo de configuração pode ter a seguinte aparência:

{
    "$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 responseOverrides

O objeto requestOverrides define as alterações feitas na resposta que é passada de volta para o cliente. O objeto é definido pelas seguintes propriedades:

response.statusCode: O código de status HTTP a ser retornado ao cliente.
response.statusReason: A frase de razão HTTP a ser retornada ao cliente.
response.body: A representação de cadeia de caracteres do corpo a ser retornado ao cliente.
response.headers.<HeaderName>: Um cabeçalho que pode ser definido para a resposta ao cliente. Substitua <HeaderName> pelo nome do cabeçalho que você deseja definir. Se você fornecer a cadeia de caracteres vazia, o cabeçalho não será incluído na resposta.

Os valores podem fazer referência às configurações do aplicativo, aos parâmetros da solicitação original do cliente e aos parâmetros da resposta de back-end.

Um exemplo de configuração pode ter a seguinte aparência:

{
    "$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, portanto, nenhuma backendUri propriedade é necessária. O exemplo mostra como você pode usar os Proxies do Azure Functions para simular APIs.

Trabalhar com proxies herdados

Reativar proxies no Functions v4.x

Criar um proxy

Modificar solicitações e respostas

Modificar a solicitação de back-end

Modificar a resposta

Utilizar variáveis

Funções locais de referência

Parâmetros de solicitação de referência

Parâmetros do modelo de rota

Parâmetros de solicitação adicionais

Parâmetros de resposta back-end de referência

Configurações do aplicativo de referência

Solucionar problemas de proxies

Bloquear rastreamentos de proxy

Configuração avançada

Desativar proxies individuais

Definições de Aplicação

Caracteres reservados (formatação de cadeia de caracteres)

Definir um objeto requestOverrides

Definir um objeto responseOverrides

Recursos adicionais