Exemplos de início rápido para a extensão de Armazenamento do Azure no Banco de Dados do Azure para PostgreSQL

Veja a seguir uma lista de exemplos para ajudá-lo a aprender a usar a extensão de Armazenamento do Azure.

Criar uma conta de Armazenamento do Azure e preenchê-la com dados

Crie uma conta de armazenamento do Azure. Para criar uma conta de Armazenamento do Azure, se você ainda não tiver uma, personalize os valores de <resource_group>, <location>e <account_name>, e <container_name>execute o seguinte comando da CLI do 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

Crie um contêiner de blob. Para criar o contêiner de blob, execute a seguinte CLI do Azure:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Busque uma das duas chaves de acesso atribuídas à conta de armazenamento. Copie o valor do seu access_key, pois você precisa passá-lo como um argumento para azure_storage.account_add em uma etapa subsequente. Para buscar a primeira das duas chaves de acesso, execute o seguinte comando da CLI do 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
```

Baixe o arquivo com o conjunto de dados usado durante os exemplos e carregue-o no contêiner de blob. Para baixar o arquivo com o conjunto de dados, execute o seguinte comando da CLI do 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

Observação

Você pode listar contêineres ou blobs armazenados neles para uma conta de armazenamento específica, mas somente se o usuário ou função do PostgreSQL receber permissão na referência a essa conta de armazenamento usando azure_storage.account_user_add. Os membros da azure_storage_admin função recebem esse privilégio em todas as contas de Armazenamento do Azure que foram adicionadas usando azure_storage.account_add. Por padrão, somente membros da azure_pg_admin função recebem a azure_storage_admin função.

Criar uma tabela na qual os dados são carregados

Vamos criar a tabela na qual importamos o conteúdo dos arquivos que carregamos para a conta de armazenamento. Para fazer isso, conecte-se à instância do servidor flexível do Banco de Dados do Azure para PostgreSQL usando o PostgreSQL para Visual Studio Code (versão prévia),psql, PgAdmin ou o cliente de sua preferência e execute a seguinte instrução:

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

Preparar a extensão para uso

Antes de continuar, verifique se você:

Adicionar a chave de acesso da conta de armazenamento

Este exemplo ilustra como adicionar uma referência a uma conta de armazenamento, juntamente com a chave de acesso dessa conta de armazenamento, que é necessária para acessar seu conteúdo por meio da funcionalidade fornecida pela azure_storage extensão em sua instância do servidor flexível do Banco de Dados do Azure para PostgreSQL.

<account_name> deve ser definido como o nome da sua conta de armazenamento. Se você usou os scripts anteriores, esse valor deverá corresponder a qualquer valor definido para a variável de ambiente storage_account nesses scripts.

Da mesma forma, <access_key> deve ser definido como o valor que você busca da sua conta de armazenamento.

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

Dica

Se você quiser recuperar o nome da conta de armazenamento e uma de suas chaves de acesso do portal do Azure, pesquise sua conta de armazenamento, no menu de recursos selecione chaves do Access, copie o nome da conta de armazenamento e copie a chave da seção key1 (você precisa selecionar Mostrar ao lado da chave primeiro).

Conceder acesso a um usuário ou função na referência de armazenamento de Blobs do Azure

Este exemplo ilustra como conceder acesso a um usuário ou função nomeada <regular_user>, para que esse usuário do PostgreSQL possa usar a azure_storage extensão para acessar os blobs armazenados em contêineres hospedados pela conta de armazenamento do Azure referenciada.

<regular_user> deve ser definido como o nome de um usuário ou função existente.

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

Listar todos os blobs em um contêiner

Este exemplo ilustra como listar todos os blobs existentes dentro do contêiner <container_name> da conta <account_name>de armazenamento.

<container_name> deve ser definido como o nome do contêiner de blob. Se você usou os scripts anteriores, esse valor deverá corresponder a qualquer valor definido para a variável de ambiente blob_container nesses scripts.

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

Listar blobs com um prefixo de nome específico

Este exemplo ilustra como listar todos os blobs existentes dentro do contêiner <container_name> da conta <account_name>de armazenamento, cujo nome de blob começa com <blob_name_prefix>.

<blob_name_prefix> deve ser definido como qualquer prefixo que você deseja que os blobs enumerados incluam em seus nomes. Se você quiser retornar todos os blobs, poderá definir esse parâmetro como uma cadeia de caracteres vazia ou nem mesmo especificar um valor para esse parâmetro, nesse caso, o valor é padrão para uma cadeia de caracteres vazia.

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

Como alternativa, você pode usar a seguinte sintaxe:

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

Importar dados usando uma instrução COPY FROM

O exemplo a seguir mostra a importação de dados de um blob chamado storage_extension_sample.parquet que reside no contêiner <container_name> de blob na conta <account_name>de Armazenamento do Azure por meio do COPY comando:

Crie uma tabela que corresponda ao esquema do arquivo de origem:

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

Use uma COPY instrução para copiar dados para a tabela de destino. O formato é inferido como Parquet da extensão do arquivo.

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

Use uma COPY instrução para copiar dados para a tabela de destino. Como o formato de codificação não pode ser inferido da extensão de arquivo, ele é especificado explicitamente por meio da opção FORMAT .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Use uma COPY instrução para copiar dados para a tabela de destino. O formato de codificação pode ser inferido da extensão de arquivo. No entanto, a presença de cabeçalhos de coluna na primeira linha precisa ser configurada explicitamente por meio da HEADERS opção.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Execute a instrução a seguir SELECT para confirmar se os dados são carregados na tabela.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Exportar dados usando uma instrução COPY TO

Os exemplos a seguir mostram a exportação de dados de uma tabela chamada sample_data, para vários blobs com nomes diferentes, e características como seu formato de codificação, todos os quais residem no contêiner <container_name> de blob na conta <account_name>de Armazenamento do Azure, por meio do COPY comando:

Crie uma tabela que corresponda ao esquema do arquivo de origem:

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

Carregue dados na tabela. Execute instruções INSERT para preenchê-la com várias linhas sintéticas ou use os dados de importação usando um exemplo de instrução COPY FROM para preenchê-los com o conteúdo do conjunto de dados de exemplo.

Use uma COPY instrução para copiar dados da tabela de destino. Especifique que o formato de codificação deve ser parquet.

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

Use uma COPY instrução para copiar dados da tabela de destino. Especifique que o formato de codificação deve ser CSV e a primeira linha do arquivo resultante contém cabeçalhos de coluna.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Execute a instrução a seguir SELECT para confirmar se o blob existe na conta de armazenamento.

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

Ler conteúdo de um blob

A blob_get função recupera o conteúdo de um blob específico, no contêiner <container_name> referenciado do <account_name> armazenamento. Para blob_get saber como analisar os dados, você pode passar um valor no formulário NULL::table_name, em table_name que se refere a uma tabela cujo esquema corresponde ao do blob que está sendo lido. No exemplo, ele se refere à sample_data tabela que criamos no início.

<blob_name> deve ser definido como o caminho completo do blob cujo conteúdo você deseja ler.

Nesse caso, o decodificador que deve ser usado para analisar o blob é inferido da .parquet extensão de arquivo.

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

Como alternativa, você pode definir explicitamente o esquema do resultado usando a AS cláusula após a função 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;

Ler, filtrar e modificar o conteúdo lido de um blob

Este exemplo ilustra a possibilidade de filtrar e modificar o conteúdo importado do blob, antes de carregá-lo em uma tabela 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;

Ler o conteúdo do arquivo com opções personalizadas (cabeçalhos, delimitadores de coluna, caracteres de escape)

Este exemplo ilustra como você pode usar separadores personalizados e caracteres de escape passando o resultado de options_copy para o 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')
        );

Usar a opção de decodificador

Este exemplo ilustra o uso da opção decoder . Quando a opção de decodificador não está presente, ela é inferida da extensão do arquivo. Mas quando o nome do arquivo não tiver uma extensão ou quando essa extensão de nome de arquivo não corresponder à associada ao decodificador que deve ser usado para analisar corretamente o conteúdo do arquivo, você poderá passar explicitamente o argumento do decodificador.

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

Agregações de computação sobre o conteúdo de um blob

Este exemplo ilustra como você pode fazer operações de agregação sobre informações armazenadas em um contêiner de blob, sem a necessidade de importar o conteúdo do blob para tabelas 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;

Gravar conteúdo em um blob

A blob_put função compõe o conteúdo de um blob específico (sample_data_copy.parquet nesse caso) e o carrega no contêiner <container_name> referenciado do <account_name> armazenamento. Este exemplo usa blob_get para construir um conjunto de cinco linhas, que são então passadas para a função de agregação que as blob_put carrega como um blob chamado sample_data_copy.parquet.

O formato de codificação é inferido como parquet, com base na extensão .parquetde arquivo.

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;

O formato de codificação é inferido como CSV, com base na extensão .csvde arquivo.

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;

O formato de codificação não pode ser inferido porque o arquivo não tem uma extensão de arquivo, portanto, ele é configurado explicitamente como parquet. Além disso, o algoritmo de compactação é definido como 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;

Listar todas as referências às contas de armazenamento do Azure

Este exemplo ilustra como descobrir quais contas de armazenamento do Azure a azure_storage extensão pode referenciar neste banco de dados, juntamente com o tipo de autenticação usada para acessar cada conta de armazenamento e quais usuários ou funções recebem permissão, por meio da função azure_storage.account_user_add , para acessar essa conta de armazenamento do Azure por meio da funcionalidade fornecida pela extensão.

SELECT * FROM azure_storage.account_list();

Revogar o acesso de um usuário ou função na referência de armazenamento de Blobs do Azure

Este exemplo ilustra como revogar o acesso de um usuário ou função nomeada <regular_user>, de modo que esse usuário do PostgreSQL não possa usar a azure_storage extensão para acessar os blobs armazenados em contêineres hospedados pela conta de armazenamento do Azure referenciada.