Share via

Trabalhar com os proxies herdados

  • Artigo

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.

Para ajudar a facilitar a migração das implementações de proxy existentes, este artigo se vincula ao conteúdo equivalente do Gerenciamento de API, quando disponível.

Este artigo explica como configurar e trabalhar com proxies do Azure Functions. Com esse recurso, você pode especificar os pontos de extremidade em seu aplicativo de funções 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 uma arquitetura de microsserviços), enquanto ainda apresenta uma única superfície de API para clientes.

A cobrança do Standard Functions se aplica para execuções de proxy. Para saber mais, confira Preços do Azure Functions.

Reabilitar proxies no Functions v4.x

Depois de migrar seu aplicativo de funções para a versão 4.x do runtime do Functions, você precisa reabilitar especificamente os proxies. Você ainda deve alternar para integrar seus aplicativos de funções ao Gerenciamento de API do Azure o mais rápido possível e não contar apenas com os proxies.

Habilitar novamente os proxies exige que você defina um sinalizador na configuração de aplicativo AzureWebJobsFeatureFlags de uma das seguintes maneiras:

  • Se a configuração AzureWebJobsFeatureFlags ainda não existir, adicione essa configuração ao seu aplicativo de funções com um 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 usada para habilitar a versão prévia e outros recursos temporários. Para saber mais sobre como criar e modificar as configurações do aplicativo, confira Trabalhar com as configurações de aplicativo.

Observação

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

Criar um proxy

Importante

Para ver um conteúdo equivalente usando o Gerenciamento de API, confira Expor as 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 aplicativo de funções. As etapas desta seção mostram como usar o portal do Azure para criar esse arquivo no aplicativo de funções. Nem todas as linguagens e combinações de sistemas operacionais dão suporte à edição no portal. Se você não puder modificar os arquivos do aplicativo de funções no portal, poderá criar e implantar o arquivo proxies.json equivalente na raiz da pasta do projeto local. Para saber mais sobre o suporte à edição do portal, confira Detalhes do suporte a linguagens.

  1. Abra o Portal do Azure e navegue até seu aplicativo de funções.
  2. No painel esquerdo, selecione Proxies e, em seguida, selecione +Adicionar.
  3. Forneça um nome para seu proxy.
  4. Configurar o ponto de extremidade exposto no aplicativo de função especificando o modelo de rota e Métodos HTTP. Esses parâmetros se comportam de acordo com as regras de gatilhos HTTP.
  5. 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ções, ou pode ser qualquer outra API. O valor não precisa ser estático e pode referenciar as configurações do aplicativo e os parâmetros da solicitação original do cliente.
  6. Selecione Criar.

Seu proxy agora existe como um novo ponto de extremidade em seu aplicativo de funções. Do ponto de vista do cliente, isso é o mesmo que um HttpTrigger no Functions. Você pode experimentar o novo proxy copiando a URL do Proxy e testá-la 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 um conjunto de instruções executadas em sequência, na solicitação ou na resposta de uma API. Para obter mais informações sobre as políticas do Gerenciamento de API, confira Políticas do Gerenciamento de API do Azure.

Com os proxies, você pode modificar as solicitações e as respostas por meio do back-end. Essas transformações podem usar variáveis, conforme definido em Usar variáveis.

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, é possível fazer alterações no método HTTP, cabeçalhos e parâmetros de cadeia de consulta. Os valores modificados podem referenciar as configurações do aplicativo e os parâmetros da solicitação original do cliente.

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

Modifique 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 referenciar as configurações do aplicativo, os parâmetros da solicitação original do cliente e os parâmetros da resposta de back-end.

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

Usar variáveis

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

Funções de local de referência

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

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

Observação

Se sua função usar os níveis de autorização função, administrador ou sys, você precisará fornecer o código e o clientId, de acordo com a URL da função original. Nesse 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 referenciá-las nos proxies. Isso evita o armazenamento de segredos no código-fonte.

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

Use os parâmetros de solicitação como entradas para a propriedade de URL de back-end ou como parte da modificação de solicitações e respostas. Alguns parâmetros podem ser limitados ao modelo de rota especificado na configuração do proxy base, enquanto outros são obtidos de propriedades da solicitação de entrada.

Parâmetros de modelo de rota

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

Por exemplo, se um proxy tem um modelo de rota como /pets/{petId}, a URL do back-end pode incluir o valor de {petId}, como em https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Se o modelo de rota termina em um caractere 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 por meio 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 consulta que pode ser lido por meio 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 de back-end de referência

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 motivo HTTP retornada na resposta de back-end.
  • {backend.response.headers.<HeaderName>}: um cabeçalho que pode ser lido por meio 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 referenciar as configurações do aplicativo definidas para o aplicativo de funções envolvendo o nome da configuração entre sinais de percentual (%).

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.

Dica

Usar configurações do aplicativo para hosts de back-end quando você tem várias implantações ou ambientes de teste. Dessa forma, você pode garantir que está sempre se comunicando com o back-end correto para aquele ambiente.

Solucionar problemas de Proxies

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

Você pode depurar um proxy do lado do cliente adicionando um cabeçalho Proxy-Trace-Enabled 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, você pode não desejar permitir que qualquer pessoa chame o seu serviço para gerar um rastreamento. Essas pessoas não poderão acessar o conteúdo de rastreamento sem suas credenciais de logon, mas gerar o rastreamento consome recursos e expõe seu uso dos Proxies de Função.

Desabilite totalmente os rastreamentos adicionando "debug":false a qualquer proxy específico em 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 esse arquivo manualmente e implantá-lo como parte do seu aplicativo ao usar qualquer um dos métodos de implantação que ofereça suporte a funções.

Dica

Se você não configurou um dos métodos de implantação, também poderá trabalhar com o arquivo proxies.json no portal. Vá até o aplicativo de funções e selecione Recursos da plataforma e,depois, selecione Editor do Serviço de Aplicativo. Isso permitirá que você veja toda a estrutura de arquivo do aplicativo de funções e faça alterações.

Proxies.json é definido por um objeto de proxies, composto de proxies nomeados e suas definições. Opcionalmente, você pode referenciar um esquema JSON para o preenchimento do código, caso seu editor dê suporte a isso. Um arquivo de exemplo pode parecer com o seguinte:

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

  • matchCondition: obrigatório - um objeto que define as solicitações que disparam a execução desse proxy. Ele contém duas propriedades compartilhadas com Gatilhos HTTP:
    • métodos: uma matriz dos métodos HTTP aos quais o proxy responde. Se isso não for especificado, o proxy responderá a todos os métodos HTTP na rota.
    • route: obrigatório - define o modelo da rota, controlando para 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 ao qual a solicitação deve ser transmitida por proxy. Esse valor pode referenciar as configurações do aplicativo e os parâmetros da solicitação original do cliente. Se esta propriedade não for incluída, o Azure Functions responderá com um HTTP 200 OK.
  • requestOverrides: um objeto que define as transformações para a solicitação de back-end. Confira Definir um objeto requestOverrides.
  • requestOverrides: um objeto que define as transformações para a resposta do cliente. Confira Definir um objeto responseOverrides.

Observação

A propriedade de rota dos proxies de funções do Azure não honra a propriedade routePrefix da configuração de host do Aplicativo de funções. Se você quiser incluir um prefixo, como /api, ele deve ser incluído na propriedade de rota.

Desabilitar proxies individuais

Você pode desabilitar proxies individuais adicionando "disabled": true ao proxy no arquivo proxies.json. Isso fará com que as solicitações atendam a matchCondition para retornar 404.

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

Configurações do aplicativo

O comportamento do proxy pode ser controlado por várias configurações de aplicativo. Todas elas são descritas na referência de Configurações do aplicativo de funções

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

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

Caractere Caractere de escape 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 à solicitação quando o recurso de back-end é chamado. O objeto é definido pelas seguintes propriedades:

  • backend.request.method: O método HTTP que é 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 ao 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 ao 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 referenciar as configurações do aplicativo e os parâmetros da solicitação original do cliente.

Uma configuração de exemplo pode ser parecida com a seguinte:

{
    "$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 à resposta passada novamente ao 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 motivo do HTTP a ser retornada ao cliente.
  • response.body: a representação de cadeia de caracteres do corpo a ser retornada 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 referenciar as configurações do aplicativo, os parâmetros da solicitação original do cliente e os parâmetros da resposta de back-end.

Uma configuração de exemplo pode ser parecida com a seguinte:

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

Observação

Neste exemplo, o corpo da resposta é definido diretamente e, portanto, nenhuma propriedade backendUri é necessária. O exemplo mostra como você pode usar os Proxies do Azure Functions para simular APIs.