Импорт и экспорт данных с помощью расширения azure_storage в База данных Azure для PostgreSQL — гибкий сервер

Статья
11/19/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: База данных Azure для PostgreSQL — гибкий сервер

Расширение azure_storage позволяет импортировать или экспортировать данные в нескольких форматах файлов непосредственно между учетными записями служба хранилища Azure и экземпляром гибкого сервера База данных Azure для PostgreSQL.

Примеры экспорта и импорта данных с помощью этого расширения см. в разделе "Примеры " этой статьи.

Чтобы использовать azure_storage расширение на База данных Azure для PostgreSQL гибком экземпляре сервера, необходимо разрешить расширение, загрузить библиотеку и создать расширение.

Обзор процедуры

Определите учетные записи служба хранилища Azure, с которыми требуется взаимодействие пользователей azure_storage расширения.
Определите тип авторизации, который вы хотите использовать для запросов, сделанных в службе BLOB-объектов каждой из этих служба хранилища Azure учетных записей. azure_storage расширение поддерживает авторизацию с общим ключом и авторизацию с помощью идентификатора Microsoft Entra. Из этих двух типов авторизации идентификатор Microsoft Entra обеспечивает более высокую безопасность и простоту использования по общему ключу, и является одним из рекомендуемых корпорацией Майкрософт. Чтобы удовлетворить необходимые условия в каждом случае, следуйте инструкциям в соответствующих разделах:
- Авторизация с помощью идентификатора Microsoft Entra или
- Авторизация с помощью общего ключа.
Включить azure_storage в shared_preload_libraries:

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

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --query value --output tsv)

az postgres flexible-server restart --resource-group <flexible_server_resource_group> --name <flexible_server_name>

Использование конфигураций — размещение REST API.

Так как сервер shared_preload_libraries является статическим, сервер должен быть перезапущен для того, чтобы изменения вступили в силу. Для перезапуска сервера можно использовать СЕРВЕР — перезапустить REST API.

Включить azure_storage в azure.extensions:

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --query value --output tsv)

Используя клиент вашего предпочтения (например, psql, pgAdmin и т. д.), подключитесь к любой базе данных в экземпляре База данных Azure для PostgreSQL гибкого сервера. Чтобы создать все объекты SQL (таблицы, типы, функции, представления и т. д.), с помощью которых можно использовать azure_storage расширение для взаимодействия с экземплярами учетных записей служба хранилища Azure, выполните следующую инструкцию:
```
CREATE EXTENSION azure_storage;
```
azure_storage.account_* Используя функции, добавьте ссылки на служба хранилища Azure учетные записи, которым требуется разрешить пользователям Или ролям PostgreSQL доступ к расширениюazure_storage. Эти ссылки включают имя учетной записи служба хранилища Azure, на которой ссылается ссылка, и тип проверки подлинности, используемый при взаимодействии с учетной записью служба хранилища Azure. В зависимости от выбранного типа проверки подлинности может потребоваться также указать другие параметры, например ключ доступа к учетной записи служба хранилища Azure или маркер SAS.

Внимание

Для типов проверки подлинности, для которых необходимо предоставить ключ доступа к учетной записи служба хранилища Azure, обратите внимание, что ключи доступа служба хранилища Azure похожи на корневой пароль для учетной записи хранения. Всегда будьте осторожны, чтобы защитить их. Для безопасного управления ключами и их замены воспользуйтесь Azure Key Vault. azure_storage расширение сохраняет эти ключи в таблице azure_storage.accounts , которую можно считывать членами pg_read_all_data роли.

Пользователи, которым предоставлена azure_storage_admin роль, могут взаимодействовать с таблицей azure_storage.accounts с помощью следующих функций:

azure_storage.account_add
azure_storage.account_list
azure_storage.account_remove
azure_storage.account_user_add
azure_storage.account_user_remove

Роль azure_storage_admin по умолчанию предоставляется azure_pg_admin роли.

Использование авторизации с идентификатором Microsoft Entra

Включите управляемое удостоверение, назначаемое системой, на экземпляре База данных Azure для PostgreSQL гибкого сервера.

az rest --method patch --url https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<flexible_server_resource_group>/providers/Microsoft.DBforPostgreSQL/flexibleServers/<flexible_server_name>?api-version=2024-08-01 --body '{"identity":{"type":"SystemAssigned"}}'

Перезапустите экземпляр гибкого сервера База данных Azure для PostgreSQL после включения управляемого удостоверения, назначаемого системой.
Назначьте разрешения на управление доступом на основе ролей (RBAC) для доступа к данным больших двоичных объектов в учетной записи служба хранилища Azure управляемому удостоверению вашего экземпляра База данных Azure для PostgreSQL гибкого сервера.

Использование авторизации с общим ключом

У вашей учетной записи служба хранилища Azure должен быть включен доступ к ключу учетной записи хранения (т. е. не удается задать для свойства AllowSharedKeyAccess значение false).

az storage account update --resource-group <storage_account_resource_group> --name <account_name> --allow-shared-key-access true

Чтобы передать его в функцию azure_storage.account_add, получите один из двух ключей доступа учетной записи служба хранилища Azure.

az storage account keys list --resource-group <storage_account_resource_group> --account-name <account_name> --query [0].value -o tsv

Функции

azure_storage.account_add

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

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

Примечание.

Эта функция не проверяет, существует ли имя учетной записи или доступно ли оно с помощью ключа доступа. Однако он проверяет, является ли имя учетной записи хранения допустимым в соответствии с правилами проверки именования, введенными для учетных записей хранения Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

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

azure_storage.account_add(account_config jsonb);

Разрешения

Должен быть членом azure_storage_admin.

Аргументы

account_name_p

text Имя учетной записи хранения BLOB-объектов Azure, содержащей все объекты: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен, доступное из любой точки мира по протоколу HTTPS.

account_key_p

text значение одного из ключей доступа для учетной записи хранения. Ключи доступа к хранилищу BLOB-объектов Azure похожи на корневой пароль для учетной записи хранения. Не забудьте защитить ключи доступа. Для безопасного управления ключами и их замены воспользуйтесь Azure Key Vault. Ключ учетной записи хранится в таблице, доступной только суперпользователем. Пользователи, которым предоставлена azure_storage_admin роль, могут взаимодействовать с этой таблицей с помощью функций. Чтобы узнать, какие учетные записи хранения добавляются, используйте функцию azure_storage.account_list.

account_config

jsonbимя учетной записи служба хранилища Azure и все необходимые параметры, такие как тип проверки подлинности, тип учетной записи или учетные данные хранения. Мы рекомендуем использовать служебные функции azure_storage.account_options_managed_identity, azure_storage.account_options_credentials или azure_storage.account_options для создания любого из допустимых значений, которые необходимо передать в качестве этого аргумента.

Возвращаемый тип

VOID

azure_storage.account_options_managed_identity

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр в azure_storage.account_add, и полезна для создания допустимого значения аргумента account_config при использовании управляемого удостоверения, назначаемого системой, для взаимодействия с учетной записью служба хранилища Azure.

azure_storage.account_options_managed_identity(name text, type azure_storage.storage_type);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

name

type

azure_storage.storage_type значение одного из поддерживаемых типов хранилища. Поддерживается blobтолько значение.

Возвращаемый тип

jsonb

azure_storage.account_options_credentials

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр в azure_storage.account_add, и полезна для создания допустимого значения аргумента account_config при использовании ключа доступа служба хранилища Azure для взаимодействия с учетной записью служба хранилища Azure.

azure_storage.account_options_credentials(name text, credentials text, type azure_storage.storage_type);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

name

учетные данные

type

azure_storage.storage_type значение одного из поддерживаемых типов хранилища. Поддерживается blobтолько значение.

Возвращаемый тип

jsonb

azure_storage.account_options

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр в azure_storage.account_add, и полезна для создания допустимого значения аргумента account_config при использовании ключа доступа служба хранилища Azure или управляемого удостоверения, назначенного системой, для взаимодействия с учетной записью служба хранилища Azure.

azure_storage.account_options(name text, auth_type azure_storage.auth_type, storage_type azure_storage.storage_type, credentials text DEFAULT NULL);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

name

auth_type

azure_storage.auth_type значение одного из поддерживаемых типов хранилища. Поддерживаются access-keyтолько значения, а managed-identityтакже .

storage_type

azure_storage.storage_type значение одного из поддерживаемых типов хранилища. Поддерживается blobтолько значение.

учетные данные

Возвращаемый тип

jsonb

azure_storage.account_remove

Функция, которая позволяет удалить учетную запись хранения и связанный с ним ключ доступа из списка учетных записей хранения, к которым azure_storage может получить доступ расширение.

azure_storage.account_remove(account_name_p text);

Разрешения

Должен быть членом azure_storage_admin.

Аргументы

account_name_p

Возвращаемый тип

VOID

azure_storage.account_user_add

Функция, которая позволяет предоставлять пользователю Или роли PostgreSQL доступ к учетной записи хранения через функции, предоставляемые расширением azure_storage .

Примечание.

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

azure_storage.account_add(account_name_p text, user_p regrole);

Разрешения

Должен быть членом azure_storage_admin.

Аргументы

account_name_p

user_p

regrole имя пользователя Или роли PostgreSQL, доступной на сервере.

Возвращаемый тип

VOID

azure_storage.account_user_remove

Функция, которая позволяет отменить доступ пользователя Или роли PostgreSQL к учетной записи хранения через функции, предоставляемые расширением azure_storage .

Примечание.

Выполнение этой функции выполняется только в том случае, если имя учетной записи хранения, имя которой передается в качестве первого аргумента, уже создано с помощью azure_storage.account_add, и если пользователь или роль, имя которой передается в качестве второго аргумента, по-прежнему существует. При удалении пользователя или роли с сервера путем выполнения DROP USER | ROLEразрешения, предоставленные для любой ссылки на служба хранилища Azure учетных записей, также автоматически удаляются.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Разрешения

Должен быть членом azure_storage_admin.

Аргументы

account_name_p

user_p

regrole имя пользователя Или роли PostgreSQL, доступной на сервере.

Возвращаемый тип

VOID

azure_storage.account_list

Функция, которая перечисляет имена учетных записей хранения, настроенных с помощью функции azure_storage.account_add , вместе с пользователями или ролями PostgreSQL, которые предоставляют разрешения на взаимодействие с этой учетной записью хранения через функции, предоставляемые azure_storage расширением.

azure_storage.account_list();

Разрешения

Должен быть членом azure_storage_admin.

Аргументы

Эта функция не принимает никаких аргументов.

Возвращаемый тип

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[])Таблица с четырьмя столбцами со списком добавленных учетных записей служба хранилища Azure, тип проверки подлинности, используемый для взаимодействия с каждой учетной записью, типом хранилища и списком пользователей Или ролей PostgreSQL, которым предоставлен доступ.

azure_storage.blob_list

Функция, которая перечисляет имена и другие свойства (размер, lastModified, eTag, contentType, contentEncoding и contentHash) больших двоичных объектов, хранящихся в указанном контейнере указанной учетной записи хранения.

azure_storage.blob_list(account_name text, container_name text, prefix text DEFAULT ''::text);

Разрешения

Пользователь или роль, вызывающие эту функцию, необходимо добавить в список разрешенных пользователей, account_name выполнив azure_storage.account_user_add. azure_storage_admin Участники автоматически могут ссылаться на все служба хранилища Azure учетные записи, ссылки на которые были добавлены с помощью azure_storage.account_add.

Аргументы

account_name

container_name

text имя контейнера. Контейнер упорядочивает набор больших двоичных объектов, как каталог в файловой системе. Учетная запись хранения может содержать неограниченное количество контейнеров. В каждом контейнере может храниться неограниченное количество больших двоичных объектов. Имя контейнера должно быть допустимым именем системы доменных имен (DNS), так как оно входит в уникальный универсальный код ресурса (URI), используемый для адресов контейнера или больших двоичных объектов. При именовании контейнера обязательно следуйте этим правилам.

Универсальный код ресурса (URI) для контейнера аналогичен: https://myaccount.blob.core.windows.net/mycontainer

prefix

text При указании функция возвращает большие двоичные объекты, имена которых начинаются со значения, указанного в этом параметре. По умолчанию используется пустая строка.

Возвращаемый тип

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) Таблица с одной записью для каждого возвращаемого большого двоичного объекта, включая полное имя большого двоичного объекта и некоторые другие свойства.

path

text полное имя большого двоичного объекта.

байт

bigint размер большого двоичного объекта в байтах.

last_modified

timestamp with time zoneдата и время последнего изменения большого двоичного объекта. Любая операция, которая изменяет большой двоичный объект, включая обновление метаданных или свойств большого двоичного объекта, изменяет время последнего изменения большого двоичного объекта.

etag

text Свойство ETag используется для оптимистического параллелизма во время обновлений. Это не метка времени, так как есть другое свойство с именем Timestamp, которое сохраняет последний раз, когда запись была обновлена. Например, если вы загружаете сущность и хотите обновить ее, ETag должна соответствовать тому, что сейчас хранится. Настройка соответствующего ETag важна, так как если у вас несколько пользователей редактировали один и тот же элемент, вы не хотите, чтобы они перезаписывали изменения друг друга.

content_type

text Тип контента, указанный для большого двоичного объекта. Тип контента по умолчанию — application/octet-stream.

content_encoding

textСвойство Content-Encoding большого двоичного объекта, который служба хранилища Azure позволяет определить. Для сжатого содержимого можно задать для свойства Gzip. Когда браузер обращается к содержимому, он автоматически распаковывает содержимое.

content_hash

text Хэш, используемый для проверки целостности большого двоичного объекта во время транспорта. При указании этого заголовка служба хранилища проверяет предоставленный хэш с одним вычисляемого из содержимого. Если два хэша не соответствуют, операция завершается ошибкой с кодом 400 (недопустимый запрос).

azure_storage.blob_get

Функция, которая позволяет импортировать данные. Он загружает файл из контейнера BLOB-объектов в учетной записи служба хранилища Azure. Затем он преобразует содержимое в строки, которые можно использовать и обрабатывать с помощью конструкций языка SQL. Эта функция добавляет поддержку фильтрации и управления данными, полученными из контейнера BLOB-объектов перед импортом.

Примечание.

Прежде чем пытаться получить доступ к контейнеру для указанной учетной записи хранения, эта функция проверяет, допустимы ли имена учетной записи хранения и контейнера в качестве аргументов в соответствии с правилами проверки именования, введенными в учетных записях хранения Azure. Если один из них недопустим, возникает ошибка.

azure_storage.blob_get(account_name text, container_name text, path text, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

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

azure_storage.blob_get(account_name text, container_name text, path text, rec anyelement, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

Разрешения

Аргументы

account_name

container_name

Универсальный код ресурса (URI) для контейнера аналогичен: https://myaccount.blob.core.windows.net/mycontainer

path

text полное имя большого двоичного объекта.

rec

anyelement определение выходной структуры записи.

дешифратор

text спецификация формата большого двоичного объекта. Можно задать любое из следующих значений:

Формат	По умолчанию	Description
`auto`	`true`	Выводит значение на основе последней серии символов, назначенных имени большого двоичного объекта. Если имя большого двоичного объекта заканчивается `.csv` или `.csv.gz`предполагается `csv`. Если заканчивается или `.tsv` `.tsv.gz`предполагается `tsv`. Если заканчивается , `.json.xml.gz.xml.txt.json.gz`или `.txt.gz`, предполагается.`text`
`csv`		Формат разделенных запятыми значений, используемый PostgreSQL COPY.
`tsv`		Значения, разделенные табуляции, формат копирования PostgreSQL по умолчанию.
`binary`		Двоичный формат PostgreSQL COPY.
`text` \| `xml` \| `json`		Файл, содержащий одно текстовое значение.

compression

text спецификация типа сжатия. Можно задать любое из следующих значений:

Формат	По умолчанию	Description
`auto`	`true`	Выводит значение на основе последней серии символов, назначенных имени большого двоичного объекта. Если имя большого двоичного объекта заканчивается `.gz`, предполагается `gzip`. В противном случае предполагается `none`.
`gzip`		Принудительно использует декодировщик gzip для распаковки большого двоичного объекта.
`none`		Принудительно обрабатывает большой двоичный объект как тот, который не требует декомпрессии.

Расширение не поддерживает другие типы сжатия.

options

jsonb Параметры, определяющие обработку пользовательских заголовков, настраиваемых разделителей, escape-символов и т. д. options влияет на поведение этой функции таким образом, как параметры, которые можно передать команде COPY в PostgreSQL, влияют на его поведение.

Возвращаемый тип

SETOF record SETOF anyelement

azure_storage.blob_put

Функция, которая позволяет экспортировать данные, отправляя файлы в контейнер BLOB-объектов в учетной записи служба хранилища Azure. Содержимое файлов создается из строк в PostgreSQL.

Примечание.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record)
RETURNS VOID;

Существует перегруженная версия функции, содержащая encoder параметр, который позволяет указать кодировщик, который следует использовать, если его нельзя вывести из расширения path параметра, или когда требуется переопределить один вывод.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text)
RETURNS VOID;

Существует перегруженная версия функции, которая также содержит compression параметр, который позволяет указать сжатие, используемое, когда его нельзя выводить из расширения path параметра, или когда требуется переопределить вывод одного из выводимых.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text)
RETURNS VOID;

Существует перегруженная версия функции, которая также содержит options параметр для обработки пользовательских заголовков, пользовательских разделителей, escape-символов и т. д. options работает аналогично параметрам, которые можно передать команде COPY в PostgreSQL.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text, options jsonb)
RETURNS VOID;

Разрешения

Аргументы

account_name

container_name

Универсальный код ресурса (URI) для контейнера аналогичен: https://myaccount.blob.core.windows.net/mycontainer

path

text полное имя большого двоичного объекта.

tuple

record определение выходной структуры записи.

кодировщик

text спецификация формата большого двоичного объекта. Можно задать любое из следующих значений:

Формат	По умолчанию	Description
`auto`	`true`	Выводит значение на основе последней серии символов, назначенных имени большого двоичного объекта. Если имя большого двоичного объекта заканчивается `.csv` или `.csv.gz`предполагается `csv`. Если заканчивается или `.tsv` `.tsv.gz`предполагается `tsv`. Если заканчивается , `.json.xml.gz.xml.txt.json.gz`или `.txt.gz`, предполагается.`text`
`csv`		Формат разделенных запятыми значений, используемый PostgreSQL COPY.
`tsv`		Значения, разделенные табуляции, формат копирования PostgreSQL по умолчанию.
`binary`		Двоичный формат PostgreSQL COPY.
`text` \| `xml` \| `json`		Файл, содержащий одно текстовое значение.

compression

text спецификация типа сжатия. Можно задать любое из следующих значений:

Формат	По умолчанию	Description
`auto`	`true`	Выводит значение на основе последней серии символов, назначенных имени большого двоичного объекта. Если имя большого двоичного объекта заканчивается `.gz`, предполагается `gzip`. В противном случае предполагается `none`.
`gzip`		Принудительно использует декодировщик gzip для распаковки большого двоичного объекта.
`none`		Принудительно обрабатывает большой двоичный объект как тот, который не требует декомпрессии.

Расширение не поддерживает другие типы сжатия.

options

Возвращаемый тип

VOID

azure_storage.options_csv_get

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр внутри blob_get, и полезна для декодирования содержимого CSV-файла.

azure_storage.options_csv_get(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

разделитель

text Символ, разделяющий столбцы в каждой строке (строке) файла. Это должен быть один 1-байтовый символ. Хотя эта функция поддерживает разделители любого количества символов, если вы пытаетесь использовать более одного байтового символа, PostgreSQL сообщает об ошибке COPY delimiter must be a single one-byte character .

null_string

text строка, представляющая значение NULL. Значение по умолчанию — \N (backslash-N) в текстовом формате и неквалированная пустая строка в формате CSV. Вы можете предпочесть пустую строку даже в текстовом формате, если вы не хотите различать значения NULL от пустых строк.

boolean флаг, указывающий, содержит ли файл строку заголовка с именами каждого столбца в файле. В выходных данных начальная строка содержит имена столбцов из таблицы.

quote

text символ кавычек, используемый при кавычках значения данных. По умолчанию используется двойная кавычка. Это должен быть один 1-байтовый символ. Хотя эта функция поддерживает разделители любого количества символов, если вы пытаетесь использовать более одного байтового символа, PostgreSQL сообщает об ошибке COPY quote must be a single one-byte character .

escape

text Символ, который должен отображаться перед символом данных, соответствующим значению QUOTE. Значение по умолчанию совпадает со значением QUOTE (чтобы символ кавычки был двойным, если он отображается в данных). Это должен быть один 1-байтовый символ. Хотя эта функция поддерживает разделители любого количества символов, если вы пытаетесь использовать более одного байтового символа, PostgreSQL сообщает об ошибке COPY escape must be a single one-byte character .

force_not_null

text[] не совпадайте со значениями указанных столбцов со строкой NULL. В случае, если строка NULL пуста, это означает, что пустые значения считываются как строки нулевой длины, а не null, даже если они не кавычки.

force_null

text[] сопоставляет значения указанных столбцов со строкой NULL, даже если кавычки найдены, а если совпадение найдено, задайте значение NULL. В случае, если строка NULL пуста, она преобразует в кавычки пустую строку в NULL.

content_encoding

text имя кодировки, с которой кодируется файл. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_copy

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр внутри blob_get. Он выступает в качестве вспомогательной функции для options_csv_get, options_tsv и options_binary.

azure_storage.options_copy(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_quote text[] DEFAULT NULL::text[], force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

разделитель

null_string

авторизации

quote

escape

force_quote

text[] принудительно используется для всех значений, отличных от NULL, в каждом указанном столбце. Выходные данные NULL никогда не цитируются. Если задано значение *, значения, отличные от NULL, указываются во всех столбцах.

force_not_null

force_null

content_encoding

text имя кодировки, с которой кодируется файл. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_tsv

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр внутри blob_get, и полезна для декодирования содержимого tsv-файла.

azure_storage.options_tsv(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, content_encoding text DEFAULT NULL::text);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

разделитель

null_string

content_encoding

text имя кодировки, с которой кодируется файл. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_binary

Функция, которая выступает в качестве служебной функции, которая может вызываться как параметр внутри blob_get, и полезна для декодирования содержимого двоичного файла.

azure_storage.options_binary(content_encoding text DEFAULT NULL::text);

Разрешения

Любой пользователь или роль могут вызывать эту функцию.

Аргументы

content_encoding

text имя кодировки, с которой кодируется файл. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

Возможные ошибки

ОШИБКА: azure_storage. Разрешение не достаточно для выполнения запрошенной операции

При выполнении каких-либо функций, взаимодействующих с служба хранилища Azure (azure_storage.blob_listилиazure_storage.blob_put) и управляемого удостоверения, назначенным системой, azure_storage.blob_get не предоставляются соответствующие роли или разрешения уровня данных (как правило, минимальный участник данных хранилища для azure_storage.blob_put и минимальное число средств чтения данных BLOB-объектов хранилища для других двух функций).

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

ОШИБКА: azure_storage: отсутствуют учетные данные хранения

При выполнении любых функций, взаимодействующих с служба хранилища Azure (azure_storage.blob_listazure_storage.blob_getилиazure_storage.blob_put) и учетными данными, с которыми требуется пройти проверку подлинности с учетной записью хранения, не регистрироваться.azure_storage.account_add

ОШИБКА: azure_storage: внутренняя ошибка при подключении

Если экземпляр гибкого сервера не может связаться с целевой учетной записью хранения. Это может произойти в следующих случаях:

Учетная запись хранения не существует.
Конфигурация сети не разрешает трафик, исходящий из экземпляра гибкого сервера, для доступа к учетной записи хранения. Например, если экземпляр гибкого сервера развертывается с помощью сети общедоступного доступа, а учетная запись хранения доступна только через частные конечные точки.

Если управляемое удостоверение, назначенное системой, не включено в экземпляре гибкого сервера.

ОШИБКА: azure_storage: недопустимый формат учетных данных хранилища

Если управляемое удостоверение, назначенное системой, включено на экземпляр гибкого сервера, но сервер не был перезапущен после включения.

ОШИБКА: azure_storage: текущий пользователь <user_or_role не может использовать учетную запись <хранения account_name>>

При выполнении любых функций, взаимодействующих с служба хранилища Azure (azure_storage.blob_listилиazure_storage.blob_put) с пользователем или ролью, azure_storage.blob_get которая не является членом azure_storage_admin и не предоставляет разрешения, используя azure_storage.account_user_addучетную запись хранения, используемую для использования указанной учетной записи хранения.

Примеры

Перед выполнением следующих примеров необходимо выполнить следующие предварительные требования:

Создайте учетную запись Службы хранилища Azure. Чтобы создать учетную запись служба хранилища Azure, если у вас еще нет учетной записи, настройте значения <resource_group>, <location><account_name>и <container_name>выполните следующую команду Azure CLI:
```
resource_group=<resource_group>
location=<location>
storage_account=<account_name>
blob_container=<container_name>
az group create --name $resource_group --location $location
az storage account create --resource-group $resource_group --name $storage_account --location $location --sku Standard_LRS --kind BlobStorage --public-network-access enabled --access-tier hot
```
Создайте контейнер BLOB объектов. Чтобы создать контейнер BLOB-объектов, выполните следующую команду Azure CLI:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Получите один из двух ключей доступа, назначенных учетной записи хранения. Скопируйте значение access_key, так как необходимо передать его в качестве аргумента для azure_storage.account_add на следующем шаге. Чтобы получить первый из двух ключей доступа, выполните следующую команду Azure CLI:
```
access_key=$(az storage account keys list --resource-group $resource_group --account-name $storage_account --query [0].value)
echo "Following is the value of your access key:"
echo $access_key
```

Скачайте файл с набором данных, который используется в примерах, и отправьте его в контейнер BLOB-объектов. Чтобы скачать файл с набором данных, выполните следующую команду Azure CLI:

mkdir --parents azure_storage_examples
cd azure_storage_examples
curl -O https://examples.citusdata.com/tutorial/events.csv
gzip -k events.csv
cp events.csv events_blob_without_extension
cp events.csv events_pipe.csv
cp events.csv.gz events_compressed
sed -i 's/,/|/g' events_pipe.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "events*" --account-key $access_key --overwrite --output none --only-show-errors

Примечание.

Вы можете перечислить контейнеры или большие двоичные объекты, хранящиеся в них для определенной учетной записи хранения, но только если пользователю Или роли PostgreSQL предоставлено разрешение на ссылку на эту учетную запись хранения с помощью azure_storage.account_user_add. azure_storage_admin Членам роли предоставляется эта привилегия для всех учетных записей служба хранилища Azure, добавленных с помощью azure_storage.account_add. По умолчанию только члены azure_pg_admin предоставляются azure_storage_admin роли.

Создание таблицы, в которой загружаются данные

Создадим таблицу, в которую мы импортируем содержимое CSV-файла, который мы отправили в учетную запись хранения. Для этого подключитесь к экземпляру База данных Azure для PostgreSQL гибкого сервера с помощью PgAdminили psqlклиента вашего предпочтения и выполните следующую инструкцию:

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

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

В этом примере показано, как добавить ссылку на учетную запись хранения вместе с ключом доступа к этой учетной записи хранения, которая требуется для доступа к его содержимому через функциональные возможности, предоставляемые azure_storage расширением в экземпляре База данных Azure для PostgreSQL гибкого сервера.

<account_name> необходимо задать имя учетной записи хранения. Если вы использовали предыдущие скрипты, это значение должно соответствовать значению, заданному переменной среды storage_account в этих сценариях.

Аналогичным образом необходимо задать значение, <access_key> которое вы извлекли из учетной записи хранения.

SELECT azure_storage.account_add('<account_name>', '<access_key>');

Совет

Если вы хотите получить имя учетной записи хранения и один из его ключей доступа из портал Azure, найдите учетную запись хранения, в меню ресурсов выберите ключи доступа, скопируйте имя учетной записи хранения и скопируйте ключ из раздела key1 (сначала нажмите кнопку "Показать рядом с ключом").

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

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

SELECT azure_storage.account_remove('<account_name>');

Предоставление доступа пользователю или роли в справочнике по хранилищу BLOB-объектов Azure

В этом примере показано, как предоставить пользователю или роли <regular_user>доступ, чтобы такой пользователь PostgreSQL использовал azure_storage расширение для доступа к BLOB-объектам, хранящимся в контейнерах, размещенных в учетной записи хранения Azure.

<regular_user> необходимо задать имя существующего пользователя или роли.

SELECT * FROM azure_storage.account_user_add('<account_name>', '<regular_user>');

Список всех ссылок на учетные записи хранения Azure

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

SELECT * FROM azure_storage.account_list();

Отзыв доступа от пользователя или роли в справочнике по хранилищу BLOB-объектов Azure

В этом примере показано, как отозвать доступ от имени пользователя или роли <regular_user>, чтобы такой пользователь PostgreSQL не смог использовать azure_storage расширение для доступа к BLOB-объектам, хранящимся в контейнерах, размещенных в учетной записи хранения Azure.

<regular_user> необходимо задать имя существующего пользователя или роли.

SELECT * FROM azure_storage.account_user_remove('<account_name>', '<regular_user>');

Перечисление всех больших двоичных объектов в контейнере

В этом примере показано, как перечислить все существующие большие двоичные объекты в контейнере <container_name> учетной записи <account_name>хранения.

<container_name> необходимо задать имя контейнера BLOB-объектов. Если вы использовали предыдущие сценарии, это значение должно соответствовать значению, заданному переменной среды blob_container в этих сценариях.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>');

Вывод списка объектов с определенным префиксом имени BLOB-объекта

В этом примере показано, как перечислить все существующие большие двоичные объекты в контейнере <container_name> учетной записи <account_name>хранения, имя большого двоичного объекта которого начинается с <blob_name_prefix>.

<blob_name_prefix> необходимо задать любое префикс, которое необходимо, чтобы большие двоичные объекты, перечисленные в их именах. Если вы хотите вернуть все большие двоичные объекты, можно задать для этого параметра пустую строку или даже не указать значение для этого параметра, в этом случае значение по умолчанию используется для пустой строки.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>','<blob_name_prefix>');

Кроме того, можно использовать следующий синтаксис:

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE '<blob_name_prefix>%';

Чтение содержимого из большого двоичного объекта в контейнере

Функция blob_get извлекает содержимое одного конкретного большого двоичного объекта (events.csvв данном случае) в контейнере <account_name> хранилища, который ссылается<container_name>. Чтобы blob_get узнать, как проанализировать данные, которые можно передать в форме NULL::table_name, где table_name ссылается на таблицу, схема которой соответствует считываемой большой двоичный объект. В примере она ссылается на таблицу events , созданную в самом начале.

<blob_name> необходимо задать полный путь к большому двоичному объекту, содержимое которого требуется прочитать.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
LIMIT 5;

Кроме того, можно явно определить схему результата с помощью AS предложения после функции blob_get .

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','events.csv.gz')
AS res (
         event_id BIGINT
        ,event_type TEXT
        ,event_public BOOLEAN
        ,repo_id BIGINT
        ,payload JSONB
        ,repo JSONB
        ,user_id BIGINT
        ,org JSONB
        ,created_at TIMESTAMP WITHOUT TIME ZONE)
LIMIT 5;

Использование параметра декодировщика

В этом примере показано использование decoder параметра. Обычно формат выводится из расширения файла, но если содержимое файла не имеет соответствующего расширения, можно передать аргумент декодера.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_blob_without_extension'
        , NULL::events
        , decoder := 'csv')
LIMIT 5;

Использование сжатия с параметром декодатора

В этом примере показано, как применить сжатие gzip для сжатого большого двоичного объекта gzip, имя которого не заканчивается расширением .gz.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_compressed'
        , NULL::events
        , decoder := 'csv'
        , compression := 'gzip')
LIMIT 5;

Импорт отфильтрованного содержимого и изменение перед загрузкой из объекта формата CSV

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

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Запрос содержимого из файла с заголовками, настраиваемыми разделителями, escape-символами

В этом примере показано, как использовать пользовательские разделители и escape-символы, передав результат options_copy аргументу options .

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Запрос агрегирования по содержимому большого двоичного объекта

В этом примере показано, как выполнять операции агрегирования по данным, хранящимся в контейнере БОЛЬШИХ двоичных объектов, без необходимости импортировать содержимое большого двоичного объекта в таблицы PostgreSQL.

SELECT event_type, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Импорт данных с помощью инструкции COPY

В следующем примере показано импорт данных из большого двоичного объекта, который находится в контейнере BLOB-объектов events.csv в учетной записи <account_name>служба хранилища Azure, с помощью COPY команды:<container_name>

Создайте таблицу, которая соответствует схеме исходного файла:

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Используйте инструкцию для копирования данных в целевую COPY таблицу. Укажите, что первая строка содержит заголовки столбцов.
```
COPY events
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/events.csv'
WITH (FORMAT 'csv', header);
```

Запись содержимого в большой двоичный объект в контейнере

Функция blob_put состоит из содержимого одного конкретного большого двоичного объекта (eventscopy.csv в данном случае) и отправляет его в указанный контейнер <container_name> <account_name> хранилища. В этом примере используется blob_get для создания набора из пяти строк, которые затем передаются blob_put в агрегатную функцию, которая отправляет их в виде большого двоичного объекта с именем eventscopy.csv.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'eventscopy.csv'
        , top_5_events)
FROM (SELECT * FROM azure_storage.blob_get
                     ('<account_name>'
                     ,'<container_name>'
                     ,'events.csv'
                     , NULL::events) LIMIT 5) AS top_5_events;

Экспорт данных с помощью инструкции COPY

В следующем примере показано экспорт данных из таблицыevents, вызываемой COPY в большой двоичный объектevents_exported.csv, который находится в контейнере <container_name> BLOB-объектов в учетной записи <account_name>служба хранилища Azure, с помощью команды:

Создайте таблицу, которая соответствует схеме исходного файла:

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Загрузите данные в таблицу. Выполните инструкции INSERT для заполнения несколькими синтетическими строками или используйте данные импорта с помощью примера инструкции COPY, чтобы заполнить его содержимым примера набора данных.
Используйте инструкцию для копирования данных в целевую COPY таблицу. Укажите, что первая строка содержит заголовки столбцов.
```
COPY events
TO 'https://<account_name>.blob.core.windows.net/<container_name>/events_exported.csv'
WITH (FORMAT 'csv', header);
```

Поделиться через

Импорт и экспорт данных с помощью расширения azure_storage в База данных Azure для PostgreSQL — гибкий сервер

Обзор процедуры

Использование авторизации с идентификатором Microsoft Entra

Использование авторизации с общим ключом

Функции

azure_storage.account_add

Разрешения

Аргументы

account_name_p

account_key_p

account_config

Возвращаемый тип

azure_storage.account_options_managed_identity

Разрешения

Аргументы

name

type

Возвращаемый тип

azure_storage.account_options_credentials

Разрешения

Аргументы

name

учетные данные

type

Возвращаемый тип

azure_storage.account_options

Разрешения

Аргументы

name

auth_type

storage_type

учетные данные

Возвращаемый тип

azure_storage.account_remove

Разрешения

Аргументы

account_name_p

Возвращаемый тип

azure_storage.account_user_add

Разрешения

Аргументы

account_name_p

user_p

Возвращаемый тип

azure_storage.account_user_remove

Разрешения

Аргументы

account_name_p

user_p

Возвращаемый тип

azure_storage.account_list

Разрешения

Аргументы

Возвращаемый тип

azure_storage.blob_list

Разрешения

Аргументы

account_name

container_name

prefix

Возвращаемый тип

path

байт

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Разрешения

Аргументы

account_name

container_name

path

rec

дешифратор

compression

options

Возвращаемый тип