Utiliser l’émulateur azurite pour le développement de stockage Azure local

L’émulateur open source Azurite fournit un environnement local gratuit qui vous permet de tester les applications du Stockage Blob, du Stockage File d’attente et du Stockage Table. Une fois que vous êtes satisfait de la manière dont votre application fonctionne localement, passez à l’utilisation d’un compte de stockage Azure dans le cloud. L’émulateur offre une prise en charge multiplateforme, qui inclut Windows, Linux et macOS.

Azurite remplace l’émulateur de stockage Azure et continue d’être mis à jour pour prendre en charge les dernières versions des API stockage Azure.

Cette vidéo vous montre comment installer et exécuter l’émulateur Azurite.

Les étapes de la vidéo sont également décrites dans les sections suivantes. Sélectionnez l’un de ces onglets.

Installer 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

Exécuter 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

Options de ligne de commande

Cette section détaille les commutateurs de ligne de commande disponibles quand vous lancez Azurite.

Aide

Facultatif : permet d’obtenir de l’aide sur la ligne de commande en utilisant le commutateur -h ou --help.

azurite -h
azurite --help

Hôte d’écoute

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

Configuration du port d’écoute

azurite --blobPort 8888

azurite --blobPort 0

azurite --queuePort 8888

azurite --queuePort 0

azurite --tablePort 11111

azurite --tablePort 0

Chemin de l’espace de travail

Facultatif Azurite stocke les données sur le disque local durant l’exécution. Utilisez le commutateur -l ou --location pour spécifier un chemin en tant qu’emplacement de l’espace de travail. Par défaut, le répertoire de travail du processus actuel est utilisé. Remarquez le « l » minuscule.

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

Journal d’accès

Facultatif Le journal des accès s’affiche par défaut dans la fenêtre de console. Désactivez l’affichage du journal des accès à l’aide du commutateur -s ou --silent.

azurite -s
azurite --silent

Journal de débogage

Facultatif Le journal de débogage contient des informations détaillées sur chaque arborescence des appels de procédure relative aux requêtes et aux exceptions. Activez le journal de débogage en fournissant un chemin de fichier local valide au commutateur -d ou --debug.

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

Mode relâché

Facultatif Par défaut, Azurite applique le mode strict pour bloquer les en-têtes et les paramètres de requête non pris en charge. Désactivez le mode strict en utilisant le commutateur -L ou --loose. Remarquez le « L » majuscule.

azurite -L
azurite --loose

Version

Facultatif : permet d’afficher le numéro de la version d’Azurite installée en utilisant le commutateur -v ou --version.

azurite -v
azurite --version

Configuration de certificat (HTTPS)

Facultatif : par défaut, Azurite utilise le protocole HTTP. Vous pouvez activer le mode HTTPS en fournissant un chemin d’accès à une messagerie améliorée à la confidentialité (.pem) ou échange d’informations personnelles (.pfx) fichier de certificat vers le commutateur --cert. HTTPS est requis pour se connecter à Azurite à l’aide de l'authentification OAuth.

Lorsque --cert est fourni pour un fichier PEM, vous devez fournir un commutateur --key correspondant.

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

Lorsque --cert est fourni pour un fichier PFX, vous devez fournir un commutateur --pwd correspondant.

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

Configuration HTTPS

Pour plus d’informations sur la génération de fichiers PEM et PFX, consultez configuration HTTPS.

Configuration OAuth

Facultatif : activez l’authentification OAuth pour Azurite à l’aide du commutateur --oauth.

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

Azurite prend en charge l’authentification de base en spécifiant le paramètre basic au commutateur --oauth. Azurite effectue l’authentification de base, par exemple la validation du jeton de porteur entrant, la vérification de l’émetteur, de l’audience et de l’expiration. Azurite ne vérifie pas la signature du jeton ou les autorisations. Pour en savoir plus sur l’autorisation, consultez la section Autorisation pour les outils et kits SDK.

Ignorer la vérification de la version de l’API

Facultatif : au démarrage, Azurite vérifie que la version de l’API demandée est valide. La commande suivante ignore la vérification de la version de l’API :

azurite --skipApiVersionCheck

Désactiver l’URL de style de production

Facultatif. Lorsque vous utilisez le nom de domaine complet au lieu de l’adresse IP de l’hôte d’URI de requête, Azurite analyse par défaut le nom du compte de stockage à partir de l’hôte d’URI de requête. Vous pouvez forcer l’analyse du nom du compte de stockage à partir du chemin de l’URI de requête à l’aide de --disableProductStyleUrl:

azurite --disableProductStyleUrl

Persistance en mémoire

Facultatif. Par défaut, les métadonnées d’objet blob et de file d’attente sont conservées sur le disque et le contenu est conservé dans les fichiers d’étendue. Le stockage table conserve toutes les données sur disque. Vous pouvez désactiver la persistance de toutes les données sur disque et stocker uniquement les données en mémoire. Dans le scénario de persistance en mémoire, si le processus Azurite est arrêté, toutes les données sont perdues. Le comportement de persistance par défaut peut être remplacé à l’aide de l’option suivante :

azurite --inMemoryPersistence

Ce paramètre est rejeté lorsque l’implémentation des métadonnées SQL est activée (via AZURITE_DB) ou lorsque l’option --location est spécifiée.

Limite de mémoire d’étendue

Facultatif. Par défaut, le magasin d’étendues en mémoire (pour le contenu d’objets blob et de file d’attente) est limité à 50 % de la mémoire totale sur l’ordinateur hôte. Le total est évalué à l’aide de os.totalmem(). Cette limite peut être remplacée à l’aide de l’option suivante :

azurite --extentMemoryLimit <megabytes>

Il n’existe aucune restriction sur la valeur spécifiée pour cette option, mais la mémoire virtuelle peut être utilisée si la limite dépasse la quantité de mémoire physique disponible fournie par le système d’exploitation. Une limite élevée peut éventuellement entraîner des erreurs de mémoire insuffisantes ou réduire les performances. Cette option est rejetée quand --inMemoryPersistence elle n’est pas spécifiée.

Pour plus d’informations, consultez Utiliser le stockage en mémoire.

Se connecter à Azurite avec des Kits de développement logiciel (SDK) et des outils

Vous pouvez vous connecter à Azurite à partir de SDK de Stockage Azure ou d’outils tels que l’Explorateur Stockage Azure. L’authentification est requise et Azurite prend en charge l’autorisation avec OAuth, une clé partagée et les signatures d’accès partagé (SAS, shared access signatures). Azurite prend également en charge l’accès anonyme aux conteneurs publics.

Pour plus d’informations sur l’utilisation d’Azurite avec les kits SDK Azure, consultez la section Kits SDK Azure.

Clé et compte de stockage reconnus

Ce compte et cette clé reconnus sont les mêmes que ceux utilisés par l’émulateur de stockage Azure hérité. Azurite les accepte.

• Nom du compte : devstoreaccount1
• Clé de compte : Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

Comptes et clés de stockage personnalisés

Azurite prend en charge les noms de compte et les clés de stockage personnalisés via la définition de la variable d’environnement AZURITE_ACCOUNTS au format suivant : account1:key1[:key2];account2:key1[:key2];....

Par exemple, utilisez un compte de stockage personnalisé qui a une clé :

set AZURITE_ACCOUNTS="account1:key1"

export AZURITE_ACCOUNTS="account1:key1"

Vous pouvez aussi utiliser plusieurs comptes de stockage avec deux clés chacun :

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

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

Par défaut, Azurite actualise les noms de compte et les clés personnalisés à partir de la variable d’environnement toutes les minutes. Avec cette fonctionnalité, vous pouvez effectuer dynamiquement une rotation de la clé de compte ou ajouter de nouveaux comptes de stockage sans redémarrer Azurite.

Les clés de compte doivent être une chaîne encodée en base64.

Chaînes de connexion

La méthode la plus simple pour vous connecter à Azurite à partir de votre application consiste à configurer une chaîne de connexion dans le fichier config de votre application, qui référence le raccourci UseDevelopmentStorage=true. Voici un exemple de chaîne de connexion dans un fichier app.config :

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

Chaînes de connexion HTTP

Vous pouvez transmettre les chaînes de connexion suivantes aux Kits de développement logiciel Azure (SDK) ou aux outils, comme Azure CLI 2.0 ou Explorateur Stockage.

La chaîne de connexion complète est :

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;

Pour vous connecter à un service spécifique, vous pouvez utiliser les chaînes de connexion suivantes :

Chaînes de connexion HTTPS

La chaîne de connexion HTTPS complète est :

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;

Pour vous connecter à un service spécifique, vous pouvez utiliser les chaînes de connexion suivantes :

Si vous avez utilisé dotnet dev-certs pour générer votre certificat auto-signé, utilisez la chaîne de connexion suivante :

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

Mettez à jour la chaîne de connexion lorsque vous utilisez des clés et comptes de stockage personnalisés.

Pour plus d’informations, consultez Configuration des chaînes de connexion Stockage Azure.

SDK Azure

Pour vous connecter à Azurite avec les kits de développement logiciel (SDK) Azure , procédez comme suit :

• Activez l’authentification OAuth pour Azurite via le commutateur --oauth. Pour plus d’informations, consultez configuration OAuth.
• Activez HTTPS à l’aide d’un certificat auto-signé via les options --cert et --key/--pwd. Pour en savoir plus sur la génération de certificats, consultez configuration de certificat (HTTPS) et configuration HTTPS.

Une fois les certificats en place, démarrez Azurite avec les options de ligne de commande suivantes :

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

Remplacez cert-name.pem et certname-key.pem par les noms de vos fichiers de certificat et de clé. Si vous utilisez un certificat PFX, utilisez l’option --pwd au lieu de l’option --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==")
  );

Explorateur Stockage Microsoft Azure

Vous pouvez utiliser Explorateur Stockage pour afficher les données stockées dans Azurite.

Se connecter à Azurite en utilisant le HTTP

Dans Explorateur Stockage, connectez-vous à Azurite en procédant comme suit :

1. Sélectionnez l’icône Manage Accounts (Gérer les comptes)
2. Sélectionnez Ajouter un compte.
3. Sélectionnez Attacher à un émulateur local
4. Sélectionnez Suivant.
5. Entrez le nom de votre choix dans le champ Display name (Nom complet)
6. Sélectionnez Suivant de nouveau
7. Sélectionnez Se connecter.

Se connecter à Azurite en utilisant le HTTPS

Par défaut Explorateur Stockage n’ouvre pas de point de terminaison HTTPS qui utilise un certificat auto-signé. Si vous exécutez Azurite avec le HTTPS, il vous faudra probablement utiliser un certificat auto-signé. Dans Explorateur Stockage, importez des certificats SSL via la boîte de dialogue Modifier ->Certificats SSL ->Importer des certificats.

Importer un certificat dans Explorateur Stockage

1. Recherchez le certificat sur votre ordinateur local.
2. Dans Explorateur Stockage, accédez à Modifier ->Certificats SSL ->Importer des certificats, puis importez votre certificat.

Si vous n’importez pas de certificat, vous obtenez une erreur :

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

Ajouter Azurite via une chaîne de connexion HTTPS

Pour ajouter Azurite HTTPS à Explorateur Stockage, procédez comme suit :

1. Sélectionnez Activer/désactiver l'Explorateur
2. Sélectionnez Local & Attached (Local et joint)
3. Cliquez avec le bouton droit sur Storage Accounts (Comptes de stockage), puis sélectionnez Connect to Azure Storage (Se connecter à Stockage Azure).
4. Sélectionnez Utiliser une chaîne de connexion.
5. Sélectionnez Suivant.
6. Entrez une valeur dans le champ Nom complet.
7. Entrez la chaîne de connexion HTTPS récupérée dans la section précédente de ce document
8. Sélectionnez Suivant.
9. Sélectionnez Se connecter.

Structure de l’espace de travail

Les fichiers et dossiers suivants peuvent être créés à l’emplacement de l’espace de travail lors de l’initialisation d’Azurite.

• __blobstorage__ : répertoire contenant les données binaires persistantes du service Blob Azurite
• __queuestorage__ : répertoire contenant les données binaires persistantes du service File d’attente Azurite
• __tablestorage__ : répertoire contenant les données binaires persistantes du service de table Azurite
• __azurite_db_blob__.json : fichier de métadonnées du service Blob Azurite
• __azurite_db_blob_extent__.json : fichier de métadonnées d’extension du service Blob Azurite
• __azurite_db_queue__.json : fichier de métadonnées du service File d’attente Azurite
• __azurite_db_queue_extent__.json : fichier de métadonnées d’extension du service File d’attente Azurite
• __azurite_db_table__.json : fichier de métadonnées du service de table Azurite
• __azurite_db_table_extent__.json : fichier de métadonnées d’extension du service de table Azurite

Pour nettoyer Azurite, supprimez les fichiers et dossiers ci-dessus, puis redémarrez l’émulateur.

Différences entre Azurite et Stockage Azure

Il existe des différences fonctionnelles entre une instance locale d’Azurite et un compte de stockage Azure dans le cloud.

Point de terminaison et URL de connexion

Les points de terminaison de service pour Azurite se distinguent des points de terminaison d’un compte de stockage Azure. Dans la mesure où l’ordinateur local n’effectue pas de résolution de noms de domaine, les points de terminaison Azurite doivent être des adresses locales.

Quand vous adressez une ressource dans un compte de stockage Azure, le nom du compte fait partie du nom d’hôte de l’URI. La ressource adressée fait partie du chemin de l’URI :

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

L’URI suivant est une adresse valide pour un objet blob dans un compte de stockage Azure :

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

URL de style IP

Dans la mesure où l’ordinateur local ne résout pas les noms de domaine, le nom du compte fait partie du chemin de l’URI au lieu du nom d’hôte. Utilisez le format d’URI suivant pour une ressource dans Azurite :

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

Vous pouvez utiliser l’adresse suivante pour accéder à un objet blob dans Azurite :

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

URL de style production

Si vous le souhaitez, vous pouvez modifier votre fichier d’hôte pour accéder à un compte avec une URL de style production.

Tout d’abord, ajoutez une ou plusieurs lignes à votre fichier d’hôte. Par exemple :

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

Ensuite, définissez des variables d’environnement pour activer des comptes de stockage et des clés personnalisés :

set AZURITE_ACCOUNTS="account1:key1:key2"

Vous pouvez ajouter d’autres comptes. Consultez la section Comptes de stockage et clés personnalisés de cet article.

Lancez Azurite et utilisez une chaîne de connexion personnalisée pour accéder à votre compte. Dans cet exemple, la chaîne de connexion suppose que les ports par défaut sont utilisés.

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

N’accédez pas au compte par défaut de cette façon avec l’Explorateur Stockage Azure. En raison d’un bogue, l’Explorateur Stockage ajoute toujours le nom du compte dans le chemin d’URL, ce qui entraîne des défaillances.

Par défaut, lors de l’utilisation d’Azurite avec une URL de style production, le nom du compte doit être le nom d’hôte dans un nom de domaine complet tel que http://devstoreaccount1.blob.localhost:10000/container. Pour utiliser l’URL de style production avec le nom du compte dans le chemin d’URL tel que http://foo.bar.com:10000/devstoreaccount1/container, veillez à utiliser le paramètre --disableProductStyleUrl lorsque vous démarrez Azurite.

Si vous utilisez host.docker.internal comme hôte d’URI de requête (par exemple http://host.docker.internal:10000/devstoreaccount1/container), Azurite récupère le nom du compte à partir du chemin de l’URI de requête. et ce, que le paramètre --disableProductStyleUrl soit ou non employé au démarrage d’Azurite.

Mise à l’échelle et niveau de performance

Azurite ne prend pas en charge la connexion simultanée d’un grand nombre de clients. Il est impossible de garantir le niveau de performance. Azurite est conçu à des fins de développement et de test.

Gestion des erreurs

Azurite s’aligne sur la logique de gestion des erreurs du Stockage Azure, mais il existe des différences. Par exemple, les messages d’erreur peuvent être différents, tandis que les codes d’état d’erreur s’alignent.

RA-GRS

Azurite prend en charge la réplication géoredondante avec accès en lecture (RA-GRS). Pour les ressources de stockage, accédez à l’emplacement secondaire en ajoutant -secondary au nom du compte. Par exemple, vous pouvez utiliser l’adresse suivante pour accéder à un objet blob à l’aide de l’emplacement secondaire en lecture seule dans Azurite :

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

Prise en charge des tables

Dans Azurite, la prise en charge des tables est actuellement disponible en préversion. Pour plus d’informations, consultez le projet Azurite V3 Table.

La prise en charge des fonctions durables requiert des tables.

Azurite est open source

Les contributions et suggestions relatives à Azurite sont les bienvenues. Accédez à la page des projets GitHub ou des problèmes GitHub relatifs à Azurite pour connaître les jalons et les éléments de travail que nous suivons en ce qui concerne les fonctionnalités à venir et les résolutions de bogues. Les éléments de travail détaillés sont également suivis dans GitHub.

Étapes suivantes

• Utiliser l’émulateur de stockage Azure pour le développement et le test documente l’émulateur de stockage Azure hérité, qui est remplacé par Azurite.
• L’article Configuration des chaînes de connexion Stockage Azure explique comment assembler une chaîne de connexion Stockage Azure valide.