Ejemplos de inicio rápido para la extensión de Azure Storage en Azure Database for PostgreSQL

A continuación se muestra una lista de ejemplos que le ayudarán a aprender a usar la extensión de Azure Storage.

Creación de una cuenta de Azure Storage y rellenarla con datos

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>, <account_name>y , y <container_name>ejecute el siguiente comando de la CLI de Azure:

random_suffix=$(tr -dc 'a-z0-9' </dev/urandom | head -c8)
resource_group="resource-group-$random_suffix"
location="eastus2"
storage_account="storageaccount$random_suffix"
blob_container="container-$random_suffix"
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
echo "Take note of the storage account name, which you'll have to replace in subsequent examples, whenever you find a reference to <account_name>:"
echo $storage_account
echo "Take note of the container name, which you'll have to replace in subsequent examples, whenever you find a reference to <container_name>:"
echo $blob_container

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 -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.parquet
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.parquet" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/parquet_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "parquet_without_extension" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.csv" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/csv_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "csv_without_extension" --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 se concede permiso al usuario o rol de PostgreSQL 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 de los archivos que hemos cargado en la cuenta de almacenamiento. Para ello, conéctese a la instancia del servidor flexible de Azure Database for PostgreSQL mediante PostgreSQL para Visual Studio Code (versión preliminar),psql, PgAdmin o el cliente de su preferencia y ejecute la siguiente instrucción:

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

Preparación de la extensión para su uso

Antes de continuar, asegúrese de que:

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.

<account_name> 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('<account_name>', '<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).

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('<account_name>', '<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 <account_name>de almacenamiento .

<container_name> 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('<account_name>','<container_name>');

Enumeración de blobs con un prefijo de nombre específico

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

<blob_name_prefix> debe establecerse en el prefijo que quiera 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('<account_name>','<container_name>','<blob_name_prefix>');

Como alternativa, puede usar la sintaxis siguiente:

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

Importación de datos mediante una instrucción COPY FROM

En el ejemplo siguiente se muestra la importación de datos de un blob llamado storage_extension_sample.parquet que reside en el contenedor <container_name> de blobs de la cuenta <account_name>de Azure Storage mediante el COPY comando :

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

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

Use una COPY instrucción para copiar datos en la tabla de destino. El formato se deduce como Parquet de la extensión del archivo.

TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.parquet';

Use una COPY instrucción para copiar datos en la tabla de destino. Dado que el formato de codificación no se puede deducir de la extensión de archivo, se especifica explícitamente a través de la FORMAT opción .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Use una COPY instrucción para copiar datos en la tabla de destino. El formato de codificación se puede deducir de la extensión de archivo. Sin embargo, la presencia de encabezados de columna en la primera fila debe configurarse explícitamente a través HEADERS de la opción .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Ejecute la siguiente SELECT instrucción para confirmar que los datos se cargan en la tabla.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Exportación de datos mediante una instrucción COPY TO

En los ejemplos siguientes se muestra la exportación de datos de una tabla denominada sample_data, a varios blobs con nombres diferentes y características como su formato de codificación, todos los cuales residen en el contenedor <container_name> de blobs de la cuenta <account_name>de Azure Storage, mediante el COPY comando :

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

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

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

Use una COPY instrucción para copiar datos de la tabla de destino. Especifique que el formato de codificación debe ser parquet.

COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.parquet'
WITH (FORMAT 'parquet');

Use una COPY instrucción para copiar datos de la tabla de destino. Especifique que el formato de codificación debe ser CSV y la primera fila del archivo resultante contiene encabezados de columna.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Ejecute la siguiente SELECT instrucción para confirmar que el blob existe en la cuenta de almacenamiento.

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

Leer contenido de un blob

La blob_get función recupera el contenido de un blob específico, en el contenedor <container_name> al que se hace referencia del <account_name> 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 sample_data tabla que creamos al principio.

<blob_name> debe establecerse en la ruta de acceso completa del blob cuyo contenido desea leer.

En este caso, el descodificador que se debe usar para analizar el blob se deduce de la extensión de .parquet archivo.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
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('<account_name>','<container_name>','storage_extension_sample.parquet')
AS res (
        id BIGINT PRIMARY KEY,
        sample_text TEXT,
        sample_integer INTEGER,
        sample_timestamp TIMESTAMP)
LIMIT 5;

Lectura, filtrado y modificación del contenido leído desde un blob

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-',id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
WHERE sample_integer=780
LIMIT 5;

Leer contenido del archivo con opciones personalizadas (encabezados, delimitadores de columna, 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
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.csv'
        ,NULL::sample_data
        ,options := azure_storage.options_csv_get(header := 'true')
        );

Uso de la opción de descodificador

En este ejemplo se muestra el uso de la decoder opción . Cuando la opción de descodificador no está presente, se deduce de la extensión del archivo. Pero cuando el nombre de archivo no tiene una extensión o cuando esa extensión de nombre de archivo no se corresponde con la asociada al descodificador que se debe usar para analizar correctamente el contenido del archivo, puede pasar explícitamente el argumento de descodificador.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'parquet_without_extension'
        , NULL::sample_data
        , decoder := 'parquet')
LIMIT 5;

Proceso de agregaciones 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 sample_integer, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
GROUP BY sample_integer
ORDER BY 2 DESC
LIMIT 5;

Escribir contenido en un blob

La blob_put función compone el contenido de un blob específico (sample_data_copy.parquet en este caso) y lo carga en el contenedor <container_name> al que se hace referencia del <account_name> 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 sample_data_copy.parquet.

El formato de codificación se deduce como parquet, basado en la extensión .parquetde archivo .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.parquet'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

El formato de codificación se deduce como CSV, en función de la extensión .csvde archivo .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.csv'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

No se puede deducir el formato de codificación porque el archivo no tiene una extensión de archivo, por lo que se configura explícitamente como parquet. Además, el algoritmo de compresión se establece en zstd.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_parquet_data_copy_without_extension_with_zstd_compression'
        , top_5_sample_data
        ,'parquet'
        ,'zstd')
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

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.