Usare l'emulatore Azurite per lo sviluppo Archiviazione di Azure locale

L'emulatore open source Di Azurite offre un ambiente locale gratuito per testare le applicazioni BLOB di Azure, Queue Archiviazione e Table Archiviazione. Quando si è soddisfatti del funzionamento locale dell'applicazione, passare all'uso di un account Archiviazione di Azure nel cloud. L'emulatore fornisce supporto multipiattaforma in Windows, Linux e macOS.

Azurite sostituisce l'emulatore Archiviazione di Azure e continua a essere aggiornato per supportare le versioni più recenti delle API di Archiviazione di Azure.

Questo video illustra come installare ed eseguire l'emulatore Azurite.

I passaggi del video sono descritti anche nelle sezioni seguenti. Selezionare una di queste schede.

Installare 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

Run 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

Opzioni della riga di comando

In questa sezione vengono fornite informazioni dettagliate sulle opzioni della riga di comando disponibili durante l'avvio di Azurite.

Help

Facoltativo : ottenere la Guida della riga di comando usando l'opzione -h o --help .

azurite -h
azurite --help

Host di ascolto

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

Configurazione della porta di ascolto

azurite --blobPort 8888

azurite --blobPort 0

azurite --queuePort 8888

azurite --queuePort 0

azurite --tablePort 11111

azurite --tablePort 0

Percorso dell'area di lavoro

Facoltativo : Azurite archivia i dati nel disco locale durante l'esecuzione. Usare o -l --location per specificare un percorso come posizione dell'area di lavoro. Per impostazione predefinita, viene utilizzata la directory di lavoro del processo corrente. Si noti il minuscolo 'l'.

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

Log di accesso

Facoltativo : per impostazione predefinita, il log di accesso viene visualizzato nella finestra della console. Disabilitare la visualizzazione del log di accesso usando l'opzione -s o --silent .

azurite -s
azurite --silent

Log di debug

Facoltativo : il log di debug include informazioni dettagliate su ogni traccia dello stack di richieste ed eccezioni. Abilitare il log di debug specificando un percorso di file locale valido per l'opzione -d o --debug .

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

Modalità libera

Facoltativo : per impostazione predefinita, Azurite applica la modalità strict per bloccare le intestazioni e i parametri delle richieste non supportati. Disabilitare la modalità strict usando l'opzione -L o --loose . Si noti la maiuscola 'L'.

azurite -L
azurite --loose

Versione

Facoltativo : visualizzare il numero di versione di Azurite installato usando l'opzione -v o --version .

azurite -v
azurite --version

Configurazione del certificato (HTTPS)

Facoltativo : per impostazione predefinita, Azurite usa il protocollo HTTP. È possibile abilitare la modalità HTTPS fornendo un percorso a un file di certificato di Privacy Enhanced Mail (con estensione pem) o personal information exchange (pfx) al --cert commutatore. HTTPS è necessario per connettersi a Azurite usando l'autenticazione OAuth.

Quando --cert viene fornito per un file PEM, è necessario fornire un commutatore corrispondente --key .

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

Quando --cert viene fornito per un file PFX, è necessario fornire un commutatore corrispondente --pwd .

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

Configurazione HTTPS

Per informazioni dettagliate sulla generazione di file PEM e PFX, vedere Configurazione HTTPS.

Configurazione di OAuth

Facoltativo : abilitare l'autenticazione OAuth per Azurite usando l'opzione --oauth .

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

Azurite supporta l'autenticazione di base specificando il basic parametro per l'opzione --oauth . Azurite esegue l'autenticazione di base, ad esempio convalidare il token di connessione in ingresso, controllare l'autorità di certificazione, il pubblico e la scadenza. Azurite non controlla la firma o le autorizzazioni del token. Per altre informazioni sull'autorizzazione, vedere Autorizzazione per strumenti e SDK.

Ignorare il controllo della versione dell'API

Facoltativo : durante l'avvio, Azurite verifica che la versione dell'API richiesta sia valida. Il comando seguente ignora il controllo della versione dell'API:

azurite --skipApiVersionCheck

Disabilitare l'URL in stile produzione

Facoltativo. Quando si usa il nome di dominio completo anziché l'IP nell'host URI della richiesta, per impostazione predefinita Azurite analizza il nome dell'account di archiviazione dall'host URI della richiesta. È possibile forzare l'analisi del nome dell'account di archiviazione dal percorso dell'URI della richiesta usando --disableProductStyleUrl:

azurite --disableProductStyleUrl

Persistenza in memoria

Facoltativo. Per impostazione predefinita, i metadati di BLOB e coda vengono salvati in modo permanente su disco e il contenuto viene salvato in modo permanente in extent dei file. L'archiviazione tabelle rende persistenti tutti i dati su disco. È possibile disabilitare la persistenza di tutti i dati su disco e archiviare solo i dati in memoria. Nello scenario di persistenza in memoria, se il processo Azurite viene terminato, tutti i dati vengono persi. È possibile eseguire l'override del comportamento di persistenza predefinito usando l'opzione seguente:

azurite --inMemoryPersistence

Questa impostazione viene rifiutata quando l'implementazione dei metadati basata su SQL è abilitata (tramite AZURITE_DB) o quando viene specificata l'opzione --location .

Limite di memoria extent

Facoltativo. Per impostazione predefinita, l'archivio extent in memoria (per il contenuto blob e coda) è limitato al 50% della memoria totale nel computer host. Il totale viene valutato usando os.totalmem(). Questo limite può essere sottoposto a override usando l'opzione seguente:

azurite --extentMemoryLimit <megabytes>

Non esiste alcuna restrizione sul valore specificato per questa opzione, ma la memoria virtuale potrebbe essere usata se il limite supera la quantità di memoria fisica disponibile come specificato dal sistema operativo. Un limite elevato potrebbe causare alla fine errori di memoria insufficiente o prestazioni ridotte. Questa opzione viene rifiutata quando --inMemoryPersistence non viene specificata.

Per altre informazioni, vedere Usare l'archiviazione in memoria.

Connessione a Azurite con SDK e strumenti

È possibile connettersi a Azurite da SDK di Archiviazione di Azure o strumenti come Archiviazione di Azure Explorer. L'autenticazione è obbligatoria e Azurite supporta l'autorizzazione con OAuth, Chiave condivisa e firme di accesso condiviso ( SAS). Azurite supporta anche l'accesso anonimo ai contenitori pubblici.

Per altre informazioni sull'uso di Azurite con gli SDK di Azure, vedere Azure SDK.

Account di archiviazione e chiave noti

Azurite accetta lo stesso account noto e la stessa chiave usata dall'emulatore di Archiviazione di Azure legacy.

• Nome account: devstoreaccount1
• Chiave dell'account: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

Account e chiavi di archiviazione personalizzati

Azurite supporta nomi e chiavi di account di archiviazione personalizzati impostando la AZURITE_ACCOUNTS variabile di ambiente nel formato seguente: account1:key1[:key2];account2:key1[:key2];....

Ad esempio, usare un account di archiviazione personalizzato con una chiave:

set AZURITE_ACCOUNTS="account1:key1"

export AZURITE_ACCOUNTS="account1:key1"

In alternativa, usare più account di archiviazione con due chiavi:

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

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

Azurite aggiorna i nomi e le chiavi di account personalizzati dalla variabile di ambiente ogni minuto per impostazione predefinita. Con questa funzionalità, è possibile ruotare dinamicamente la chiave dell'account o aggiungere nuovi account di archiviazione senza riavviare Azurite.

Le chiavi dell'account devono essere una stringa con codifica Base64.

Stringhe di connessione

Il modo più semplice per connettersi a Azurite dall'applicazione consiste nel configurare un stringa di connessione nel file di configurazione dell'applicazione che fa riferimento al collegamento UseDevelopment Archiviazione=true. Ecco un esempio di stringa di connessione in un file app.config:

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

Stringa di connessione HTTP

È possibile passare i stringa di connessione seguenti agli SDK o agli strumenti di Azure, ad esempio l'interfaccia della riga di comando di Azure 2.0 o Archiviazione Explorer.

Il stringa di connessione completo è:

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;

Per connettersi a un servizio specifico, è possibile usare i stringa di connessione seguenti:

Stringa di connessione HTTPS

Il stringa di connessione HTTPS completo è:

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;

Per connettersi a un servizio specifico, è possibile usare i stringa di connessione seguenti:

Se è stato usato per generare il certificato autofirmatodotnet dev-certs, usare il stringa di connessione seguente.

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

Aggiornare il stringa di connessione quando si usano account di archiviazione e chiavi personalizzati.

Per altre informazioni, vedere Configurare le stringhe di connessione di Archiviazione di Azure.

Azure SDK

Per connettersi a Azurite con gli SDK di Azure, seguire questa procedura:

• Abilitare l'autenticazione OAuth per Azurite tramite l'opzione --oauth . Per altre informazioni, vedere Configurazione di OAuth.
• Abilitare HTTPS usando un certificato autofirmato tramite le --cert opzioni e/--key--pwd . Per altre informazioni sulla generazione di certificati, vedere Configurazione del certificato (HTTPS) e configurazione HTTPS.

Dopo aver eseguito i certificati, avviare Azurite con le opzioni della riga di comando seguenti:

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

Sostituire cert-name.pem e certname-key.pem con i nomi dei file di certificato e chiave. Se si usa un certificato PFX, usare l'opzione --pwd anziché l'opzione --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==")
  );

Microsoft Azure Storage Explorer

È possibile usare Archiviazione Explorer per visualizzare i dati archiviati in Azurite.

Connessione a Azurite tramite HTTP

In Archiviazione Explorer connettersi a Azurite seguendo questa procedura:

1. Selezionare l'icona Gestisci account
2. Selezionare Aggiungi un account
3. Selezionare Collega a un emulatore locale
4. Selezionare Avanti.
5. Modificare il campo Nome visualizzato in un nome di propria scelta
6. Selezionare di nuovo Avanti
7. Seleziona Connetti

Connessione a Azurite con HTTPS

Per impostazione predefinita, Archiviazione Explorer non apre un endpoint HTTPS che usa un certificato autofirmato. Se si esegue Azurite con HTTPS, è probabile che si usi un certificato autofirmato. In Archiviazione Explorer importare certificati SSL tramite la finestra di dialogo Modifica ->Certificati SSL ->Importa certificati.

Importare un certificato in Esplora Archiviazione

1. Trovare il certificato nel computer locale.
2. In Archiviazione Explorer passare a Modifica ->Certificati SSL ->Importa certificati e importare il certificato.

Se non si importa un certificato, viene visualizzato un errore:

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

Aggiungere Azurite tramite https stringa di connessione

Seguire questa procedura per aggiungere Azurite HTTPS a Archiviazione Explorer:

1. Selezionare Attiva/Disattiva Esplora risorse
2. Selezionare Locale e Collegato
3. Fare clic con il pulsante destro del mouse su account Archiviazione e selezionare Connessione per Archiviazione di Azure.
4. Selezionare Usa un stringa di connessione
5. Selezionare Avanti.
6. Immettere un valore nel campo Nome visualizzato.
7. Immettere il stringa di connessione HTTPS della sezione precedente di questo documento
8. Selezionare Avanti.
9. Seleziona Connetti

Struttura dell'area di lavoro

È possibile creare i file e le cartelle seguenti nel percorso dell'area di lavoro durante l'inizializzazione di Azurite.

• __blobstorage__ - Directory contenente i dati binari persistenti del servizio BLOB di Azurite
• __queuestorage__ - Directory contenente i dati binari persistenti del servizio di accodamento di Azurite
• __tablestorage__ - Directory contenente i dati binari persistenti del servizio tabelle di Azurite
• __azurite_db_blob__.json - File di metadati del servizio BLOB Azurite
• __azurite_db_blob_extent__.json - File di metadati dell'extent del servizio BLOB di Azurite
• __azurite_db_queue__.json - File di metadati del servizio di accodamento di Azurite
• __azurite_db_queue_extent__.json - File di metadati dell'extent del servizio di accodamento di Azurite
• __azurite_db_table__.json - File di metadati del servizio tabelle di Azurite
• __azurite_db_table_extent__.json - File di metadati dell'extent del servizio tabelle di Azurite

Per pulire Azurite, eliminare i file e le cartelle precedenti e riavviare l'emulatore.

Differenze tra Azurite e Archiviazione di Azure

Esistono differenze funzionali tra un'istanza locale di Azurite e un account Archiviazione di Azure nel cloud.

ENDPOINT e URL di connessione

Gli endpoint di servizio per Azurite sono diversi dagli endpoint di un account Archiviazione di Azure. Il computer locale non esegue la risoluzione dei nomi di dominio, richiedendo che gli endpoint di Azurite siano indirizzi locali.

Quando si indirizza una risorsa in un account Archiviazione di Azure, il nome dell'account fa parte del nome host dell'URI. La risorsa indirizzata fa parte del percorso URI:

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

L'URI seguente è un indirizzo valido per un BLOB in un account Archiviazione di Azure:

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

URL in stile IP

Poiché il computer locale non risolve i nomi di dominio, il nome dell'account fa parte del percorso URI anziché del nome host. Usare il formato URI seguente per una risorsa in Azurite:

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

L'indirizzo seguente può essere usato per accedere a un BLOB in Azurite:

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

URL in stile produzione

Facoltativamente, è possibile modificare il file hosts per accedere a un account con l'URL in stile produzione .

Prima di tutto, aggiungere una o più righe al file hosts. Ad esempio:

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

Impostare quindi le variabili di ambiente per abilitare gli account di archiviazione e le chiavi personalizzati:

set AZURITE_ACCOUNTS="account1:key1:key2"

È possibile aggiungere altri account. Vedere la sezione Account di archiviazione e chiavi personalizzati di questo articolo.

Avviare Azurite e usare un stringa di connessione personalizzato per accedere al tuo account. Nell'esempio seguente, il stringa di connessione presuppone che vengano usate le porte predefinite.

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

Non accedere all'account predefinito in questo modo con Archiviazione di Azure Explorer. È presente un bug che Archiviazione Explorer aggiunge sempre il nome dell'account nel percorso URL, causando errori.

Per impostazione predefinita, quando si usa Azurite con un URL di produzione, il nome dell'account deve essere il nome host nel nome di dominio completo, http://devstoreaccount1.blob.localhost:10000/containerad esempio . Per usare l'URL di produzione con il nome dell'account nel percorso URL, http://foo.bar.com:10000/devstoreaccount1/containerad esempio , assicurarsi di usare il parametro all'avvio --disableProductStyleUrl di Azurite.

Se si usa host.docker.internal come host URI di richiesta (ad esempio: http://host.docker.internal:10000/devstoreaccount1/container), Azurite ottiene il nome dell'account dal percorso dell'URI della richiesta. Questo comportamento è vero indipendentemente dal fatto che si usi il --disableProductStyleUrl parametro quando si avvia Azurite.

Scalabilità e prestazioni

Azurite non supporta un numero elevato di clienti connessi. Non esiste alcuna garanzia di prestazioni. Azurite è destinato a scopi di sviluppo e test.

Gestione degli errori

Azurite è allineato con Archiviazione di Azure logica di gestione degli errori, ma ci sono differenze. Ad esempio, i messaggi di errore potrebbero essere diversi, mentre i codici di stato degli errori sono allineati.

RA-GRS

Azurite supporta la replica con ridondanza geografica e accesso in lettura (RA-GRS). Per le risorse di archiviazione, accedere alla posizione secondaria aggiungendo -secondary al nome dell'account. Ad esempio, l'indirizzo seguente può essere usato per accedere a un BLOB usando il database secondario di sola lettura in Azurite:

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

Supporto tabelle

Il supporto per le tabelle in Azurite è attualmente disponibile in anteprima. Per altre informazioni, vedere il progetto Tabella V3 di Azurite.

Il supporto per le funzioni durevoli richiede tabelle.

Azurite è open source

I contributi e i suggerimenti per Azurite sono benvenuti. Passare alla pagina del progetto GitHub di Azurite o ai problemi di GitHub per le attività cardine e gli elementi di lavoro che verranno monitorati per le funzionalità future e le correzioni di bug. Gli elementi di lavoro dettagliati vengono rilevati anche in GitHub.

Passaggi successivi

• Usare l'emulatore Archiviazione di Azure per lo sviluppo e il test dei documenti relativi all'emulatore di Archiviazione di Azure legacy, sostituito da Azurite.
• Configurare Archiviazione di Azure stringa di connessione spiega come assemblare un Archiviazione di Azure stringa di connessione valido.