Использование эмулятора Azurite для разработки локальной службы хранилища Azure

Эмулятор с открытым исходным кодом Azurite предоставляет бесплатную локальную среду для тестирования ваших приложений, использующих хранилище блоб-объектов Azure, хранилище очередей и хранилище таблиц. Если вы удовлетворены тем, как приложение работает локально, перейдите на использование учетной записи хранения Azure в облаке. Эмулятор обеспечивает кроссплатформенную поддержку в Windows, Linux и macOS.

Azurite заменяет эмулятор службы хранилища Azure и продолжает обновляться для поддержки последних версий API службы хранилища Azure.

В этом видео показано, как установить и запустить эмулятор Azurite.

Действия в видео также описаны в следующих разделах. Выберите любую из этих вкладок.

Установка 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

Запустите 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

Параметры командной строки

В этом разделе описаны параметры командной строки, доступные при запуске Azurite.

Помощь

Необязательно — Получите справку для командной строки, используя переключатели -h и --help.

azurite -h
azurite --help

Прослушивание хоста

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

Настройка порта прослушивания

azurite --blobPort 8888

azurite --blobPort 0

azurite --queuePort 8888

azurite --queuePort 0

azurite --tablePort 11111

azurite --tablePort 0

Путь к рабочей области

Необязательно . Azurite сохраняет данные на локальный диск во время выполнения. -l Используйте или --location переключитесь, чтобы указать путь в качестве расположения рабочей области. По умолчанию используется текущий рабочий каталог процесса. Обратите внимание, что буква 'l' используется в нижнем регистре.

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

журнал доступа;

Необязательно. По умолчанию журнал доступа отображается в окне консоли. Отключите отображение журнала доступа с помощью -s или --silent переключения.

azurite -s
azurite --silent

Журнал отладки

Необязательно — Журнал отладки включает подробные сведения о каждом запросе и трассировке стека исключения. Включите журнал отладки, указав допустимый путь к локальному файлу для переключателя -d или --debug.

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

Свободный режим

Необязательно . По умолчанию Azurite применяет строгий режим для блокировки неподдерживаемых заголовков и параметров запроса. Отключите строгий режим с помощью переключателя -L или --loose. Обратите внимание на заглавную букву "L".

azurite -L
azurite --loose

Версия

Необязательно . Отображение установленного номера версии Azurite с помощью -v или --version переключателя.

azurite -v
azurite --version

Конфигурация сертификата (HTTPS)

Необязательно . По умолчанию Azurite использует протокол HTTP. Вы можете включить режим HTTPS, указав путь к файлу сертификата с расширенной защитой конфиденциальности (.pem) или к файлу сертификата обмена персональными данными (.pfx) для переключателя --cert. Протокол HTTPS необходим для подключения к Azurite с помощью проверки подлинности OAuth.

Если для PEM-файла предоставлено --cert, необходимо указать соответствующий --key переключатель.

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

Если --cert для PFX-файла предоставлено, необходимо указать соответствующий --pwd коммутатор.

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

Настройка HTTPS

Подробные сведения о создании PEM и PFX-файлов см. в разделе "Настройка HTTPS".

Конфигурация OAuth

Необязательно . Включите проверку подлинности OAuth для Azurite с помощью --oauth переключателя.

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

Azurite поддерживает базовую проверку подлинности, указав basic параметр для коммутатора --oauth . Azurite выполняет базовую проверку подлинности, например проверку входящего маркера носителя, проверку издателя, аудитории и истечения срока действия. Azurite не проверяет подпись токена или разрешения. Дополнительные сведения об авторизации см. в разделе "Авторизация" для средств и пакетов SDK.

Пропустить проверку версии API

Необязательно . При запуске Azurite проверяет, является ли запрошенная версия API допустимой. Следующая команда пропускает проверку версии API:

azurite --skipApiVersionCheck

Отключение производственного стиля URL.

Необязательно. При использовании полного доменного имени вместо IP-адреса в узле URI запроса Azurite по умолчанию анализирует имя учетной записи хранения из узла URI запроса. Вы можете принудительно выполнить синтаксический анализ имени учетной записи хранения из пути URI запроса с помощью --disableProductStyleUrl:

azurite --disableProductStyleUrl

Сохраняемость в памяти

Необязательно. По умолчанию метаданные BLOB-объектов и очередей сохраняются на диске, а содержимое сохраняется в файлах экстентов. Хранилище таблиц сохраняет все данные на диске. Вы можете отключить сохранение любых данных на диске и хранить только данные в памяти. В сценарии сохраняемости в памяти, если процесс Azurite завершается, все данные теряются. Поведение сохраняемости по умолчанию можно переопределить с помощью следующего параметра:

azurite --inMemoryPersistence

Этот параметр отклоняется при включении реализации метаданных на основе SQL (через AZURITE_DB) или при указании --location параметра.

Ограничение памяти для экстентов

Необязательно. По умолчанию хранилище экстентов в памяти (для содержимого больших двоичных объектов и очередей) ограничено 50% общего объема памяти на хост-компьютере. Общее значение вычисляется с помощью os.totalmem(). Это ограничение можно переопределить с помощью следующего параметра:

azurite --extentMemoryLimit <megabytes>

Нет ограничений на значение, указанное для этого параметра, но виртуальная память может использоваться, если ограничение превышает объем доступной физической памяти, как указано операционной системой. Высокий предел может в конечном итоге привести к ошибкам памяти или снижению производительности. Этот параметр отклоняется, если --inMemoryPersistence не указан.

Дополнительные сведения см. в статье "Использование хранилища в памяти".

Отключение сбора данных телеметрии

Необязательно. По умолчанию Azurite собирает данные телеметрии для улучшения продукта. Используйте параметр --disableTelemetry, чтобы отключить сбор данных телеметрии для текущего выполнения Azurite. Например, такая команда:

azurite --disableTelemetry

Подключение к Azurite с помощью пакетов SDK и средств

Вы можете подключиться к Azurite из пакетов SDK службы хранилища Azure или таких средств, как Обозреватель службы хранилища Azure. Требуется проверка подлинности, а Azurite поддерживает авторизацию с помощью OAuth, общего ключа и подписанных URL-адресов (SAS). Azurite также поддерживает анонимный доступ к общедоступным контейнерам.

Дополнительные сведения об использовании Azurite с пакетами SDK Azure см. в статье о пакетах SDK Azure.

Общеизвестная учетная запись хранения и ключ

Azurite принимает ту же известную учетную запись и ключ, который используется устаревшим эмулятором службы хранилища Azure.

• Имя учетной записи: devstoreaccount1
• Ключ учетной записи: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

Пользовательские учетные записи для хранения и ключи

Azurite поддерживает пользовательские имена учетных записей и ключи хранения, задав AZURITE_ACCOUNTS переменную среды в следующем формате: account1:key1[:key2];account2:key1[:key2];...

Например, используйте пользовательскую учетную запись хранения с одним ключом:

set AZURITE_ACCOUNTS="account1:key1"

export AZURITE_ACCOUNTS="account1:key1"

Или используйте несколько учетных записей хранения с двумя ключами.

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

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

Azurite обновляет имена и ключи пользовательских учетных записей из переменной среды каждую минуту по умолчанию. С помощью этой функции можно динамически повернуть ключ учетной записи или добавить новые учетные записи хранения без перезапуска Azurite.

Ключи учетной записи должны быть строкой в кодировке Base64.

Строки подключения

Самый простой способ подключения к Azurite из приложения — настроить строку подключения в файле конфигурации приложения, который ссылается на ярлык UseDevelopmentStorage=true. Ниже приведен пример строки подключения в файлеapp.config :

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

Строки http-подключения

Следующие строки подключения можно передать в Azure SDKs или такие средства, как Azure CLI 2.0 или Storage Explorer.

Полная строка подключения:

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;

Чтобы подключиться к определенной службе, можно использовать следующие строки подключения:

Строки подключения HTTPS

Полная строка подключения HTTPS:

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;

Чтобы подключиться к определенной службе, можно использовать следующие строки подключения:

Если вы использовали dotnet dev-certs для создания самозаверяющего сертификата, используйте следующую строку подключения.

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

Обновите строку подключения при использовании пользовательских учетных записей и ключей хранения.

Дополнительные сведения см. в статье Настройка строк подключения службы хранилища Azure.

Пакеты SDK для Azure

Чтобы подключиться к Azurite с помощью пакетов SDK Azure, выполните следующие действия.

• Включите проверку подлинности OAuth для Azurite с помощью коммутатора --oauth . Дополнительные сведения см. в разделе конфигурации OAuth.
• Включите HTTPS с помощью самозаверяющего сертификата через параметры --cert и --key/--pwd. Дополнительные сведения о создании сертификатов см. в статье о настройке сертификата (HTTPS) и настройке HTTPS.

После того как сертификаты будут установлены, запустите Azurite со следующими параметрами командной строки:

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

Замените cert-name.pem и certname-key.pem на имена ваших файлов сертификата и ключа. Если вы используете PFX-сертификат, используйте --pwd этот параметр вместо --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

Обозреватель службы хранилища можно использовать для просмотра данных, хранящихся в Azurite.

Подключение к Azurite с помощью HTTP

В обозревателе службы хранилища подключитесь к Azurite, выполнив следующие действия.

1. Щелкните значок "Управление учетными записями"
2. Выберите "Добавить учетную запись"
3. Выберите "Подключиться к локальному эмулятору"
4. Выберите "Далее"
5. Измените поле отображаемого имени на имя по вашему выбору.
6. Снова нажмите кнопку "Далее"
7. Выберите Подключиться.

Подключение к Azurite с помощью HTTPS

По умолчанию обозреватель службы хранилища не открывает конечную точку HTTPS, использующую самозаверяющий сертификат. Если вы используете Azurite с HTTPS, скорее всего, вы используете самозаверяющий сертификат. В обозревателе службы хранилища импортируйте SSL-сертификаты с помощью диалогового окна "Изменить>SSL-сертификаты ->импорт сертификатов".

Импорт сертификата в Storage Explorer

1. Найдите сертификат на локальном компьютере.
2. В обозревателе службы хранилища перейдите к разделу "Изменить>SSL-сертификаты ->импорт сертификатов" и импортируйте сертификат.

Если сертификат не импортирован, вы получите сообщение об ошибке:

unable to verify the first certificate или self signed certificate in chain

Добавление Azurite через строку подключения HTTPS

Выполните следующие действия, чтобы добавить Azurite HTTPS в Storage Explorer:

1. Выберите Toggle Explorer
2. Выбор "Локальный" и "Присоединено"
3. Щелкните правой кнопкой мыши учетные записи хранения и выберите "Подключиться к службе хранилища Azure".
4. Выберите "Использовать строку подключения"
5. Выберите Далее.
6. Введите значение в поле отображаемого имени.
7. Введите строку подключения HTTPS из предыдущего раздела этого документа
8. Выберите "Далее"
9. Выберите Подключиться.

Структура рабочей области

В расположении рабочей области при инициализации Azurite могут быть созданы следующие файлы и папки.

• __blobstorage__ — каталог, содержащий сохранённые двоичные данные службы объектов BLOB Azurite
• __queuestorage__ — Каталог, содержащий службу очередей Azurite, сохраняемые двоичные данные
• __tablestorage__ — Каталог, содержащий службу таблиц Azurite, сохраняемые двоичные данные
• __azurite_db_blob__.json — файл метаданных службы блобов Azurite
• __azurite_db_blob_extent__.json — файл метаданных областей службы Blob Azurite
• __azurite_db_queue__.json — файл метаданных службы очередей Azurite
• __azurite_db_queue_extent__.json — файл метаданных сегментов службы очередей Azurite
• __azurite_db_table__.json — файл метаданных службы таблиц Azurite
• __azurite_db_table_extent__.json — файл метаданных экстентов службы таблиц Azurite

Чтобы очистить Azurite, удалите указанные выше файлы и папки и перезапустите эмулятор.

Различия между Azurite и службой хранилища Azure

Существуют функциональные различия между локальным экземпляром Azurite и учетной записью хранения Azure в облаке.

URL-адрес конечной точки и подключения

Конечные точки службы для Azurite отличаются от конечных точек учетной записи хранения Azure. Локальный компьютер не выполняет разрешение доменных имен, из-за чего точки доступа Azurite должны быть локальными адресами.

При обращении к ресурсу в учетной записи Azure Storage, имя учетной записи является частью имени узла URI. Адрес ресурса является частью пути URI:

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

Следующий URI является допустимым адресом блоба в учетной записи хранилища Azure:

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

URL-адрес в стиле IP

Так как локальный компьютер не разрешает доменные имена, имя учетной записи является частью пути URI вместо имени узла. Используйте следующий формат URI для ресурса в Azurite:

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

Для доступа к blob в Azurite может быть использован следующий адрес:

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

URL-адрес в стиле рабочей среды

При желании можно изменить файл hosts, чтобы получить доступ к учетной записи с URL-адресом в стиле производственной среды.

Сначала добавьте одну или несколько строк в файл hosts. Рассмотрим пример.

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

Затем задайте переменные среды, чтобы включить настраиваемые учетные записи хранения и ключи:

set AZURITE_ACCOUNTS="account1:key1:key2"

Можно добавить дополнительные учетные записи. См. раздел "Пользовательские учетные записи хранения" и "Ключи " этой статьи.

Запустите Azurite и используйте настраиваемую строку подключения для доступа к вашей учетной записи. В следующем примере строка подключения предполагает, что используются порты по умолчанию.

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

Не используйте обозреватель Azure Storage для доступа к учетной записи по умолчанию этим способом. Обозреватель хранилища всегда добавляет имя учетной записи в URL-путь, что приводит к сбоям.

По умолчанию при использовании Azurite с URL-адресом в стиле продакшн имя учетной записи должно быть именем узла в полном доменном имени, например http://devstoreaccount1.blob.localhost:10000/container. Чтобы использовать URL-адрес в рабочем стиле с именем учетной записи в пути URL-адреса, например http://foo.bar.com:10000/devstoreaccount1/container, обязательно используйте --disableProductStyleUrl параметр при запуске Azurite.

Если вы используете host.docker.internal в качестве узла URI запроса (например, http://host.docker.internal:10000/devstoreaccount1/container), Azurite получает имя учетной записи из пути URI запроса. Это поведение верно независимо от того, используется --disableProductStyleUrl ли параметр при запуске Azurite.

Масштабирование и производительность

Azurite не поддерживает большое количество подключенных клиентов. Нет гарантии производительности. Azurite предназначен для разработки и тестирования.

Обработка ошибок

Azurite соответствует логике обработки ошибок службы хранилища Azure, но существуют различия. Например, сообщения об ошибках могут отличаться, тем временем коды состояния ошибок совпадают.

RA-GRS

Azurite поддерживает геоизбыточную репликацию с доступом для чтения (RA-GRS). Для ресурсов хранилища получите доступ к дополнительному расположению, добавив -secondary к имени учетной записи. Например, следующий адрес может использоваться для доступа к большому двоичному объекту с помощью вторичного объекта только для чтения в Azurite:

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

Поддержка таблиц

Поддержка таблиц в Azurite в настоящее время доступна в предварительной версии. Дополнительные сведения см. в проекте Azurite V3 Table.

Для поддержки устойчивых функций требуются таблицы.

Azurite — это открытый исходный код

Взносы и предложения для Azurite приветствуются. Перейдите на страницу проекта Azurite GitHub или задачи на GitHub, чтобы ознакомиться с вехами и рабочими элементами, которые мы отслеживаем для предстоящих функций и исправлений ошибок. Подробные рабочие элементы также отслеживаются в GitHub.

Дальнейшие действия

• Документ «Эмулятор хранилища Azure для разработки и тестирования» описывает устаревший эмулятор хранилища Azure, который заменен на Azurite.
• Настройка строк подключения службы хранилища Azure объясняет, как собрать допустимую строку подключения службы хранилища Azure.