Importación y exportación de datos mediante azure_storage extensión en Azure Database for PostgreSQL: servidor flexible

Artículo
11/19/2024

SE APLICA A: Azure Database for PostgreSQL con servidor flexible

La extensión azure_storage permite importar o exportar datos en varios formatos de archivo, directamente entre las cuentas de Azure Storage y una instancia del servidor flexible de Azure Database for PostgreSQL.

Puede encontrar ejemplos de exportación e importación de datos mediante esta extensión en la sección Ejemplos de este artículo.

Para usar la extensión en la azure_storage instancia de servidor flexible de Azure Database for PostgreSQL, debe agregar la extensión a shared_preload_librariesy también agregarla al azure.extensions parámetro de servidor, como se describe en cómo usar extensiones de PostgreSQL.

Dado shared_preload_library que es un parámetro de servidor estático, requiere un reinicio del servidor para que el cambio surta efecto.

Una vez reiniciado el servidor, conéctese a la instancia de PostgreSQL mediante el cliente de su preferencia (por ejemplo, psql, pgAdmin, etc.). Confirme que SHOW azure.extensions;, y SHOW shared_preload_libraries;, incluyan el valor azure_storage en la lista de los valores separados por comas devueltos por cada una de las SHOW instrucciones .

Solo puede instalar la extensión, mediante la conexión a la base de datos de destino y la ejecución de la instrucción CREATE EXTENSION . Debe repetir el comando por separado para cada base de datos en la que desea que la extensión esté disponible.

CREATE EXTENSION azure_storage;

Información general del procedimiento

Identifique las cuentas de Azure Storage con las que desea que los usuarios de la azure_storage extensión interactúen.
Decida qué tipo de autorización desea usar para las solicitudes realizadas en el servicio de blobs de cada una de esas cuentas de Azure Storage. azure_storage la extensión admite la autorización con clave compartida y la autorización con el identificador de Microsoft Entra. De estos dos tipos de autorización, Microsoft Entra ID proporciona una seguridad superior y facilidad de uso en clave compartida, y es la que Microsoft recomienda. Para cumplir los requisitos previos necesarios en cada caso, siga las instrucciones de las secciones correspondientes:
- Autorización con el identificador de Entra de Microsoft o
- Autorización con clave compartida.
Incluya azure_storage en shared_preload_libraries:

Dado que shared_preload_libraries es estático, el servidor debe reiniciarse para que un cambio surta efecto:

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)

Dado que shared_preload_libraries es estático, el servidor debe reiniciarse para que un cambio surta efecto:

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

Incluya azure_storage en 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)

Con el cliente de su preferencia (por ejemplo, psql, pgAdmin, etc.), conéctese a cualquier base de datos de su instancia de Servidor flexible de Azure Database for PostgreSQL. Para crear todos los objetos SQL (tablas, tipos, funciones, vistas, etc.) con los que puede usar la azure_storage extensión para interactuar con instancias de cuentas de Azure Storage, ejecute la siguiente instrucción:
```
CREATE EXTENSION azure_storage;
```
Con las azure_storage.account_* funciones, agregue referencias a cuentas de Azure Storage a las que desea permitir que los usuarios o roles de PostgreSQL accedan con la azure_storage extensión. Estas referencias incluyen el nombre de la cuenta de Azure Storage a la que se hace referencia y el tipo de autenticación que se va a usar al interactuar con la cuenta de Azure Storage. Según el tipo de autenticación seleccionado, es posible que también necesite proporcionar otros parámetros, como la clave de acceso de la cuenta de Azure Storage o el token de SAS.

Importante

Para los tipos de autenticación para los que debe proporcionar una clave de acceso de la cuenta de Azure Storage, tenga en cuenta que las claves de acceso de Azure Storage son similares a una contraseña raíz para la cuenta de almacenamiento. Siempre tenga cuidado de protegerlos. Use Azure Key Vault para administrar y rotar las claves de forma segura. azure_storage la extensión almacena esas claves en una tabla azure_storage.accounts que los miembros del pg_read_all_data rol pueden leer.

Los usuarios concedidos al azure_storage_admin rol pueden interactuar con la azure_storage.accounts tabla mediante las siguientes funciones:

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

El azure_storage_admin rol es, de forma predeterminada, concedido al azure_pg_admin rol.

Para usar la autorización con el identificador de Entra de Microsoft

Habilite la identidad administrada asignada por el sistema en la instancia del servidor flexible de Azure Database for 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"}}'

Reinicie la instancia del servidor flexible de Azure Database for PostgreSQL después de habilitar una identidad administrada asignada por el sistema.
Asigne permisos de control de acceso basado en rol (RBAC) para el acceso a datos de blobs, en la cuenta de Azure Storage, a la identidad administrada asignada por el sistema de la instancia de Azure Database for PostgreSQL con servidor flexible.

Para usar la autorización con clave compartida

La cuenta de Azure Storage debe tener habilitada la opción Permitir el acceso a la clave de la cuenta de almacenamiento (es decir, no puede tener la propiedad AllowSharedKeyAccess establecida en false).

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

Para pasarla a la función azure_storage.account_add , capture cualquiera de las dos claves de acceso de la cuenta de Azure Storage.

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

Funciones

azure_storage.account_add

Función que permite agregar una cuenta de almacenamiento y su clave de acceso asociada a la lista de cuentas de almacenamiento a las que puede acceder la azure_storage extensión.

Si una invocación anterior de esta función ya ha agregado la referencia a esta cuenta de almacenamiento, no agrega una nueva entrada, sino que actualiza la clave de acceso de la entrada existente.

Nota:

Esta función no valida si el nombre de cuenta al que se hace referencia existe o si es accesible con la clave de acceso proporcionada. Sin embargo, valida que el nombre de la cuenta de almacenamiento es válido, según las reglas de validación de nomenclatura impuestas en las cuentas de almacenamiento de Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

Hay una versión sobrecargada de esta función, que acepta un account_config parámetro que encapsula el nombre de la cuenta de Azure Storage a la que se hace referencia y todos los valores necesarios, como el tipo de autenticación, el tipo de cuenta o las credenciales de almacenamiento.

azure_storage.account_add(account_config jsonb);

Permisos

Debe ser miembro de azure_storage_admin.

Argumentos

account_name_p

text el nombre de la cuenta de Azure Blob Storage que contiene todos los objetos: blobs, archivos, colas y tablas. La cuenta de almacenamiento proporciona un espacio de nombres único al que se puede acceder desde cualquier lugar del mundo a través de HTTPS.

account_key_p

text el valor de una de las claves de acceso de la cuenta de almacenamiento. Las claves de acceso de Azure Blob Storage son similares a una contraseña raíz para la cuenta de almacenamiento. Siempre debe proteger las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura. La clave de cuenta se almacena en una tabla a la que solo puede acceder el superusuario. Los usuarios concedidos al azure_storage_admin rol pueden interactuar con esta tabla a través de funciones. Para ver qué cuentas de almacenamiento se agregan, use la función azure_storage.account_list.

account_config

jsonb el nombre de la cuenta de Azure Storage y todos los valores necesarios, como el tipo de autenticación, el tipo de cuenta o las credenciales de almacenamiento. Se recomienda usar las funciones de utilidad azure_storage.account_options_managed_identity, azure_storage.account_options_credentials o azure_storage.account_options para crear cualquiera de los valores válidos que se deben pasar como este argumento.

Tipo de valor devuelto

VOID

azure_storage.account_options_managed_identity

Función que actúa como una función de utilidad, a la que se puede llamar como parámetro dentro de azure_storage.account_add y resulta útil para generar un valor válido para el argumento, cuando se usa una identidad administrada asignada por el account_config sistema para interactuar con la cuenta de Azure Storage.

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

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

nombre

type

azure_storage.storage_type valor de uno de los tipos de almacenamiento admitidos. Solo el valor admitido es blob.

Tipo de valor devuelto

jsonb

azure_storage.account_options_credentials

Función que actúa como una función de utilidad, que se puede llamar como parámetro dentro de azure_storage.account_add, y resulta útil para generar un valor válido para el account_config argumento, cuando se usa una clave de acceso de Azure Storage para interactuar con la cuenta de Azure Storage.

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

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

nombre

credentials

type

azure_storage.storage_type valor de uno de los tipos de almacenamiento admitidos. Solo el valor admitido es blob.

Tipo de valor devuelto

jsonb

azure_storage.account_options

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

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

nombre

auth_type

azure_storage.auth_type valor de uno de los tipos de almacenamiento admitidos. Solo los valores admitidos son access-key, y managed-identity.

storage_type

azure_storage.storage_type valor de uno de los tipos de almacenamiento admitidos. Solo el valor admitido es blob.

credentials

Tipo de valor devuelto

jsonb

azure_storage.account_remove

Función que permite quitar una cuenta de almacenamiento y su clave de acceso asociada de la lista de cuentas de almacenamiento a las que puede acceder la azure_storage extensión.

azure_storage.account_remove(account_name_p text);

Permisos

Debe ser miembro de azure_storage_admin.

Argumentos

account_name_p

Tipo de valor devuelto

VOID

azure_storage.account_user_add

Función que permite conceder a un usuario o rol de PostgreSQL acceso a una cuenta de almacenamiento a través de las funciones proporcionadas por la azure_storage extensión.

Nota:

La ejecución de esta función solo se realiza correctamente si la cuenta de almacenamiento, cuyo nombre se pasa como primer argumento, ya se creó con azure_storage.account_add y si el usuario o rol, cuyo nombre se pasa como segundo argumento, ya existe.

azure_storage.account_add(account_name_p text, user_p regrole);

Permisos

Debe ser miembro de azure_storage_admin.

Argumentos

account_name_p

user_p

regrole el nombre de un usuario o rol de PostgreSQL disponible en el servidor.

Tipo de valor devuelto

VOID

azure_storage.account_user_remove

Función que permite revocar un acceso de usuario o rol de PostgreSQL a una cuenta de almacenamiento a través de las funciones proporcionadas por la azure_storage extensión.

Nota:

La ejecución de esta función solo se realiza correctamente si la cuenta de almacenamiento cuyo nombre se pasa como primer argumento ya se ha creado con azure_storage.account_add y si el usuario o rol cuyo nombre se pasa como segundo argumento todavía existe. Cuando se quita un usuario o rol del servidor, al ejecutar DROP USER | ROLE, también se eliminan automáticamente los permisos concedidos en cualquier referencia a cuentas de Azure Storage.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Permisos

Debe ser miembro de azure_storage_admin.

Argumentos

account_name_p

user_p

regrole el nombre de un usuario o rol de PostgreSQL disponible en el servidor.

Tipo de valor devuelto

VOID

azure_storage.account_list

Función que enumera los nombres de las cuentas de almacenamiento configuradas a través de la función azure_storage.account_add , junto con los usuarios o roles de PostgreSQL a los que se conceden permisos para interactuar con esa cuenta de almacenamiento a través de las funciones proporcionadas por la azure_storage extensión.

azure_storage.account_list();

Permisos

Debe ser miembro de azure_storage_admin.

Argumentos

Esta función no toma ningún argumento.

Tipo de valor devuelto

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[]) una tabla de cuatro columnas con la lista de cuentas de Azure Storage agregadas, el tipo de autenticación que se usa para interactuar con cada cuenta, el tipo de almacenamiento y la lista de usuarios o roles de PostgreSQL a los que se le concede acceso.

azure_storage.blob_list

Función que enumera los nombres y otras propiedades (size, lastModified, eTag, contentType, contentEncoding y contentHash) de blobs almacenados en el contenedor especificado de la cuenta de almacenamiento a la que se hace referencia.

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

Permisos

El usuario o el rol que invoca esta función se deben agregar a la lista de permitidos para la account_name referencia, ejecutando azure_storage.account_user_add. Los miembros de pueden hacer referencia automáticamente a todas las cuentas de azure_storage_admin Azure Storage cuyas referencias se agregaron mediante azure_storage.account_add.

Argumentos

account_name

container_name

text el nombre de un contenedor. Un contenedor organiza un conjunto de blobs, de forma parecida a un directorio en un sistema de archivos. Una cuenta de almacenamiento puede contener un número ilimitado de contenedores y un contenedor puede almacenar un número ilimitado de blobs. Un nombre de contenedor debe ser un nombre válido del sistema de nombres de dominio (DNS), ya que forma parte del URI único que se usa para abordar el contenedor o sus blobs. Al asignar un nombre a un contenedor, asegúrese de seguir estas reglas.

El identificador URI de un contenedor es similar a: https://myaccount.blob.core.windows.net/mycontainer

prefix

text cuando se especifica, la función devuelve los blobs cuyos nombres comienzan por el valor proporcionado en este parámetro. El valor predeterminado es una cadena vacía.

Tipo de valor devuelto

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) una tabla con un registro por blob devuelto, incluido el nombre completo del blob y otras propiedades.

path

text el nombre completo del blob.

bytes

bigint el tamaño del blob en bytes.

last_modified

timestamp with time zonefecha y hora en que se modificó por última vez el blob. Cualquier operación que modifique el blob, incluida una actualización de los metadatos o las propiedades del blob, cambia la hora de la última modificación del blob.

ETag

text La propiedad ETag se usa para la simultaneidad optimista durante las actualizaciones. No es una marca de tiempo, ya que hay otra propiedad denominada Marca de tiempo que almacena la última vez que se actualizó un registro. Por ejemplo, si carga una entidad y quiere actualizarla, la etiqueta ETag debe coincidir con lo que está almacenado actualmente. Establecer la etiqueta ETag adecuada es importante porque, si tiene varios usuarios editando el mismo elemento, no querrá que sobrescriban los cambios entre sí.

content_type

text el tipo de contenido especificado para el blob. El tipo de contenido predeterminado es application/octet-stream.

content_encoding

text la propiedad Content-Encoding de un blob que Azure Storage permite definir. En el caso del contenido comprimido, podría establecer la propiedad como Gzip. Cuando el explorador accede al contenido, descomprime automáticamente el contenido.

content_hash

text hash usado para comprobar la integridad del blob durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento comprueba el hash proporcionado con un calculado a partir del contenido. Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta).

azure_storage.blob_get

Función que permite importar datos. Descarga uno o varios archivos de un contenedor de blobs en una cuenta de Azure Storage. A continuación, traduce el contenido en filas, que se pueden consumir y procesar con construcciones de lenguaje SQL. Esta función agrega compatibilidad para filtrar y manipular los datos capturados desde el contenedor de blobs antes de importarlos.

Nota:

Antes de intentar acceder al contenedor de la cuenta de almacenamiento a la que se hace referencia, esta función comprueba si los nombres de la cuenta de almacenamiento y el contenedor pasados como argumentos son válidos según las reglas de validación de nomenclatura impuestas en las cuentas de almacenamiento de Azure. Si alguno de ellos no es válido, se genera un error.

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);

Hay una versión sobrecargada de esta función, que acepta un rec parámetro que permite definir convenientemente el registro de formato de salida.

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);

Permisos

Argumentos

account_name

container_name

El identificador URI de un contenedor es similar a: https://myaccount.blob.core.windows.net/mycontainer

path

text el nombre completo del blob.

rec

anyelement la definición de la estructura de salida del registro.

decodificador

text la especificación del formato de blob. Se puede establecer en cualquiera de los siguientes valores:

Format	Valor predeterminado	Descripción
`auto`	`true`	Deduce el valor en función de la última serie de caracteres asignados al nombre del blob. Si el nombre del blob termina con `.csv` o `.csv.gz`, se supone `csv`que . Si termina con `.tsv` o `.tsv.gz`, se supone `tsv`que . Si termina con `.json`, `.json.gz`, `.xml`, `.xml.gz`, `.txt`o `.txt.gz`, asume `text`.
`csv`		Formato de valores separados por comas usado por POSTGRESQL COPY.
`tsv`		Valores separados por tabulaciones, el formato COPY predeterminado de PostgreSQL.
`binary`		Formato COPY de PostgreSQL binario.
`text` \| `xml` \| `json`		Un archivo que contiene un valor de texto único.

compression

text la especificación del tipo de compresión. Se puede establecer en cualquiera de los siguientes valores:

Format	Valor predeterminado	Descripción
`auto`	`true`	Deduce el valor en función de la última serie de caracteres asignados al nombre del blob. Si el nombre del blob termina con `.gz`, se supone `gzip`que . De lo contrario, se supone `none`que .
`gzip`		Fuerza el uso del descodificador gzip para descomprimir el blob.
`none`		Fuerza a tratar el blob como uno que no requiere descompresión.

La extensión no admite ningún otro tipo de compresión.

options

jsonb la configuración que define el control de encabezados personalizados, separadores personalizados, caracteres de escape, etc. options afecta al comportamiento de esta función de forma similar a la forma en que las opciones que puede pasar al COPY comando en PostgreSQL afectan a su comportamiento.

Tipo de valor devuelto

SETOF record SETOF anyelement

azure_storage.blob_put

Función que permite exportar datos mediante la carga de archivos en un contenedor de blobs en una cuenta de Azure Storage. El contenido de los archivos se genera a partir de filas de PostgreSQL.

Nota:

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

Hay una versión sobrecargada de la función, que contiene encoder el parámetro que permite especificar el codificador que se va a usar cuando no se puede deducir de la extensión del path parámetro, o cuando se quiere invalidar el que se deduce.

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

Hay una versión sobrecargada de función que también contiene un compression parámetro que permite especificar la compresión que se va a usar cuando no se puede deducir de la extensión del path parámetro, o cuando se quiere invalidar la que se deduce.

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

Hay una versión sobrecargada de la función que también contiene un options parámetro para controlar encabezados personalizados, separadores personalizados, caracteres de escape, etc. options funciona de forma similar a las opciones que se pueden pasar al COPY comando en PostgreSQL.

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

Permisos

Argumentos

account_name

container_name

El identificador URI de un contenedor es similar a: https://myaccount.blob.core.windows.net/mycontainer

path

text el nombre completo del blob.

tuple

record la definición de la estructura de salida del registro.

codificador

text la especificación del formato de blob. Se puede establecer en cualquiera de los siguientes valores:

Format	Valor predeterminado	Descripción
`auto`	`true`	Deduce el valor en función de la última serie de caracteres asignados al nombre del blob. Si el nombre del blob termina con `.csv` o `.csv.gz`, se supone `csv`que . Si termina con `.tsv` o `.tsv.gz`, se supone `tsv`que . Si termina con `.json`, `.json.gz`, `.xml`, `.xml.gz`, `.txt`o `.txt.gz`, asume `text`.
`csv`		Formato de valores separados por comas usado por POSTGRESQL COPY.
`tsv`		Valores separados por tabulaciones, el formato COPY predeterminado de PostgreSQL.
`binary`		Formato COPY de PostgreSQL binario.
`text` \| `xml` \| `json`		Un archivo que contiene un valor de texto único.

compression

text la especificación del tipo de compresión. Se puede establecer en cualquiera de los siguientes valores:

Format	Valor predeterminado	Descripción
`auto`	`true`	Deduce el valor en función de la última serie de caracteres asignados al nombre del blob. Si el nombre del blob termina con `.gz`, se supone `gzip`que . De lo contrario, se supone `none`que .
`gzip`		Fuerza el uso del descodificador gzip para descomprimir el blob.
`none`		Fuerza a tratar el blob como uno que no requiere descompresión.

La extensión no admite ningún otro tipo de compresión.

options

Tipo de valor devuelto

VOID

azure_storage.options_csv_get

Función que actúa como una función de utilidad, que se puede llamar como parámetro dentro blob_getde y es útil para descodificar el contenido de un archivo 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);

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

delimiter

text carácter que separa las columnas dentro de cada fila (línea) del archivo. Debe ser un solo carácter de 1 byte. Aunque esta función admite delimitadores de cualquier número de caracteres, si intenta usar más de un solo carácter de 1 byte, PostgreSQL notifica un COPY delimiter must be a single one-byte character error.

null_string

text cadena que representa un valor NULL. El valor predeterminado es \N (barra diagonal inversa-N) en formato de texto y una cadena vacía sin comillas en formato CSV. Es posible que prefiera una cadena vacía incluso en formato de texto para los casos en los que no desea distinguir valores nulos de cadenas vacías.

boolean marca que indica si el archivo contiene una línea de encabezado con los nombres de cada columna del archivo. En la salida, la línea inicial contiene los nombres de columna de la tabla.

comillas

text carácter de comillas que se va a usar cuando se cita un valor de datos. El valor predeterminado es comillas dobles. Debe ser un solo carácter de 1 byte. Aunque esta función admite delimitadores de cualquier número de caracteres, si intenta usar más de un solo carácter de 1 byte, PostgreSQL notifica un COPY quote must be a single one-byte character error.

escape

text carácter que debe aparecer antes de un carácter de datos que coincida con el valor QUOTE. El valor predeterminado es el mismo que el valor QUOTE (por lo que el carácter de comillas se duplica si aparece en los datos). Debe ser un solo carácter de 1 byte. Aunque esta función admite delimitadores de cualquier número de caracteres, si intenta usar más de un solo carácter de 1 byte, PostgreSQL notifica un COPY escape must be a single one-byte character error.

force_not_null

text[] no coincidan con los valores de las columnas especificadas en la cadena null. En el caso predeterminado en el que la cadena nula esté vacía, esto significa que los valores vacíos se leen como cadenas de longitud cero en lugar de valores nulos, incluso cuando no están entre comillas.

force_null

text[] coincide con los valores de las columnas especificadas con la cadena null, incluso si se cita y, si se encuentra una coincidencia, establezca el valor en NULL. En el caso predeterminado en el que la cadena nula esté vacía, convierte una cadena vacía entre comillas en un valor nulo.

content_encoding

text nombre de la codificación con la que se codifica el archivo. Si se omite la opción, se usa la codificación del cliente actual.

Tipo de valor devuelto

jsonb

azure_storage.options_copy

Función que actúa como una función de utilidad, a la que se puede llamar como parámetro dentro de blob_get. Actúa como una función auxiliar para options_csv_get, options_tsv y 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);

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

delimiter

null_string

autorización

boolean marca que indica si el archivo contiene una línea de encabezado con los nombres de cada columna del archivo. En la salida, la línea inicial contiene los nombres de columna de la tabla.

comillas

escape

force_quote

text[] obliga a que se usen comillas para todos los valores que no sean NULL en cada columna especificada. La salida nula nunca se pone entre comillas. Si se especifica *, los valores que no son nulos se citan en todas las columnas.

force_not_null

force_null

content_encoding

text nombre de la codificación con la que se codifica el archivo. Si se omite la opción, se usa la codificación del cliente actual.

Tipo de valor devuelto

jsonb

azure_storage.options_tsv

Función que actúa como una función de utilidad, a la que se puede llamar como parámetro dentro blob_getde y es útil para descodificar el contenido de un archivo tsv.

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

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

delimiter

null_string

content_encoding

text nombre de la codificación con la que se codifica el archivo. Si se omite la opción, se usa la codificación del cliente actual.

Tipo de valor devuelto

jsonb

azure_storage.options_binary

Función que actúa como una función de utilidad, que se puede llamar como parámetro dentro blob_getde y es útil para descodificar el contenido de un archivo binario.

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

Permisos

Cualquier usuario o rol puede invocar esta función.

Argumentos

content_encoding

text nombre de la codificación con la que se codifica el archivo. Si se omite la opción, se usa la codificación del cliente actual.

Tipo de valor devuelto

jsonb

Errores posibles

ERROR: azure_storage: El permiso no es suficiente para realizar la operación solicitada

Al ejecutar cualquiera de las funciones que interactúan con Azure Storage (azure_storage.blob_listo azure_storage.blob_get azure_storage.blob_put) y a la identidad administrada asignada por el sistema no se le conceden los roles o permisos adecuados del plano de datos (normalmente un mínimo de colaborador de datos de Storage Blob para azure_storage.blob_put y un mínimo de Lector de datos de Storage Blob para las otras dos funciones).

También puede ser el caso de que ya haya concedido los permisos mínimos necesarios, pero aún no están en vigor. Estos permisos pueden tardar unos minutos hasta que se propaguen esos permisos.

ERROR: azure_storage: faltan credenciales de almacenamiento

Al ejecutar cualquiera de las funciones que interactúan con Azure Storage (azure_storage.blob_listo azure_storage.blob_get azure_storage.blob_put) y las credenciales con las que desea que la extensión se autentique con la cuenta de almacenamiento no se registran mediante azure_storage.account_add.

ERROR: azure_storage: error interno al conectarse

Cuando la identidad administrada asignada por el sistema no está habilitada en la instancia de servidor flexible.

ERROR: azure_storage: formato no válido de credenciales de almacenamiento

Cuando la identidad administrada asignada por el sistema está habilitada en la instancia de servidor flexible, pero el servidor no se ha reiniciado después de habilitarla.

ERROR: azure_storage: no se permite que el usuario <actual user_or_role> use la cuenta <de almacenamiento storage_account>

Al ejecutar cualquiera de las funciones que interactúan con Azure Storage (azure_storage.blob_listo azure_storage.blob_get azure_storage.blob_put) con un usuario o rol que no es miembro de azure_storage_admin y no se conceden permisos, mediante azure_storage.account_user_add, para usar la cuenta de almacenamiento a la que se hace referencia.

Ejemplos

Debe cumplir los siguientes requisitos previos para poder ejecutar los ejemplos siguientes:

Cree una cuenta de Azure Storage. Para crear una cuenta de Azure Storage, si aún no tiene una, personalice los valores de <resource_group>, <location>, <storage_account>y , y <blob_container>ejecute el siguiente comando de la CLI de Azure:

resource_group=<resource_group>
location=<location>
storage_account=<storage_account>
blob_container=<blob_container>
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

Cree un contenedor de blobs. Para crear el contenedor de blobs, ejecute la SIGUIENTE CLI de Azure:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Capture una de las dos claves de acceso asignadas a la cuenta de almacenamiento. Asegúrese de copiar el valor de la access_key según sea necesario pasarlo como argumento para azure_storage.account_add en un paso posterior. Para capturar el primero de las dos claves de acceso, ejecute el siguiente comando de la CLI de Azure:
```
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
```

Descargue el archivo con el conjunto de datos que se usa durante los ejemplos y cárguelo en el contenedor de blobs. Para descargar el archivo con el conjunto de datos, ejecute el siguiente comando de la CLI de Azure:

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

Nota:

Puede enumerar contenedores o blobs almacenados en ellos para una cuenta de almacenamiento específica, pero solo si el usuario o rol de PostgreSQL tiene permiso en la referencia a esa cuenta de almacenamiento mediante azure_storage.account_user_add. A los miembros del azure_storage_admin rol se les concede este privilegio sobre todas las cuentas de Azure Storage que se han agregado mediante azure_storage.account_add. De forma predeterminada, solo a los miembros de azure_pg_admin se les concede el azure_storage_admin rol.

Creación de una tabla en la que se cargan los datos

Vamos a crear la tabla en la que se importa el contenido del archivo CSV que hemos cargado en la cuenta de almacenamiento. Para ello, conéctese a la instancia del servidor flexible de Azure Database for PostgreSQL mediante PgAdmin, psqlo el cliente de su preferencia y ejecute la siguiente instrucción:

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
        );

Adición de la clave de acceso de la cuenta de almacenamiento

En este ejemplo se muestra cómo agregar una referencia a una cuenta de almacenamiento, junto con la clave de acceso de esa cuenta de almacenamiento necesaria para acceder a su contenido a través de la funcionalidad proporcionada por la extensión en la azure_storage instancia del servidor flexible de Azure Database for PostgreSQL.

<storage_account> debe establecerse en el nombre de la cuenta de almacenamiento. Si usó los scripts anteriores, este valor debe coincidir con el valor establecido en la variable de entorno storage_account en esos scripts.

Del mismo modo, <access_key> debe establecerse en el valor que ha capturado de la cuenta de almacenamiento.

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

Sugerencia

Si desea recuperar el nombre de la cuenta de almacenamiento y una de sus claves de acceso desde Azure Portal, busque la cuenta de almacenamiento; en el menú de recursos, seleccione Claves de acceso, copie el nombre de la cuenta de almacenamiento y copie la sección Clave de key1 (tiene que seleccionar Mostrar junto a la clave en primer lugar).

Eliminación de la referencia a la cuenta de almacenamiento

En este ejemplo se muestra cómo quitar cualquier referencia a una cuenta de almacenamiento para que ningún usuario de la base de datos actual pueda usar la azure_storage funcionalidad de extensión para acceder a esa cuenta de almacenamiento.

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

Concesión de acceso a un usuario o rol en la referencia de Azure Blob Storage

En este ejemplo se muestra cómo conceder acceso a un usuario o rol denominado <regular_user>, de modo que dicho usuario de PostgreSQL pueda usar la azure_storage extensión para acceder a los blobs almacenados en contenedores hospedados por la cuenta de almacenamiento de Azure a la que se hace referencia.

<regular_user> debe establecerse en el nombre de un usuario o rol existente.

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

Enumeración de todas las referencias a cuentas de Azure Storage

En este ejemplo se muestra cómo averiguar a qué cuentas de almacenamiento de Azure puede hacer referencia la azure_storage extensión en esta base de datos, junto con el tipo de autenticación que se usa para acceder a cada cuenta de almacenamiento y a qué usuarios o roles se les concede permiso, a través de la función azure_storage.account_user_add , para acceder a esa cuenta de almacenamiento de Azure a través de la funcionalidad proporcionada por la extensión.

SELECT * FROM azure_storage.account_list();

Revocación del acceso de un usuario o rol en la referencia de Azure Blob Storage

En este ejemplo se muestra cómo revocar el acceso de un usuario o rol denominado <regular_user>, de modo que dicho usuario de PostgreSQL no pueda usar la azure_storage extensión para acceder a los blobs almacenados en contenedores hospedados por la cuenta de almacenamiento de Azure a la que se hace referencia.

<regular_user> debe establecerse en el nombre de un usuario o rol existente.

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

Enumeración de todos los blobs de un contenedor

En este ejemplo se muestra cómo enumerar todos los blobs existentes dentro del contenedor <container_name> de la cuenta <storage_account>de almacenamiento .

<blob_container> debe establecerse en el nombre del contenedor de blobs. Si usó los scripts anteriores, este valor debe coincidir con el valor establecido en la variable de entorno blob_container en esos scripts.

SELECT * FROM azure_storage.blob_list('<storage_account>','<blob_container>');

Enumeración de los objetos con prefijo de nombre de blob específico

En este ejemplo se muestra cómo enumerar todos los blobs existentes dentro del contenedor <blob_container> de la cuenta <storage_account>de almacenamiento , cuyo nombre de blob comienza por <blob_name_prefix>.

<blob_name_prefix> debe establecerse en el prefijo que desee que los blobs enumerados incluyan en sus nombres. Si desea devolver todos los blobs, puede establecer este parámetro en una cadena vacía o incluso no especificar un valor para este parámetro, en cuyo caso el valor predeterminado es una cadena vacía.

SELECT * FROM azure_storage.blob_list('<storage_account>','<blob_container>','<blob_name_prefix>');

Como alternativa, puede usar la sintaxis siguiente:

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

Leer contenido de un blob en un contenedor

La blob_get función recupera el contenido de un blob específico (events.csv en este caso), en el contenedor <blob_container> al que se hace referencia del <storage_account> almacenamiento. Para blob_get saber cómo analizar los datos, puede pasar un valor en el formulario NULL::table_name, donde table_name hace referencia a una tabla cuyo esquema coincide con el del blob que se lee. En el ejemplo, hace referencia a la events tabla que creamos al principio.

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

Como alternativa, puede definir explícitamente el esquema del resultado mediante la AS cláusula después de la función blob_get .

SELECT * FROM azure_storage.blob_get('<storage_account>','<blob_container>','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;

Uso de la opción de descodificador

En este ejemplo se muestra el uso de la decoder opción . Por lo general, el formato se deduce de la extensión del archivo, pero, cuando el contenido del archivo no tiene una extensión coincidente, puede pasar el argumento de descodificador.

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

Uso de la compresión con la opción de descodificador

En este ejemplo se muestra cómo aplicar el uso de la compresión gzip en un blob comprimido gzip cuyo nombre no termina con una extensión de .gz.

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

Importación de contenido filtrado y modificación antes de cargar desde el objeto de formato CSV

En este ejemplo se muestra la posibilidad de filtrar y modificar el contenido importado desde el blob, antes de cargarlo en una tabla SQL.

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

Consulta del contenido del archivo con encabezados, separadores personalizados, caracteres de escape

En este ejemplo se muestra cómo se pueden usar separadores personalizados y caracteres de escape, pasando el resultado de options_copy al options argumento .

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

Consulta de agregación sobre el contenido de un blob

En este ejemplo se muestra cómo puede realizar operaciones de agregación sobre información almacenada en un contenedor de blobs, sin necesidad de importar el contenido del blob en tablas de PostgreSQL.

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

Importación de datos mediante una instrucción COPY

En el ejemplo siguiente se muestra la importación de datos de un blob llamado events.csv que reside en el contenedor <blob_container> de blobs de la cuenta <storage_account>de Azure Storage mediante el COPY comando :

Cree una tabla que coincida con el esquema del archivo de origen:

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
        );

Use una instrucción COPY para copiar datos en la tabla de destino. Especifique que la primera fila contiene encabezados de columna.
```
COPY events
FROM 'https://<storage_account>.blob.core.windows.net/<blob_container>/events.csv'
WITH (FORMAT 'csv', header);
```

Escribir contenido en un blob en un contenedor

La blob_put función compone el contenido de un blob específico (eventscopy.csv en este caso) y lo carga en el contenedor <blob_container> al que se hace referencia del <storage_account> almacenamiento. En este ejemplo se usa blob_get para construir un conjunto de cinco filas, que luego se pasan a la blob_put función de agregado que las carga como un blob denominado eventscopy.csv.

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

Exportación de datos mediante una instrucción COPY

En el ejemplo siguiente se muestra la exportación de datos de una tabla denominada events, a un blob llamado events_exported.csv que reside en el contenedor <blob_container> de blobs de la cuenta <storage_account>de Azure Storage, mediante el COPY comando :

Cree una tabla que coincida con el esquema del archivo de origen:

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
        );

Cargue los datos en la tabla. Ejecute instrucciones INSERT para rellenarla con varias filas sintéticas o use los datos de importación mediante un ejemplo de instrucción COPY para rellenarlo con el contenido del conjunto de datos de ejemplo.

Use una instrucción COPY para copiar datos en la tabla de destino. Especifique que la primera fila contiene encabezados de columna.

COPY events
TO 'https://<storage_account>.blob.core.windows.net/<blob_container>/events_exported.csv'
WITH (FORMAT 'csv', header);

Comparta sugerencias y errores con el equipo de producto de Azure Database for PostgreSQL.

Compartir a través de

Importación y exportación de datos mediante azure_storage extensión en Azure Database for PostgreSQL: servidor flexible

Información general del procedimiento

Para usar la autorización con el identificador de Entra de Microsoft

Para usar la autorización con clave compartida

Funciones

azure_storage.account_add

Permisos

Argumentos

account_name_p

account_key_p

account_config

Tipo de valor devuelto

azure_storage.account_options_managed_identity

Permisos

Argumentos

nombre

type

Tipo de valor devuelto

azure_storage.account_options_credentials

Permisos

Argumentos

nombre

credentials

type

Tipo de valor devuelto

azure_storage.account_options

Permisos

Argumentos

nombre

auth_type

storage_type

credentials

Tipo de valor devuelto

azure_storage.account_remove

Permisos

Argumentos

account_name_p

Tipo de valor devuelto

azure_storage.account_user_add

Permisos

Argumentos

account_name_p

user_p

Tipo de valor devuelto

azure_storage.account_user_remove

Permisos

Argumentos

account_name_p

user_p

Tipo de valor devuelto

azure_storage.account_list

Permisos

Argumentos

Tipo de valor devuelto

azure_storage.blob_list

Permisos

Argumentos

account_name

container_name

prefix

Tipo de valor devuelto

path

bytes

last_modified

ETag

content_type

content_encoding

content_hash

azure_storage.blob_get

Permisos

Argumentos

account_name

container_name

path

rec

decodificador

compression

options

Tipo de valor devuelto