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

A seguir está 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

Criar uma conta de Armazenamento do Azure. Para criar uma conta de Armazenamento do Azure, se ainda não tiver uma, personalize os valores de , <resource_group>, <location>e <account_name>e execute o seguinte comando da CLI do <container_name>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
```
Buscar uma das duas chaves de acesso atribuídas à conta de armazenamento. Certifique-se de copiar o valor do seu access_key pois 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 para seu 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 os blobs armazenados neles para uma conta de armazenamento específica, mas somente se seu 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 função recebem esse privilégio sobre todas as contas de azure_storage_admin Armazenamento do Azure que foram adicionadas usando azure_storage.account_add. Por padrão, apenas os membros do azure_pg_admin recebem a azure_storage_admin função.

Criar uma tabela na qual os dados são carregados

Vamos criar a tabela onde importamos o conteúdo dos ficheiros que carregámos para a conta de armazenamento. Para tal, ligue-se à sua instância do Azure Database for PostgreSQL flexible server usando PostgreSQL for Visual Studio Code (Preview), psql, PgAdmin ou o cliente da 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 prosseguir, certifique-se de que:

Adicionar 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 Banco de Dados do Azure para servidor flexível PostgreSQL.

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

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

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

Sugestão

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

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

Este exemplo ilustra como conceder acesso a um usuário ou função chamado <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 referida conta de armazenamento do Azure.

<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 seu contêiner de blob. Se você usou os scripts anteriores, esse valor deve 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 quiser retornar todos os blobs, você pode definir esse parâmetro como uma cadeia de caracteres vazia ou nem mesmo especificar um valor para esse parâmetro, caso em que o valor assume como padrão 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 a partir da extensão do ficheiro.

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 a partir da extensão do ficheiro, é explicitamente especificado através da FORMAT opção.
```
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 a partir da extensão do ficheiro. No entanto, a presença de cabeçalhos de coluna na primeira linha precisa de ser explicitamente configurada através 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 que os dados foram carregados na tabela.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Exportar dados usando uma instrução COPY TO

Os exemplos seguintes mostram a exportação de dados de uma tabela chamada sample_data, para múltiplos blobs com nomes diferentes e características como o seu formato de codificação, todos os quais residem no contentor <container_name> do blob na conta <account_name>Azure Storage , através 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ê-las com várias linhas sintéticas ou use os dados Import usando um exemplo de instrução COPY FROM para preenchê-las 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 que a primeira linha do ficheiro resultante contém cabeçalhos de colunas.
```
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 que 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 contentor <container_name> referido do <account_name> armazenamento. Para blob_get saber como analisar os dados você pode passar um valor no formulário NULL::table_name, onde table_name se refere a uma tabela cujo esquema corresponde ao do blob que está sendo lido. No exemplo, refere-se à sample_data tabela que criamos no início.

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

Neste caso, o descodificador que deve ser usado para analisar o blob é inferido a partir da .parquet extensão do ficheiro.

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

Utilize a opção de descodificador

Este exemplo ilustra o decoder uso da opção. Quando a opção do descodificador não está presente, é inferida pela extensão do ficheiro. Mas quando o nome do ficheiro não tem extensão, ou quando essa extensão não corresponde àquela associada ao descodificador que deve ser usado para analisar corretamente o conteúdo do ficheiro, pode-se passar explicitamente o argumento do descodificador.

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;

Escrever conteúdo em um blob

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

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

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 .csvdo ficheiro .

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 ficheiro não tem extensão de ficheiro, por isso está explicitamente configurado como parquet. Além disso, o algoritmo de compressão está definido para 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 a contas de armazenamento do Azure

Este exemplo ilustra como descobrir quais contas de armazenamento do Azure a azure_storage extensão pode referenciar nesse banco de dados, juntamente com o tipo de autenticação usado 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 Blob do Azure

Este exemplo ilustra como revogar o acesso de um usuário ou função chamado <regular_user>, para 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 referida conta de armazenamento do Azure.