Trabajar con la proxies heredados

  • Artículo

Importante

Azure Functions Proxies es una característica heredada en las versiones 1.x a 3.x del entorno de ejecución de Azure Functions. La compatibilidad con los proxy se puede volver a habilitar en la versión 4.x para que pueda actualizar correctamente las aplicaciones de funciones a la versión más reciente del entorno de ejecución. Debe cambiar a la integración de las aplicaciones de funciones con Azure API Management tan pronto como sea posible. API Management le permite aprovechar un conjunto más completo de características para definir, proteger, administrar y monetizar las API basadas en Functions. Para más información, consulte Integración de API Management.

Para obtener información sobre cómo volver a habilitar la compatibilidad con servidores proxy en la versión 4.x de Functions, consulte Volver a habilitar servidores proxy en Functions v4.x.

Para facilitar la migración desde las implemetaciones de proxy existentes, en este artículo se vincula a contenido de API Management equivalente, cuando esté disponible.

En este artículo se explica cómo configurar y usar Azure Functions Proxies. Con esta característica, puede especificar puntos de conexión en su aplicación de función que se implementan con otro recurso. Puede utilizar a estos servidores proxy para dividir una API grande en varias Function App (como en una arquitectura de microservicio), mientras que presenta una superficie de API única para los clientes.

Se aplica la facturación estándar de Functions a las ejecuciones de proxy. Para más información, consulte los precios de Azure Functions.

Volver a habilitar servidores proxy en Functions v4.x

Después de migrar la aplicación de funciones a la versión 4.x del entorno de ejecución de Functions, deberá volver a habilitar específicamente los servidores proxy. Todavía debe cambiar a la integración de las aplicaciones de funciones con Azure API Management lo antes posible y no solo depender de servidores proxy.

Para volver a habilitar servidores proxy, es necesario establecer una marca en la configuración de la aplicación AzureWebJobsFeatureFlags de una de las siguientes maneras:

  • Si la configuración AzureWebJobsFeatureFlags aún no existe, agregue esta configuración a la aplicación de funciones con un valor de EnableProxies.

  • Si esta configuración ya existe, agregue ,EnableProxies al final del valor existente.

AzureWebJobsFeatureFlags es una matriz delimitada por comas de marcas que se usa para habilitar la vista previa y otras características temporales. Para más información sobre cómo crear y modificar la configuración de la aplicación, consulte Trabajar con la configuración de la aplicación.

Nota

Incluso cuando se vuelve a habilitar utilizando la marca EnableProxies, no se puede trabajar con proxies en Azure Portal. En su lugar, debe trabajar directamente con el archivo proxies.json para la aplicación de funciones. Para más información, consulte Configuración avanzada.

Creación de un proxy

Importante

Para obtener contenido equivalente mediante API Management, consulte Exposición de API sin servidor desde puntos de conexión HTTP mediante Azure API Management.

Los proxies se definen en el archivo proxies.json en la raíz de la aplicación de funciones. Los pasos de esta sección muestran cómo usar el Azure Portal para crear este archivo en la aplicación de funciones. No todos los idiomas y combinaciones de sistema operativo admiten la edición en el portal. Si no puede modificar los archivos de la aplicación de funciones en el portal, puede crear e implementar el archivo equivalente proxies.json desde la raíz de la carpeta del proyecto local. Para más información sobre la compatibilidad con la edición del portal, consulte Detalles de compatibilidad con el lenguaje.

  1. Abra Azure Portal y vaya a la aplicación de función.
  2. En el panel izquierdo, seleccione Proxies y, luego, +Agregar.
  3. Proporcione un nombre para el proxy.
  4. Configure el punto de conexión expuesto en esta aplicación de función; para ello, especifique la plantilla de ruta y los métodos HTTP. Estos parámetros se comportan según las reglas de los desencadenadores HTTP.
  5. Establezca la dirección URL de back-end en otro punto de conexión. El punto de conexión podría tratarse de una función en otra aplicación de función o podría ser cualquier otra API. El valor no necesita ser estático y puede hacer referencia a la configuración de la aplicación y a parámetros de la solicitud de cliente original.
  6. Seleccione Crear.

El proxy ahora existe como un nuevo punto de conexión en la Function App. Desde la perspectiva del cliente, es lo mismo que httpTrigger en Functions. Puede probar el nuevo proxy; para ello, copie la dirección URL del proxy y pruébela con el cliente HTTP favorito.

Modificación de solicitudes y respuestas

Importante

API Management le permite poder cambiar el comportamiento de la API a través de la configuración mediante directivas. Las directivas son una colección de declaraciones que se ejecutan secuencialmente en la solicitud o respuesta de una API. Para obtener más información sobre directivas API Management, consulte Directivas de Azure API Management.

Con proxies puede modificar solicitudes y respuestas del back-end. Estas transformaciones pueden usar variables, como se define en Uso de variables.

Modificación de la solicitud de back-end

De forma predeterminada, la solicitud de back-end se inicializa como copia de la solicitud original. Además de establecer la dirección URL de back-end, se pueden realizar cambios en el método HTTP, los encabezados y los parámetros de cadena de consulta. Los valores modificados pueden hacer referencia a la configuración de la aplicación y a los parámetros de la solicitud de cliente original.

Las solicitudes de back-end pueden modificarse en el portal expandiendo la sección Invalidación de solicitud de la página de detalles del proxy.

Modificar la respuesta

De forma predeterminada, la respuesta del cliente se inicializa como copia de la respuesta de back-end. Puede realizar cambios en el código de estado, la expresión del motivo, los encabezados y el cuerpo de la respuesta. Los valores modificados pueden hacer referencia a la configuración de la aplicación, a parámetros de la solicitud de cliente original y a parámetros de la respuesta de back-end.

Las respuestas de back-end pueden modificarse en Azure Portal si se expande la sección Invalidación de respuesta de la página de detalles del proxy.

Uso de variables

La configuración de un proxy no necesita ser estática. Puede condicionarlo para que use variables de la solicitud de cliente original, la respuesta de back-end o la configuración de la aplicación.

Funciones locales de referencia

Puede utilizar localhost para hacer referencia a una función dentro de la misma aplicación de función directamente, sin una solicitud de proxy de ida y vuelta.

"backendUri": "https://localhost/api/httptriggerC#1" hará referencia a una función desencadenada mediante HTTP local en la ruta /api/httptriggerC#1

Nota

Si la función usa los niveles de autorización de función, administrador o sistema, deberá proporcionar el código y el valor de clientId, según la URL de la función original. En este caso, la referencia tendría el siguiente aspecto: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" Se recomienda almacenar estas claves en la configuración de la aplicación y hacer referencia a ellas en los servidores proxy. De esta forma, se evita tener que almacenar los secretos en el código fuente.

Referencia a los parámetros de solicitud

Puede usar parámetros de solicitud como entradas para la propiedad de dirección URL de back-end o como parte de la modificación de solicitudes y respuestas. Algunos parámetros pueden enlazarse desde la plantilla de ruta especificada en la configuración de proxy base, y otros pueden proceder de propiedades de la solicitud entrante.

Parámetros de plantilla de ruta

Los parámetros que se usan en la plantilla de ruta están disponibles para hacer referencia a ellos por su nombre. Los nombres de parámetro se incluyen entre llaves ({}).

Por ejemplo, si un proxy tiene una plantilla de ruta, como /pets/{petId}, la dirección URL de back-end puede incluir el valor de {petId}, como en https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Si la plantilla de ruta finaliza en un carácter comodín, como /api/{*restOfPath}, el valor {restOfPath} es una representación de cadena de los segmentos de ruta de acceso restantes procedentes de la solicitud entrante.

Parámetros de solicitud adicionales

Además de los parámetros de la plantilla de ruta, pueden usarse los siguientes valores en la configuración:

  • {request.method} : método HTTP que se usa en la solicitud original.
  • {request.headers.<nombreDeEncabezado>}: encabezado que puede leerse desde la solicitud original. Reemplace <nombreDeEncabezado> por el nombre del encabezado que desea leer. Si el encabezado no se incluye en la solicitud, el valor será una cadena vacía.
  • {request.querystring.<nombreDeParámetro>}: parámetro de cadena de consulta que se puede leer desde la solicitud original. Reemplace <nombreDeParámetro> por el nombre del parámetro que desea leer. Si el parámetro no se incluye en la solicitud, el valor será una cadena vacía.

Referencia a parámetros de respuesta de back-end

Los parámetros de respuesta pueden utilizarse como parte de la modificación de la respuesta al cliente. Se pueden usar los siguientes valores en la configuración:

  • {backend.response.statusCode} : código de estado HTTP que se devuelve en la respuesta de back-end.
  • {backend.response.statusReason} : frase de motivo HTTP que se devuelve en la respuesta de back-end.
  • {backend.response.headers.<nombreDeEncabezado>}: encabezado que puede leerse desde la respuesta de back-end. Reemplace <nombreDeEncabezado> por el nombre del encabezado que desea leer. Si el encabezado no se incluye en la respuesta, el valor será una cadena vacía.

Referencia a la configuración de la aplicación

También puede hacer referencia a la configuración de la aplicación definida para la aplicación de función rodeando el nombre de la configuración con signos de porcentaje (%).

Por ejemplo, en la dirección URL de back-end https://%ORDER_PROCESSING_HOST%/api/orders , "%ORDER_PROCESSING_HOST%" se sustituiría por el valor de la opción ORDER_PROCESSING_HOST.

Sugerencia

Use la configuración de la aplicación para hosts back-end si tiene varias implementaciones o entornos de prueba. De este modo, puede asegurarse de que siempre se comunica con el back-end correcto para ese entorno.

Solución de problemas con Proxies

Si añade la marca "debug":true a cualquier proxy de su proxies.json, se habilitará el registro de depuración. Los registros se almacenan en D:\home\LogFiles\Application\Proxies\DetailedTrace y son accesibles mediante herramientas avanzadas (kudu). Las respuestas HTTP también contendrán un encabezado Proxy-Trace-Location con una dirección URL para acceder al archivo de registro.

Puede depurar un proxy del cliente mediante la adición de un encabezado Proxy-Trace-Enabled establecido en true. De este modo, también se registrará un seguimiento en el sistema de archivos y se devolverá la dirección URL de seguimiento como un encabezado en la respuesta.

Bloqueo de seguimiento de proxy

Por motivos de seguridad, es posible que no desee que nadie llame a su servicio para generar un seguimiento. Nadie podrá acceder al contenido de seguimiento sin sus credenciales de inicio de sesión, pero la generación del seguimiento consume recursos y revela que está utilizando Function Proxies.

Deshabilite por completo los seguimientos añadiendo "debug":false a cualquier proxy determinado en su proxies.json.

Configuración avanzada

Los servidores proxy que configura se almacenan en un archivo proxies.json, ubicado en la raíz de un directorio de la aplicación de función. Puede editar este archivo manualmente e implementarlo como parte de la aplicación cuando se utiliza cualquiera de los métodos de implementación compatibles con Functions.

Sugerencia

Si no ha configurado alguno de los métodos de implementación, también puede trabajar con el archivo proxies.json en el portal. Vaya a la aplicación de función y seleccione Características de la plataforma y Editor de App Service. Al hacerlo, puede ver toda la estructura de archivos de la aplicación de función y realizar cambios.

El archivo proxies.json lo define un objeto de servidores proxy, compuesto de servidores proxy con nombre y de sus definiciones. De forma opcional, si el editor lo admite, puede hacer referencia a un esquema JSON para completar el código. Un archivo de ejemplo puede tener el siguiente aspecto:

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

Cada proxy tiene un nombre descriptivo, como proxy1 en el ejemplo anterior. El objeto de definición de proxy correspondiente se define mediante las siguientes propiedades:

  • matchCondition: (requerida) objeto que define las solicitudes que desencadenan la ejecución de este proxy. Contiene dos propiedades compartidas con los desencadenadores HTTP:
    • methods: matriz de los métodos HTTP a los que responde el servidor proxy. Si no se especifica, el proxy responde a todos los métodos HTTP de la ruta.
    • route: (requerida) define la plantilla de ruta y controla a qué direcciones URL de solicitud responde el proxy. A diferencia de los desencadenadores HTTP, no hay ningún valor predeterminado.
  • backendUri: dirección URL del recurso de back-end a la que se redirigirá la solicitud mediante proxy. Este valor puede hacer referencia a la configuración de la aplicación y a parámetros de la solicitud de cliente original. Si no se incluye esta propiedad, Azure Functions responde con el mensaje HTTP 200 - Correcto.
  • requestOverrides: objeto que define transformaciones a la solicitud de back-end. Consulte Definición de un objeto requestOverrides.
  • responseOverrides: objeto que define transformaciones a la respuesta del cliente. Consulte Definición de un objeto responseOverrides.

Nota

La propiedad route de Azure Functions Proxies no respeta la propiedad routePrefix de la configuración del host de Function App. Si quiere incluir un prefijo como /api, se debe incluir en la propiedad route.

Deshabilitación de servidores proxy individuales

Puede deshabilitar servidores proxy individuales añadiendo "disabled": true al proxy en el archivo proxies.json. Esto hará que las solicitudes que cumplan matchCondition devuelvan un error 404.

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

Configuración de la aplicación

El comportamiento del proxy puede controlarse mediante varias opciones de configuración de la aplicación. Están todas descritas en Referencia de configuración de aplicación para Azure Functions

Caracteres reservados (formato de cadena)

Los proxies leen todas las cadenas de un archivo JSON usando \ como un símbolo de escape. Los proxies también interpretan las llaves. Consulte a continuación un conjunto completo de ejemplos.

Carácter Carácter de escape Ejemplo
{ o } {{ o }} {{ example }} -->{ example }
\ \\ example.com\\text.html -->example.com\text.html
" \" \"example\" -->"example"

Definición de un objeto requestOverrides

El objeto requestOverrides define los cambios realizados en la solicitud cuando se llama al recurso de back-end. El objeto se define mediante las siguientes propiedades:

  • backend.request.method: método HTTP que se usa para llamar al back-end.
  • backend.request.querystring.<nombreDeParámetro>: parámetro de cadena de consulta que se puede establecer para llamar al back-end. Reemplace <nombreDeParámetro> por el nombre del parámetro que desea establecer. Si se proporciona una cadena vacía, el parámetro se sigue incluyendo en la solicitud de back-end.
  • backend.request.headers.<nombreDeEncabezado>: encabezado que se puede establecer para llamar al back end. Reemplace <nombreDeEncabezado> por el nombre del encabezado que desea establecer. Si se proporciona una cadena vacía, el parámetro se sigue incluyendo en la solicitud de back-end.

Los valores pueden hacer referencia a la configuración de la aplicación y a los parámetros de la solicitud de cliente original.

Una configuración de ejemplo puede tener el siguiente aspecto:

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

Definición de un objeto responseOverrides

El objeto requestOverrides define los cambios realizados en la respuesta que se pasa de nuevo al cliente. El objeto se define mediante las siguientes propiedades:

  • response.statusCode: código de estado HTTP que se va a devolver al cliente.
  • response.statusReason: frase de motivo HTTP que se va a devolver al cliente.
  • response.body: representación de cadena del cuerpo que se va a devolver al cliente.
  • response.headers.<nombreDeEncabezado>: encabezado que se puede establecer para la respuesta al cliente. Reemplace <nombreDeEncabezado> por el nombre del encabezado que desea establecer. Si se proporciona una cadena vacía, el encabezado no se incluye en la respuesta.

Los valores pueden hacer referencia a la configuración de la aplicación, a parámetros de la solicitud de cliente original y a parámetros de la respuesta de back-end.

Una configuración de ejemplo puede tener el siguiente aspecto:

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

En este ejemplo, el cuerpo de la respuesta se define directamente, por lo que no se necesita ninguna propiedad backendUri. En el ejemplo, se muestra cómo usar Azure Functions Proxies para simular las API.