Implementación de archivos ZIP en Azure Functions

Artículo
11/17/2023

En este artículo se describe la manera de implementar los archivos de proyecto de la aplicación de función en Azure desde un archivo ZIP (comprimido). Aprenda a realizar una implementación de inserción mediante el uso de la CLI de Azure y con las API de REST. Azure Functions Core Tools también usa estas API de implementación al publicar un proyecto local en Azure.

La implementación de archivos ZIP es también una forma fácil de ejecutar las funciones desde un archivo de paquetes en Azure. Es la tecnología de implementación predeterminada en los planes de hospedaje Consumption, Elastic Premiumy Dedicated (App Service). El plan Flex Consumption no admite la implementación de archivos ZIP.

Azure Functions tiene toda una gama de opciones de implementación e integración continuas que se proporcionan con Azure App Service. Para más información, vea Implementación continua para Azure Functions.

Para acelerar el desarrollo, puede que le resulte más fácil implementar los archivos de proyecto de la aplicación de funciones directamente desde un archivo ZIP. La API de implementación de ZIP toma el contenido de un archivo ZIP y lo extrae en la carpeta wwwroot de la aplicación de función. Esta implementación del archivo .zip usa el servicio Kudu que permite realizar implementaciones basadas en integraciones continuas, entre las que se incluye:

La eliminación de archivos que se omitieron en implementaciones anteriores.
La personalización de la implementación, incluyendo la ejecución de scripts de implementación.
Registros de implementación.
Los desencadenadores de la función de sincronización de una aplicación de función en un plan de consumo.

Para más información, vea la referencia sobre implementaciones con archivos ZIP.

Importante

Cuando realice la implementación del archivo ZIP, los archivos de cualquier otra implementación existente que no se encuentren en el archivo ZIP se eliminarán de la aplicación de función.

Requisitos de los .zip de implementación

El archivo ZIP que implemente debe contener todos los archivos necesarios para ejecutar la aplicación de funciones. Puede crear manualmente un archivo ZIP desde el contenido de una carpeta de proyecto de Functions mediante la funcionalidad de compresión de .zip integrada o herramientas de terceros.

El archivo debe incluir el archivo host.json en la raíz de la carpeta extraída. La pila de lenguaje seleccionada para la aplicación de funciones crea requisitos adicionales:

Importante

En el caso de los lenguajes que generan la salida compilada para la implementación, asegúrese de comprimir el contenido de la carpeta de salida que planea publicar y no toda la carpeta del proyecto. Cuando Functions extrae el contenido del archivo ZIP, el archivo host.json debe existir en la raíz del paquete.

Un proceso de implementación zip extrae los archivos y carpetas del archivo ZIP en el directorio wwwroot. Si incluye el directorio primario al crear el archivo, el sistema no encontrará los archivos que espera ver en wwwroot.

Implementación con la CLI de Azure

Puede usar la CLI de Azure para desencadenar una implementación de inserción. Para implementar el archivo .zip en la aplicación de función, use el comando az functionapp deployment source config-zip. Para usar este comando, debe usar la versión 2.0.21 o posterior de la CLI de Azure. Para ver qué versión de CLI de Azure está usando, use el comando az --version.

En el siguiente comando, reemplace el marcador de posición <zip_file_path> por la ruta de acceso a la ubicación del archivo .zip. Asimismo, reemplace <app_name> por el nombre único de su aplicación de funciones y <resource_group> por el nombre del grupo de recursos.

az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src <zip_file_path>

Este comando implementa los archivos de proyecto del archivo .zip descargado en la aplicación de función en Azure. A continuación, se reinicia la aplicación. Para ver la lista de implementaciones de esta aplicación de función, debe usar las API de REST.

Cuando se usa la CLI de Azure en el equipo local, <zip_file_path> es la ruta de acceso al archivo .zip en el equipo. También puede ejecutar la CLI de Azure en Azure Cloud Shell. Cuando use Cloud Shell, recuerde que debe cargar primero el archivo .zip de implementación en la cuenta de Azure Files que esté asociada con Cloud Shell. En ese caso, <zip_file_path> será la ubicación de almacenamiento que utiliza la cuenta de Cloud Shell. Para obtener más información, consulte Persistencia de archivos en Azure Cloud Shell.

Implementación de un archivo ZIP con las API REST

Puede usar el servicio de implementación de las API de REST para implementar el archivo .zip en su aplicación en Azure. Para implementar, envíe un mensaje de solicitud a https://<app_name>.scm.azurewebsites.net/api/zipdeploy. La solicitud POST debe contener el archivo .zip en el cuerpo del mensaje. Las credenciales de implementación de la aplicación se proporcionan en la solicitud mediante la autenticación de HTTP BASIC. Para obtener más información, consulte la referencia de implementación para la inserción del archivo .zip.

Para la autenticación básica HTTP, necesita las credenciales de implementación de App Service. Para ver cómo establecer sus credenciales de implementación, consulte Establecimiento y restablecimiento de credenciales de nivel de usuario.

Con cURL

En el ejemplo siguiente se usa la herramienta cURL para implementar un archivo .zip. Reemplace los marcadores de posición <deployment_user>, <zip_file_path> y <app_name>. Cuando cURL se lo solicite, escriba la contraseña.

curl -X POST -u <deployment_user> --data-binary "@<zip_file_path>" https://<app_name>.scm.azurewebsites.net/api/zipdeploy

Esta solicitud desencadena la implementación de inserción desde el archivo .zip cargado. Puede revisar las implementaciones actuales y pasadas mediante el punto de conexión https://<app_name>.scm.azurewebsites.net/api/deployments, tal como se muestra en el siguiente ejemplo de cURL. Una vez más, reemplace <app_name> por el nombre de la aplicación y <deployment_user> por el nombre de usuario de las credenciales de implementación.

curl -u <deployment_user> https://<app_name>.scm.azurewebsites.net/api/deployments

Implementación asincrónica de archivos ZIP

Al implementar de forma sincrónica, es posible que reciba errores relacionados con los tiempos de espera de la conexión. Agregue ?isAsync=true a la dirección URL para realizar una implementación de forma asincrónica. Recibirá una respuesta en cuanto se cargue el archivo ZIP con un encabezado Location que apunte a la dirección URL de estado de la implementación que hay que sondear. Al sondear la dirección URL proporcionada en el encabezado Location, recibirá una respuesta HTTP 202 (Aceptado) mientras el proceso está en curso y una respuesta HTTP 200 (OK) una vez expandido el archivo y la implementación se haya completado correctamente.

Autenticación de Microsoft Entra

Una alternativa al uso de la autenticación básica HTTP para la implementación de archivos ZIP es usar una identidad de Microsoft Entra. Es posible que se necesite una identidad de Microsoft Entra si la autenticación básica HTTP está deshabilitada para el sitio de SCM.

Será necesario un token de acceso válido de Microsoft Entra para el usuario o la entidad de servicio que realiza la implementación. Se puede recuperar un token de acceso mediante el comando az account get-access-token de la CLI de Azure. El token de acceso se usará en el encabezado de autenticación de la solicitud HTTP POST.

curl -X POST \
    --data-binary "@<zip_file_path>" \
    -H "Authorization: Bearer <access_token>" \
    "https://<app_name>.scm.azurewebsites.net/api/zipdeploy"

Con PowerShell

En el ejemplo siguiente se usa Publish-AzWebapp para cargar el archivo .zip. Reemplace los marcadores de posición <group-name>, <app-name> y <zip-file-path>.

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>

Esta solicitud desencadena la implementación de inserción desde el archivo .zip cargado.

Para revisar las implementaciones actuales y pasadas, ejecute los siguientes comandos. De nuevo, reemplace los marcadores <deployment-user>, <deployment-password> y <app-name>.

$username = "<deployment-user>"
$password = "<deployment-password>"
$apiUrl = "https://<app-name>.scm.azurewebsites.net/api/deployments"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$userAgent = "powershell/1.0"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -UserAgent $userAgent -Method GET

Implementación mediante una plantilla de ARM

Puede usar la extensión de plantilla de ARM ZipDeploy para insertar el archivo .zip en la aplicación de funciones.

Plantilla de ARM de ejemplo ZipDeploy

Esta plantilla incluye un espacio de ensayo y producción y se implementa en una u otra. Normalmente, usaría esta plantilla para realizar la implementación en el espacio de ensayo y, luego, la intercambiaría por el nuevo paquete ZIP que se ejecuta en el espacio de producción.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServiceName": {
      "type": "string"
    },
    "deployToProduction": {
      "type": "bool",
      "defaultValue": false
    },
    "slot": {
      "type": "string",
      "defaultValue": "staging"
    },
    "packageUri": {
      "type": "secureString"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployToProduction')]",
      "type": "Microsoft.Web/sites/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/ZipDeploy', parameters('appServiceName'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    },
    {
      "condition": "[not(parameters('deployToProduction'))]",
      "type": "Microsoft.Web/sites/slots/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/{1}/ZipDeploy', parameters('appServiceName'), parameters('slot'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    }
  ]
}

La implementación inicial la haría directamente en el espacio de producción. Para más información, consulte Implementaciones de ranuras.

Ejecución de funciones desde el paquete de implementación

También puede ejecutar las funciones directamente desde el archivo del paquete de implementación. Este método omite el paso de implementación de la copia de archivos del paquete en el directorio wwwroot de la aplicación de función. En su lugar, Functions Runtime monta el archivo del paquete y el contenido el directorio wwwroot será de solo lectura.

La implementación de ZIP se integra con esta característica, que se puede habilitar al configurar la opción de la aplicación de función WEBSITE_RUN_FROM_PACKAGE en un valor de 1. Para más información, consulte Run your functions from a deployment package file (Ejecución de Azure Functions desde un archivo de paquete de implementación).

Personalización de la implementación

En el proceso de implementación se da por supuesto que el archivo .zip que se inserta contiene una aplicación lista para ejecutarse. No se ejecuta ninguna personalización de forma predeterminada. Para habilitar los mismos procesos de compilación que se obtienen con la integración continua, agregue los siguientes elementos a la configuración de la aplicación:

SCM_DO_BUILD_DURING_DEPLOYMENT=true

Cuando se realiza la implementación de inserción del archivo .zip, el valor que se establece de forma predeterminada es false. El valor predeterminado es true para las implementaciones de integración continua. Cuando el valor se establece en true, la configuración relacionada con la implementación se usa durante la implementación. Puede configurar estas opciones a modo de configuración de la aplicación o en un archivo de configuración de implementación que se encuentra en la raíz del archivo .zip. Para obtener más información, consulte Repository and deployment-related settings (Repositorio y configuración relacionada con la implementación) en la referencia de la implementación.

Descarga de los archivos de aplicación de función

Si creó las funciones mediante el editor de Azure Portal, puede descargar el proyecto de la aplicación de funciones existente como un archivo .zip de una de estas maneras:

Desde Azure Portal
1. Inicie sesión en Azure Portal y vaya a la aplicación de función.
2. En la pestaña Introducción, seleccione Descargar contenido de la aplicación. Seleccione las opciones de descarga y, a continuación, seleccione Descargar.
  
  El archivo .zip descargado tiene el formato correcto para volver a publicarlo en la aplicación de función mediante la implementación de inserción de archivos .zip. La descarga del portal también puede agregar los archivos necesarios para abrir la aplicación de función directamente en Visual Studio.
Uso de las API REST:

Use la siguiente API GET de implementación para descargar los archivos del proyecto <function_app>:
```
https://<function_app>.scm.azurewebsites.net/api/zip/site/wwwroot/
```
Al incluir /site/wwwroot/ se garantiza que el archivo ZIP solo incorpora los archivos de proyecto de la aplicación de función y no el sitio entero. Si aún no ha iniciado sesión en Azure, se le pedirá que lo haga.

Igualmente, también puede descargar un archivo .zip desde un repositorio de GitHub. Al descargar un repositorio de GitHub como un archivo ZIP, GitHub agrega un nivel de carpeta adicional para la rama. Este nivel de carpetas adicional significa que no puede implementar el archivo .zip directamente ya que se descargó desde GitHub. Si usa un repositorio de GitHub para mantener la aplicación de función, debe usar la integración continua para implementar la aplicación.

Pasos siguientes

Ejecución de las funciones desde un archivo de paquete en Azure

Compartir vía