Usar o emulador Azurite para o desenvolvimento local do Armazenamento do Microsoft Azure

O emulador de código aberto Azurite fornece um ambiente local gratuito para testar aplicativos de Blob, Armazenamento de Filas e Armazenamento de Tabelas do Azure. Quando estiver satisfeito com o funcionamento de seu aplicativo no local, alterne para usar uma conta de Armazenamento do Microsoft Azure na nuvem. O emulador fornece suporte cruzado em várias plataformas como no Windows, Linux e macOS.

O Azurite substitui o Emulador de Armazenamento do Azure e continua sendo atualizado para dar suporte às versões mais recentes das APIs do Armazenamento do Azure.

Este vídeo mostra como instalar e executar o emulador do Azurite.

As etapas no vídeo também são descritas nas seções a seguir. Selecione uma das guias abaixo.

Instalar o 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

Executar 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

Opções de linha de comando

Esta seção detalha as opções de linha de comando disponíveis ao iniciar o Azurite.

Ajuda

Opcional - obtém ajuda na linha de comando usando a opção -h ou --help.

azurite -h
azurite --help

Host de escuta

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

Configuração da porta de escuta

azurite --blobPort 8888

azurite --blobPort 0

azurite --queuePort 8888

azurite --queuePort 0

azurite --tablePort 11111

azurite --tablePort 0

Caminho do espaço de trabalho

Opcional - o Azurite armazena dados no disco local durante a execução. Use a opção -l ou --location para especificar um caminho como o local do espaço de trabalho. Por padrão, é usado o diretório de trabalho do processo atual. Observe o ' l' minúsculo.

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

Log de acesso

Opcional – por padrão, o log de acesso é exibido na janela do console. Desabilite a exibição do log de acesso usando a opção -s ou --silent.

azurite -s
azurite --silent

Log de depuração

Opcional - o log de depuração inclui informações detalhadas sobre cada solicitação e o rastreamento de pilha das exceções. Habilite o log de depuração fornecendo um caminho de arquivo local válido para a opção -d ou --debug.

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

Modo livre

Opcional – por padrão, o Azurite aplica o modo estrito para bloquear os cabeçalhos e os parâmetros não compatíveis das solicitações. Desabilite o modo estrito usando opção -L ou --loose. Observe o ' L' maiúsculo.

azurite -L
azurite --loose

Versão

Opcional – exibe o número de versão do Azurite instalado usando a opção -v ou --version.

azurite -v
azurite --version

Configuração do certificado (HTTPS)

Opcional – por padrão, o Azurite usa o protocolo HTTP. Habilite o modo HTTPS fornecendo um caminho para o arquivo do certificado Privacy Enhanced Mail (.pem) ou Personal Information Exchange (.pfx) na opção --cert. O HTTPS é necessário para se conectar ao Azurite usando a autenticação OAuth.

Quando --cert é fornecido para um arquivo PEM, você deve fornecer uma opção --key correspondente.

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

Quando --cert é fornecido para um arquivo PFX, você deve fornecer uma opção --pwd correspondente.

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

Configuração de HTTPS

Para obter informações mais detalhadas sobre como gerar arquivos PEM e PFX, confira Configuração do HTTPS.

Configuração do OAuth

Opcional - habilite a autenticação OAuth para o Azurite usando a opção --oauth.

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

O Azurite suporta a autenticação básica por meio do parâmetro basic para a opção --oauth. O Azurite faz a autenticação básica, como validar o token de portador de entrada, verificar o emissor, o público-alvo e a expiração. O Azurite não verifica a assinatura ou as permissões do token. Para saber mais sobre a autorização, confira Autorização para ferramentas e SDKs.

Ignorar verificação de versão da API

Opcional – ao iniciar, o Azurite verifica se a versão de API solicitada é válida. O comando a seguir ignora a verificação de versão da API:

azurite --skipApiVersionCheck

Desabilitar URL de estilo de produção

Opcional. Ao usar o nome de domínio totalmente qualificado em vez do IP no host do URI de solicitação, por padrão, o Azurite analisa o nome da conta de armazenamento do host do URI da solicitação. Você pode forçar a análise do nome da conta de armazenamento no caminho do URI de solicitação usando --disableProductStyleUrl:

azurite --disableProductStyleUrl

Persistência na memória

Opcional. Por padrão, os metadados de blob e de fila são mantidos no disco e o conteúdo é mantido nos arquivos de extensão. O armazenamento de tabelas persiste todos os dados em disco. Você pode desabilitar a persistência de todos os dados no disco e armazenar apenas dados na memória. No cenário de persistência na memória, se o processo do Azurite for encerrado, todos os dados serão perdidos. O comportamento de persistência padrão pode ser substituído por meio da seguinte opção:

azurite --inMemoryPersistence

Essa configuração é rejeitada quando a implementação de metadados baseada em SQL é habilitada (por meio de AZURITE_DB) ou quando a opção --location é especificada.

Limite da memória de extensão

Opcional. Por padrão, o repositório de extensão na memória (para o conteúdo de blob e de fila) é limitado a 50% da memória total no computador host. O total é avaliado com os.totalmem(). Esse limite pode ser substituído por meio da seguinte opção:

azurite --extentMemoryLimit <megabytes>

Não há nenhuma restrição ao valor especificado para essa opção, mas a memória virtual poderá ser usada se o limite exceder a quantidade de memória física disponível, conforme fornecido pelo sistema operacional. Em última análise, um limite alto pode resultar em erros de memória insuficiente ou na redução de desempenho. Essa opção é rejeitada quando --inMemoryPersistence não é especificado.

Para saber mais, confira Usar o armazenamento na memória.

Conectar ao Azurite com SDKs e ferramentas

Você pode se conectar ao Azurite a partir dos SDKs do Armazenamento do Azure ou de ferramentas como o Gerenciador de Armazenamento do Azure. É necessário se autenticar, e o Azurite é compatível com autorizações via OAuth, chave compartilhada e SAS (assinaturas de acesso compartilhado). O Azurite também é compatível com acesso anônimo a contêineres públicos.

Para saber mais sobre como usar o Azurite com os SDKs do Azure, confira SDKs do Azure.

Chave e conta de armazenamento conhecidas

O Azurite aceita a mesma conta e chave conhecidas usadas pelo Emulador de Armazenamento do Microsoft Azure herdado.

• Nome da conta: devstoreaccount1
• Chave da conta: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

Chaves e contas de armazenamento personalizadas

O Azurite aceita chaves e nomes de contas de armazenamento personalizados, se a variável de ambiente AZURITE_ACCOUNTS for definida no seguinte formato: account1:key1[:key2];account2:key1[:key2];....

Por exemplo, use uma conta de armazenamento personalizada que tenha uma chave:

set AZURITE_ACCOUNTS="account1:key1"

export AZURITE_ACCOUNTS="account1:key1"

Ou use várias contas de armazenamento com duas chaves cada:

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

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

Por padrão, o Azurite atualiza os nomes de conta e as chaves personalizadas a partir da variável de ambiente a cada minuto. Com esse recurso, você pode girar dinamicamente a chave de conta ou adicionar novas contas de armazenamento sem reiniciar o Azurite.

As chaves da conta precisam ser uma cadeia de caracteres codificada em base64.

Cadeias de conexão

A maneira mais fácil de conectar o Azurite a partir do seu aplicativo é configurar uma cadeia de conexão no arquivo de configuração do aplicativo que faz referência ao atalho UseDevelopmentStorage=true. Abaixo está um exemplo de uma cadeia de conexão em um arquivo app.config:

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

Cadeias de conexão HTTP

Você pode passar as seguintes cadeias de conexão para os SDKs ou ferramentas do Azure, como CLI do Azure 2.0 ou Gerenciador de Armazenamento.

A cadeia de conexão completa é:

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 se conectar a um serviço específico, use as seguintes cadeias de conexão:

Cadeias de conexão HTTPS

A cadeia de conexão HTTPS completa é:

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 se conectar a um serviço específico, use as seguintes cadeias de conexão:

Se você usou dotnet dev-certs para gerar seu certificado autoassinado, use a cadeia de conexão a seguir.

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

Atualize a cadeia de conexão ao usar as chaves e contas de armazenamento personalizadas.

Para saber mais, confira Configurar cadeias de conexão do Armazenamento do Azure.

SDKs do Azure

Para se conectar ao Azurite com os SDKs do Azure, siga estas etapas:

• Habilite a autenticação OAuth para o Azurite usando a opção --oauth. Para saber mais, confira Configuração do OAuth.
• Habilite o HTTPS usando um certificado autoassinado por meio das opções --cert e --key/--pwd. Para saber mais sobre como gerar certificados, confira Configuração de certificado (HTTPS) e Configuração do HTTPS.

Depois que os certificados estiverem em vigor, inicie o Azurite com as seguintes opções de linha de comando:

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

Substitua cert-name.pem e certname-key.pem pelos nomes dos arquivos de certificado e de chave. Se estiver usando um certificado PFX, use a opção --pwd em vez da opção --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==")
  );

Gerenciador do Armazenamento do Microsoft Azure

Você pode usar o Gerenciador de Armazenamento para visualizar os dados armazenados no Azurite.

Conectar-se ao Azurite usando HTTP

Em Gerenciador de Armazenamento, conecte-se ao Azurite seguindo estas etapas:

1. Selecione o ícone Gerenciar Contas
2. Selecione Adicionar uma conta
3. Selecione Anexar a um emulador local
4. Selecione Avançar
5. Edite o campo Nome de exibição para inserir um nome de sua escolha
6. Selecione novamente Avançar
7. Selecione Conectar

Conectar-se ao Azurite usando HTTPS

Por padrão, o Gerenciador de Armazenamento não abre um ponto de extremidade HTTPS que usa um certificado autoassinado. Se você estiver executando o Azurite com HTTPS, provavelmente está usando um certificado autoassinado. Em Gerenciador de Armazenamento, importe os certificados SSL por meio da caixa de diálogo Editar ->Certificados SSL ->Importar Cerificados.

Importar certificado para o Gerenciador de Armazenamento

1. Encontre o certificado no seu computador local.
2. Em Gerenciador de Armazenamento, vá até Editar ->Certificados SSL ->Importar Certificados e importe seu certificado.

Se você não importar um certificado, receberá um erro:

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

Adicionar o Azurite usando a cadeia de conexão HTTPS

Siga estas etapas para adicionar o HTTPS Azurite ao Gerenciador de Armazenamento:

1. Selecione Alternar Explorer
2. Selecione Local e Anexado
3. Clique com o botão direito do mouse em Contas de Armazenamento e selecione Conectar-se ao Armazenamento do Microsoft Azure.
4. Selecione Usar uma cadeia de conexão
5. Selecione Avançar.
6. Insira um valor no campo Nome de exibição.
7. Insira a cadeia de conexão HTTPS da seção anterior deste documento
8. Selecione Avançar
9. Selecione Conectar

Estrutura do espaço de trabalho

Os arquivos e as pastas a seguir podem ser criados no local do workspace durante a inicialização do Azurite.

• __blobstorage__ - diretório contendo dados binários gravados do serviço Blob do Azurite
• __queuestorage__ - diretório contendo dados binários gravados do serviço de fila do Azurite
• __tablestorage__ - diretório contendo dados binários gravados do serviço de tabela do Azurite
• __azurite_db_blob__.json - arquivo de metadados do serviço Blob do Azurite
• __azurite_db_blob_extent__.json - arquivo de metadados de extensão do serviço Blob do Azurite
• __azurite_db_queue__.json - arquivo de metadados do serviço de fila do Azurite
• __azurite_db_queue_extent__.json - arquivo de metadados de extensão do serviço de fila do Azurite
• __azurite_db_table__.json - arquivo de metadados do serviço de tabela do Azurite
• __azurite_db_table_extent__.json - arquivo de metadados de extensão do serviço de tabela do Azurite

Para limpar o Azurite, exclua os arquivos e as pastas acima e reinicie o emulador.

Diferenças entre o Azurite e o Armazenamento do Microsoft Azure

Há diferenças funcionais entre uma instância local do Azurite e uma conta do Armazenamento do Azure na nuvem.

Ponto de extremidade e conexão URL

Os pontos de extremidade de serviço para a Azurite são diferentes dos pontos de extremidade de uma conta de Armazenamento do Azure. O computador local não resolve nomes de domínio, exigindo que os pontos de extremidade do Azurite sejam endereços locais.

Quando você endereça um recurso em uma conta de Armazenamento do Azure, o nome da conta faz parte do nome do host URI. O recurso que está sendo endereçado faz parte do caminho do URI:

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

Por exemplo, o seguinte URI é um endereço válido para um blob em uma conta de Armazenamento do Azure:

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

URL no estilo IP

Como o computador local não resolve os nomes de domínio, o nome da conta faz parte do caminho do URI e não do nome do host. Use o seguinte formato de URI para um recurso no Azurite:

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

O endereço a seguir pode ser usado para acessar um blob no Azurite:

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

URL no estilo de produção

Opcionalmente, você pode modificar o arquivo de hosts para acessar uma conta com a URL no estilo de produção.

Primeiro, adicione uma ou mais linhas ao arquivo de hosts. Por exemplo:

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

Depois, defina variáveis de ambiente para habilitar as chaves e as contas de armazenamento personalizadas:

set AZURITE_ACCOUNTS="account1:key1:key2"

Você pode adicionar mais contas. Confira a seção Chaves e contas de armazenamento personalizadas deste artigo.

Inicie o Azurite e use uma cadeia de conexão personalizada para acessar sua conta. No exemplo a seguir, a cadeia de conexão pressupõe que são usadas as portas padrão.

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ão acesse a conta padrão dessa forma com o Gerenciador de Armazenamento do Azure. Há um bug em que o Gerenciador de Armazenamento está sempre adicionando o nome da conta no caminho da URL, causando falhas.

Por padrão, quando o Azurite é usado com uma URL de estilo de produção, o nome da conta deve ser o nome do host no nome de domínio totalmente qualificado, como http://devstoreaccount1.blob.localhost:10000/container. Para usar a URL de estilo de produção com o nome da conta no caminho da URL, como http://foo.bar.com:10000/devstoreaccount1/container, use o parâmetro --disableProductStyleUrl ao iniciar o Azurite.

Se você usar host.docker.internal como o host do URI de solicitação (por exemplo: http://host.docker.internal:10000/devstoreaccount1/container), o Azurite obtém o nome da conta do caminho do URI de solicitação. Esse comportamento é verdadeiro independentemente de você usar ou não o parâmetro --disableProductStyleUrl ao iniciar o Azurite.

Dimensionamento e desempenho

O Azurite não suporta um grande número de clientes conectados. Não há garantia de desempenho. O Azurite destina-se para desenvolvimentos e testes.

Tratamento de erros

O Azurite está alinhado com a lógica de tratamento de erros do Armazenamento do Microsoft Azure, mas há diferenças. Por exemplo, as mensagens de erro podem ser diferentes, embora os códigos de status de erro estejam alinhados.

RA-GRS

O Azurite suporta a replicação com redundância geográfica com acesso de leitura (RA-GRS). Para recursos de armazenamento, acesse o local secundário anexando -secondary ao nome da conta. Por exemplo, o endereço a seguir pode ser usado para acessar um blob usando o secundário de somente leitura no Azurite:

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

Suporte a tabelas

No momento, o suporte para tabelas está em versão prévia no Azurite. Para obter mais informações, confira o projeto Tabela do Azurite v3.

O suporte para funções duráveis requer tabelas.

O Azurite é open-source

As contribuições e sugestões para o Azurite são bem-vindas. Vá até a página do Projeto GitHub do Azurite ou Problemas do GitHub para conhecer os marcos e itens do trabalho que estamos acompanhando das futuras funcionalidades e correções de bugs. Os itens de trabalho detalhados também são acompanhados no GitHub.

Próximas etapas

• O artigo Usar o Emulador do Armazenamento do Microsoft Azure para desenvolvimento e teste documenta o Emulador do Armazenamento do Microsoft Azure herdado, que foi substituído pelo Azurite.
• Configurar cadeias de conexão do Armazenamento do Microsoft Azure: explica como montar uma cadeia de conexão válida do Armazenamento do Microsoft Azure.