Implementación de archivos ZIP en Azure Functions
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 también es una manera fácil de ejecutar las funciones desde el paquete de implementación. Para más información, consulte Ejecución de las funciones desde un archivo de paquete en Azure.
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.
Requisitos de los .zip de implementación
El archivo ZIP que use para la implementación de inserción debe contener todos los archivos necesarios para ejecutar la función.
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.
El código de todas las funciones de una aplicación de funciones está ubicado en una carpeta de proyecto raíz que contiene un archivo de configuración de host. El archivo host.json contiene configuraciones específicas del entorno de ejecución y está en la carpeta raíz de la aplicación de funciones. Un carpeta bin contiene paquetes y otros archivos de biblioteca que requiere la aplicación de funciones. Las estructuras de carpeta específicas necesarias para la aplicación de funciones dependen del lenguaje:
Todas las funciones de una aplicación de funciones deben compartir la misma pila de lenguaje.
Una aplicación de función incluye todos los archivos y carpetas del directorio wwwroot. Una implementación de archivo .zip incluye el contenido del directorio wwwroot, pero no el propio directorio. Al implementar un proyecto de la biblioteca de clases de C#, debe incluir las dependencias y los archivos de biblioteca compilados en una subcarpeta bin del paquete ZIP.
Al desarrollar contenido en un equipo local, puede crear manualmente un archivo .zip de la carpeta del proyecto de la aplicación de funciones mediante la funcionalidad de compresión .zip integrada o herramientas de terceros.
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
Inicie sesión en Azure Portal y vaya a la aplicación de función.
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.