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

Los ejemplos siguientes le ayudarán a aprender a usar la extensión 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 <container_name> y ejecute el siguiente comando 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 el siguiente comando CLI de Azure:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Obtenga una de las dos claves de acceso asignadas a la cuenta de almacenamiento. Asegúrese de copiar el valor de la clave de acceso según sea necesario pasarlo como argumento para azure_storage.account_add en un paso posterior.

Para obtener la primera de las dos claves de acceso, ejecute el siguiente comando 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 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 agregan 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 van a cargar datos

Cree la tabla en la que se importa el contenido de los archivos que cargó en la cuenta de almacenamiento. Para ello, conéctese a la instancia de Azure Database for PostgreSQL servidor flexible 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. Para acceder al contenido de la cuenta de almacenamiento, la azure_storage extensión de la instancia de Azure Database for PostgreSQL servidor flexible requiere la clave de acceso.

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

Establezca <access_key> en el valor que ha capturado de la cuenta de almacenamiento.

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

Sugerencia

Para recuperar el nombre de la cuenta de almacenamiento y una de sus claves de acceso desde el portal de Azure, 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 clave de la sección key1 . Debe 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>, para que el 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.

Establezca <regular_user> 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 .

Establezca <container_name> en el nombre del contenedor de blobs. Si usó los scripts anteriores, este valor debe coincidir con el valor establecido para la blob_container variable de entorno 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>.

Establezca <blob_name_prefix> en el prefijo que desea que los blobs enumerados incluyan en sus nombres. Si desea devolver todos los blobs, establezca este parámetro en una cadena vacía o no especifique 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 cómo importar datos de un blob denominado storage_extension_sample.parquet que reside en el contenedor <container_name> de blobs de la cuenta <account_name>de Azure Storage . La importación usa 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, especifíquelo explícitamente mediante 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, debe configurar explícitamente la presencia de encabezados de columna en la primera fila mediante la HEADERS 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 cómo exportar datos de una tabla denominada sample_data a varios blobs con nombres y características diferentes, como su formato de codificación. Todos los blobs residen en el contenedor <container_name> de blobs de la cuenta <account_name>de Azure Storage . Use el COPY comando para exportar los datos:

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

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

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 ayudar a blob_get analizar los datos, pase un valor con el formato NULL::table_name, donde table_name hace referencia a una tabla cuyo esquema coincide con el del blob que está leyendo. En el ejemplo, hace referencia a la sample_data tabla que creó al principio.

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

En este caso, el descodificador que analiza 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 cómo se puede 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 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 cómo usar la decoder opción . Cuando no incluya la opción de descodificador, el sistema lo deduce de la extensión del archivo. Si el nombre de archivo no tiene una extensión o si la extensión de nombre de archivo no corresponde al descodificador que el sistema necesita 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 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, en función de 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;

El formato de codificación no se puede deducir 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 qué Azure cuentas de almacenamiento a las que 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. También muestra qué usuarios o roles tienen permiso, a través de la función azure_storage.account_user_add, para acceder a esa cuenta de almacenamiento 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 desde un usuario o rol denominado <regular_user>, de modo que el 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.