Uso del emulador Azurite para el desarrollo local de Azure Storage

El emulador de código abierto Azurite proporciona un entorno local gratuito para probar sus aplicaciones de Azure Blob, Queue Storage y Table Storage. Cuando esté satisfecho con el funcionamiento de la aplicación a nivel local, puede empezar a usarla en una cuenta de almacenamiento de Azure Storage en la nube. El emulador proporciona compatibilidad multiplataforma en Windows, Linux y MacOS.

Azurite reemplaza al Emulador de Azure Storage y continúa actualizándose para admitir las versiones más recientes de las API de Azure Storage.

En este vídeo se muestra cómo instalar y ejecutar el emulador de Azurite.

Los pasos del vídeo también se describen en las secciones siguientes. Seleccione cualquiera de estas pestañas.

Instalación de Azurite

npm install -g azurite

docker pull mcr.microsoft.com/azure-storage/azurite

git clone https://github.com/Azure/Azurite.git

npm install
npm run build
npm install -g

Ejecución de Azurite

azurite --silent --location c:\azurite --debug c:\azurite\debug.log

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 \
    mcr.microsoft.com/azure-storage/azurite

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 \
    -v c:/azurite:/data mcr.microsoft.com/azure-storage/azurite

docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite \
    azurite-blob --blobHost 0.0.0.0 --blobPort 10000

azurite --silent --location c:\azurite --debug c:\azurite\debug.log

Opciones de línea de comandos

En esta sección se detallan los modificadores de línea de comandos disponibles al iniciar Azurite.

Ayuda

Opcional: obtenga ayuda de la línea de comandos mediante el modificador -h o --help.

azurite -h
azurite --help

Host de escucha

azurite --blobHost 127.0.0.1

azurite --blobHost 0.0.0.0

azurite --queueHost 127.0.0.1

azurite --queueHost 0.0.0.0

azurite --tableHost 127.0.0.1

azurite --tableHost 0.0.0.0

Configuración del puerto de escucha

azurite --blobPort 8888

azurite --blobPort 0

azurite --queuePort 8888

azurite --queuePort 0

azurite --tablePort 11111

azurite --tablePort 0

Ruta de acceso del área de trabajo

Opcional: Azurite almacena los datos en el disco local durante la ejecución. Use el modificador -l o --location para especificar una ruta de acceso como ubicación del área de trabajo. De forma predeterminada, se usa el directorio de trabajo del proceso actual. Tenga en cuenta la "l" minúscula.

azurite -l c:\azurite
azurite --location c:\azurite

Registro de acceso

Opcional: de forma predeterminada, el registro de acceso se muestra en la ventana de la consola. Deshabilite la visualización del registro de acceso con el modificador -s o --silent.

azurite -s
azurite --silent

Registro de depuración

Opcional: el registro de depuración incluye información detallada sobre cada solicitud y seguimiento de la pila de excepciones. Habilite el registro de depuración proporcionando una ruta de acceso local válida de archivo al modificador -d o --debug.

azurite -d path/debug.log
azurite --debug path/debug.log

Modo flexible

Opcional: de forma predeterminada, Azurite aplica el modo strict para bloquear parámetros y encabezados de solicitud no compatibles. Deshabilite el modo strict mediante el modificador -L o --loose. Tenga en cuenta la "L"' mayúscula.

azurite -L
azurite --loose

Versión

Opcional: muestra el número de versión de Azurite instalado mediante el modificador -v o --version.

azurite -v
azurite --version

Configuración de certificados (HTTPS)

Opcional: de forma predeterminada, Azurite usa el protocolo HTTP. Puede habilitar el modo HTTPS; para ello, proporcione una ruta de acceso a un correo con privacidad mejorada (.pem) o el archivo de certificado de Personal Information Exchange (.pfx) al modificador --cert. Se requiere HTTPS para conectarse a Azurite mediante autenticación de OAuth.

Cuando se proporciona --cert para un archivo PEM, debe proporcionar un modificador de --key correspondiente.

azurite --cert path/server.pem --key path/key.pem

Cuando se proporciona --cert para un archivo PFX, debe proporcionar un modificador de --pwd correspondiente.

azurite --cert path/server.pfx --pwd pfxpassword

Configuración de HTTPS

Para obtener información detallada sobre la generación de archivos PEM y PFX, consulte la configuración de HTTPS.

Configuración de OAuth

Opcional: habilite la autenticación de OAuth para Azurite mediante el modificador --oauth.

azurite --oauth basic --cert path/server.pem --key path/key.pem

Azurite admite la autenticación básica mediante la especificación del parámetro basic en el modificador --oauth. Azurite realiza la autenticación básica, como la validación del token de portador entrante, la comprobación del emisor, la audiencia y la expiración. Asimismo, Azurite no comprueba la firma o los permisos del token. Para obtener más información sobre la autorización, consulte Autorización para herramientas y SDK.

Omisión de la comprobación de la versión de la API

Opcional: al inicio, Azurite comprueba que la versión de la API solicitada sea válida. El siguiente comando omite la comprobación de la versión de la API:

azurite --skipApiVersionCheck

Deshabilitación de la URL de estilo de producción

Opcional. Cuando se usa el nombre de dominio completo en lugar de la dirección IP en el host URI de solicitud, Azurite analiza de forma predeterminada el nombre de la cuenta de almacenamiento del host URI de solicitud. Puede forzar el análisis del nombre de la cuenta de almacenamiento desde la ruta de acceso del URI de solicitud mediante --disableProductStyleUrl:

azurite --disableProductStyleUrl

Persistencia en memoria

Opcional. De manera predeterminada, los metadatos de blobs y colas se conservan en el disco y el contenido se conserva en los archivos de extensión. Table Storage conserva todos los datos en el disco. Puede deshabilitar la conservación de los datos en el disco y almacenar solo los datos en memoria. En el escenario de persistencia en memoria, si se finaliza el proceso de Azurite, se pierden todos los datos. El comportamiento de persistencia predeterminado se puede invalidar mediante la opción siguiente:

azurite --inMemoryPersistence

Esta configuración se rechaza cuando la implementación de metadatos basados en SQL está habilitada (a través de AZURITE_DB) o cuando se especifica la opción --location.

Límite de memoria de extensión

Opcional. De forma predeterminada, el almacén de extensiones en memoria (para el contenido de blobs y colas) está limitado al 50 % de la memoria total en el equipo host. El total se evalúa mediante os.totalmem(). Este límite se puede invalidar mediante la siguiente opción:

azurite --extentMemoryLimit <megabytes>

No hay ninguna restricción sobre el valor especificado para esta opción, pero podría usarse memoria virtual si el límite excede la cantidad de memoria física disponible proporcionada por el sistema operativo. Un límite alto podría provocar errores de memoria insuficiente o un rendimiento reducido. Esta opción se rechaza cuando --inMemoryPersistence no se especifica.

Para más información, consulte Uso del almacenamiento en memoria.

Conexión a Azurite con SDK y herramientas

Puede conectarse a Azurite desde los SDK de Azure Storage o herramientas como el Explorador de Azure Storage. Se requiere autenticación y Azurite admite la autorización con OAuth, clave compartida y firmas de acceso compartido (SAS). Azurite también admite el acceso anónimo a contenedores públicos.

Para obtener más información sobre el uso de Azurite con los SDK de Azure, consulte SDK de Azure.

Cuenta de almacenamiento y clave conocidas

Azurite acepta la misma cuenta y clave conocidas que usa el emulador de Azure Storage heredado.

• Nombre de cuenta: devstoreaccount1
• Clave de cuenta: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

Cuentas y claves de almacenamiento personalizadas

Azurite admite las claves y los nombres de cuentas de almacenamiento personalizados estableciendo la variable de entorno AZURITE_ACCOUNTS en el siguiente formato: account1:key1[:key2];account2:key1[:key2];....

Por ejemplo, use una cuenta de almacenamiento personalizada que tenga una clave:

set AZURITE_ACCOUNTS="account1:key1"

export AZURITE_ACCOUNTS="account1:key1"

O bien, use varias cuentas de almacenamiento con dos claves cada una:

set AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"

export AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"

Azurite actualiza las claves y los nombres de cuentas personalizados de la variable de entorno cada minuto de forma predeterminada. Con esta característica, puede girar de forma dinámica la clave de cuenta, o bien agregar nuevas cuentas de almacenamiento sin reiniciar Azurite.

Las claves de cuenta deben ser una cadena codificada en base64.

Cadenas de conexión

La manera más fácil de conectarse a Azurite desde su aplicación consiste en configurar, dentro del archivo de configuración de la aplicación, una cadena de conexión que haga referencia al acceso directo UseDevelopmentStorage=true. Este es un ejemplo de una cadena de conexión un archivo app.config:

<appSettings>
  <add key="StorageConnectionString" value="UseDevelopmentStorage=true" />
</appSettings>

Cadenas de conexión de HTTP

Puede pasar las siguientes cadenas de conexión a los SDK de Azure o a herramientas como la CLI de Azure 2.0 o el Explorador de Storage.

La cadena de conexión completa es:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;TableEndpoint=http://127.0.0.1:10002/devstoreaccount1;

Para conectarse a un servicio específico, puede usar las siguientes cadenas de conexión:

Cadenas de conexión de HTTP

La cadena de conexión completa de HTTPS es:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;

Para conectarse a un servicio específico, puede usar las siguientes cadenas de conexión:

Si usó dotnet dev-certs para generar el certificado autofirmado, utilice la siguiente cadena de conexión.

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://localhost:10000/devstoreaccount1;QueueEndpoint=https://localhost:10001/devstoreaccount1;TableEndpoint=https://localhost:10002/devstoreaccount1;

Actualice la cadena de conexión al usar claves y cuentas de almacenamiento personalizadas.

Para obtener más información sobre las cadenas de conexión, consulte Configuración de las cadenas de conexión de Azure Storage.

SDK de Azure

Para conectarse a Azurite con los SDK de Azure, siga estos pasos:

• Habilite la autenticación de OAuth para Azurite mediante el modificador --oauth. Para más información, consulte Configuración de OAuth.
• Habilite HTTPS mediante un certificado autofirmado a través de las opciones de --cert y --key/--pwd. Para más información sobre la generación de certificados, consulte Configuración de certificados (HTTPS) y Configuración de HTTPS.

Una vez implementados los certificados, inicie Azurite con las siguientes opciones de línea de comandos:

azurite --oauth basic --cert cert-name.pem --key cert-name-key.pem

Reemplace cert-name.pem y certname-key.pem por los nombres de los archivos de clave y certificado. Si usa un certificado PFX, use la opción --pwd en lugar de la opción --key.

// With container URL and DefaultAzureCredential
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new BlobContainerClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;", "container-name"
  );

// With account name and key
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

// With queue URL and DefaultAzureCredential
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new QueueClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;", "queue-name"
  );

// With account name and key
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

// With table URL and DefaultAzureCredential
var client = new Client(
    new Uri("https://127.0.0.1:10002/devstoreaccount1/table-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new TableClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;", "table-name"
  );

// With account name and key
var client = new TableClient(
    new Uri("https://127.0.0.1:10002/devstoreaccount1/table-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Explorador de Microsoft Azure Storage

Puede usar el Explorador de Storage para ver los datos almacenados en Azurite.

Conexión a Azurite mediante HTTP

En el Explorador de Storage, conéctese a Azurite siguiendo estos pasos:

1. Seleccione el icono para administrar cuentas.
2. Haga clic en la opción para agregar una cuenta.
3. Seleccione la opción Asociar a un emulador local.
4. Seleccione Siguiente.
5. Edite el campo del nombre para mostrar con un nombre de su elección.
6. Seleccione Siguiente de nuevo.
7. Seleccione Conectar.

Conexión a Azurite mediante HTTPS

De forma predeterminada, el Explorador de Storage no abre un punto de conexión HTTPS que use un certificado autofirmado. Si está ejecutando Azurite con HTTPS, es probable que ya use un certificado autofirmado. En el Explorador de Storage, importe los certificados SSL a través del cuadro de diálogo Editar ->Certificados SSL ->Importar certificados.

Importación del certificado en el Explorador de Storage

1. Busque el certificado en el equipo local.
2. En el Explorador de Storage, vaya a Editar ->Certificados SSL ->Importar certificados e importe el certificado.

Si no importa un certificado, se produce un error:

unable to verify the first certificate o self signed certificate in chain

Inclusión de Azurite a través de la cadena de conexión HTTPS

Siga estos pasos para agregar Azurite HTTPS al Explorador de Storage:

1. Seleccione Alternar explorador.
2. Seleccione Local y conectado.
3. Haga clic con el botón derecho en las cuentas de almacenamiento y seleccione la opción para conectarse a Azure Storage.
4. Seleccione Usar una cadena de conexión.
5. Seleccione Next (Siguiente).
6. En el campo del nombre para mostrar, especifique un valor.
7. Escriba la cadena de conexión HTTPS de la sección anterior de este documento
8. Seleccione Siguiente.
9. Seleccione Conectar.

Estructura del área de trabajo

Los siguientes archivos y carpetas se pueden crear en la ubicación del área de trabajo al inicializar Azurite.

• __blobstorage__ - Directorio que contiene datos binarios persistentes de Blob service de Azurite
• __queuestorage__ - Directorio que contiene datos binarios persistentes de Queue service de Azurite
• __tablestorage__ - Directorio que contiene datos binarios persistentes de Table service de Azurite
• __azurite_db_blob__.json - Archivo de metadatos de Blob service de Azurite
• __azurite_db_blob_extent__.json - Archivo de metadatos de la extensión de Blob service de Azurite
• __azurite_db_queue__.json - Archivo de metadatos de Queue service de Azurite
• __azurite_db_queue_extent__.json - Archivo de metadatos de la extensión de Queue service de Azurite
• __azurite_db_table__.json - Archivo de metadatos de Table service de Azurite
• __azurite_db_table_extent__.json - Archivo de metadatos de la extensión de Table service de Azurite

Para limpiar Azurite, elimine los archivos y las carpetas anteriores y reinicie el emulador.

Diferencias entre Azurite y Azure Storage

Existen diferencias funcionales entre una instancia local de Azurite y una cuenta de Azure Storage en la nube.

Punto de conexión y URL de conexión

Los puntos de conexión de servicio para Azurite son diferentes de los de una cuenta de Azure Storage. El equipo local no realiza la resolución del nombre de dominio, lo que requiere que los puntos de conexión de Azurite sean direcciones locales.

Al direccionar un recurso en una cuenta de Azure Storage, el nombre de la cuenta forma parte del nombre de host del URI. El recurso que se va a direccionar es parte de la ruta de acceso del URI:

<http|https>://<account-name>.<service-name>.core.windows.net/<resource-path>

El siguiente URI es una dirección válida para un blob en una cuenta de Azure Storage:

https://myaccount.blob.core.windows.net/mycontainer/myblob.txt

URL de estilo IP

Dado que el equipo local no realiza la resolución de nombres de dominio, el nombre de la cuenta forma parte de la ruta de acceso del URI en lugar del nombre de host. Use el siguiente formato de URI para un recurso en Azurite:

http://<local-machine-address>:<port>/<account-name>/<resource-path>

La siguiente dirección se puede usar para obtener acceso a un blob en Azurite:

http://127.0.0.1:10000/myaccount/mycontainer/myblob.txt

URL de estilo de producción

Opcionalmente, puede modificar el archivo de hosts para acceder a una cuenta con la URL de estilo de producción.

En primer lugar, agregue una o varias líneas al archivo de hosts. Por ejemplo:

127.0.0.1 account1.blob.localhost
127.0.0.1 account1.queue.localhost
127.0.0.1 account1.table.localhost

A continuación, establezca variables de entorno para habilitar las claves y las cuentas de almacenamiento personalizadas:

set AZURITE_ACCOUNTS="account1:key1:key2"

Puede agregar más cuentas. Consulte la sección Cuentas de almacenamiento y claves personalizadas de este artículo.

Inicie Azurite y use una cadena de conexión personalizada para acceder a su cuenta. En el siguiente ejemplo, la cadena de conexión asume que se usan los puertos predeterminados.

DefaultEndpointsProtocol=http;AccountName=account1;AccountKey=key1;BlobEndpoint=http://account1.blob.localhost:10000;QueueEndpoint=http://account1.queue.localhost:10001;TableEndpoint=http://account1.table.localhost:10002;

No acceda a la cuenta predeterminada de esta manera con Azure Storage Explorer. Hay un error por el cual el Explorador de Storage siempre agrega el nombre de cuenta en la ruta de URL, lo que provoca errores.

De forma predeterminada, cuando se usa Azurite con una URL de estilo de producción, el nombre de cuenta debe ser el nombre de host en el nombre de dominio completo, como http://devstoreaccount1.blob.localhost:10000/container. Para usar la URL de estilo de producción con el nombre de cuenta en la ruta de acceso de la dirección URL como http://foo.bar.com:10000/devstoreaccount1/container, asegúrese de usar el parámetro --disableProductStyleUrl al iniciar Azurite.

Si usa host.docker.internal como host de URI de solicitud (por ejemplo: http://host.docker.internal:10000/devstoreaccount1/container), Azurite obtiene el nombre de la cuenta de la ruta de acceso del URI de solicitud. Este comportamiento es cierto independientemente de si usa el parámetro --disableProductStyleUrl al iniciar Azurite.

Escalado y rendimiento

Azurite no admite un gran número de clientes conectados. No hay garantía de rendimiento. Azurite se ha pensado para su uso con fines de desarrollo y pruebas.

Control de errores

Azurite se alinea con la lógica de control de errores de Azure Storage, pero existen diferencias. Por ejemplo, los mensajes de error pueden ser diferentes, mientras que los códigos de estado de error están alineados.

RA-GRS

Azurite admite la replicación con redundancia geográfica con acceso de lectura (RA-GRS). Si quiere ver los recursos de almacenamiento, puede obtener acceso a la ubicación secundaria si anexa -secondary al nombre de la cuenta. Por ejemplo, la siguiente dirección se puede usar para obtener acceso a un blob usando la cuenta secundaria de solo lectura en Azurite:

http://127.0.0.1:10000/devstoreaccount1-secondary/mycontainer/myblob.txt

Compatibilidad con tablas

La compatibilidad con tablas en Azurite se encuentra actualmente en versión preliminar. Para más información, consulte el proyecto Tabla de Azurite V3.

La compatibilidad con Durable Functions requiere tablas.

Azurite es de código abierto

Las contribuciones y las sugerencias para Azurite son bienvenidas. Vaya a la página del proyecto GitHub o de incidencias de Github para ver los hitos y los elementos de trabajo de los que estamos haciendo un seguimiento para futuras características y correcciones de errores. También se realiza un seguimiento de los elementos de trabajo detallados en GitHub.

Pasos siguientes

• Uso del Emulador de Azure Storage para desarrollo y pruebas documenta el antiguo emulador de Azure Storage que Azurite sustituye.
• En Configuración de las cadenas de conexión de Azure Storage se explica cómo ensamblar una cadena de conexión de Azure Storage válida.