Importar e exportar dados usando azure_storage extensão no Banco de Dados do Azure para PostgreSQL - Servidor Flexível

Artigo
11/19/2024

APLICA-SE A: Banco de Dados do Azure para PostgreSQL - Servidor Flexível

A extensão azure_storage permite importar ou exportar dados em vários formatos de arquivo, diretamente entre contas de Armazenamento do Azure e uma instância do Banco de Dados do Azure para Servidor Flexível PostgreSQL.

Exemplos de exportação e importação de dados usando essa extensão podem ser encontrados na seção Exemplos deste artigo.

Para usar a azure_storage extensão em sua instância de servidor flexível do Banco de Dados do Azure para PostgreSQL, você precisa adicionar a extensão ao shared_preload_libraries, e também adicioná-la ao azure.extensions parâmetro server, conforme descrito em como usar extensões PostgreSQL.

Como shared_preload_library é um parâmetro estático do servidor, ele requer uma reinicialização do servidor para que a alteração entre em vigor.

Quando o servidor for reiniciado, conecte-se à sua instância do PostgreSQL usando o cliente de sua preferência (por exemplo, psql, pgAdmin, etc.). Confirme se SHOW azure.extensions;, e SHOW shared_preload_libraries;, ambos incluem o valor azure_storage na lista dos valores separados por vírgulas retornados por cada uma das SHOW instruções.

Só então você pode instalar a extensão, conectando-se ao seu banco de dados de destino e executando a instrução CREATE EXTENSION . Você precisa repetir o comando separadamente para cada banco de dados no qual deseja que a extensão esteja disponível.

CREATE EXTENSION azure_storage;

Visão geral do procedimento

Identifique as contas de Armazenamento do Azure com as quais você deseja que os azure_storage usuários da extensão interajam.
Decida qual tipo de autorização você deseja usar para as solicitações feitas no serviço de blob de cada uma dessas contas de Armazenamento do Azure. azure_storagesuporta autorização com Chave Compartilhada e autorização com ID do Microsoft Entra. Desses dois tipos de autorização, o Microsoft Entra ID oferece segurança superior e facilidade de uso em relação à Chave Compartilhada, e é o que a Microsoft recomenda. Para atender aos pré-requisitos necessários em cada caso, siga as instruções nas seções correspondentes:
- Autorização com ID do Microsoft Entra ou
- Autorização com Chave Partilhada.
Incluir azure_storage em shared_preload_libraries:

Como o shared_preload_libraries é estático, o servidor deve ser reiniciado para que uma alteração entre em vigor:

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)

Como o shared_preload_libraries é estático, o servidor deve ser reiniciado para que uma alteração entre em vigor:

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

Incluir azure_storage em 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)

Usando o cliente de sua preferência (por exemplo, psql, pgAdmin, etc.), conecte-se a qualquer banco de dados em sua instância do Banco de Dados do Azure para Servidor Flexível PostgreSQL. Para criar todos os objetos SQL (tabelas, tipos, funções, modos de exibição etc.) com os quais você pode usar a azure_storage extensão para interagir com instâncias de contas de Armazenamento do Azure, execute a seguinte instrução:
```
CREATE EXTENSION azure_storage;
```
Usando as azure_storage.account_* funções, adicione referências às contas de Armazenamento do Azure que você deseja permitir que usuários ou funções do PostgreSQL acessem com a azure_storage extensão. Essas referências incluem o nome da conta de Armazenamento do Azure que está sendo referenciada e o tipo de autenticação a ser usado ao interagir com a conta de Armazenamento do Azure. Dependendo do tipo de autenticação selecionado, talvez seja necessário fornecer também alguns outros parâmetros, como a chave de acesso da conta do Armazenamento do Azure ou o token SAS.

Importante

Para tipos de autenticação para os quais você deve fornecer uma chave de acesso da conta do Armazenamento do Azure, observe que suas chaves de acesso do Armazenamento do Azure são semelhantes a uma senha raiz para sua conta de armazenamento. Tenha sempre o cuidado de os proteger. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança. azure_storage A extensão armazena essas chaves em uma tabela azure_storage.accounts que pode ser lida pelos membros da pg_read_all_data função.

Os usuários que receberam a azure_storage_admin função podem interagir com a azure_storage.accounts tabela usando as seguintes funções:

azure_storage.account_add
azure_storage.lista_de_contas
azure_storage.account_remove
azure_storage.account_user_add
azure_storage.account_user_remove

A azure_storage_admin função é, por padrão, concedida à azure_pg_admin função.

Para usar a autorização com o Microsoft Entra ID

Habilite a Identidade Gerenciada Atribuída pelo Sistema em sua instância do Banco de Dados do Azure para o Servidor Flexível 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 a instância do Banco de Dados do Azure para o Servidor Flexível PostgreSQL, depois de habilitar uma identidade gerenciada atribuída ao sistema nele.
Atribua permissões de controle de acesso baseado em função (RBAC) para acesso a dados de blob, na conta de Armazenamento do Azure, à Identidade Gerenciada Atribuída pelo Sistema de sua instância do Banco de Dados do Azure para Servidor Flexível PostgreSQL.

Para usar a autorização com a Chave Compartilhada

Sua conta de Armazenamento do Azure deve ter Permitir acesso à chave da conta de armazenamento habilitada (ou seja, não pode ter sua propriedade AllowSharedKeyAccess definida como false).

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

Para passá-lo para a função azure_storage.account_add , busque uma das duas chaves de acesso da conta de Armazenamento do Azure.

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

Funções

azure_storage.account_add

Função que permite adicionar uma conta de armazenamento, e sua chave de acesso associada, à lista de contas de armazenamento que a azure_storage extensão pode acessar.

Se uma invocação anterior desta função já adicionou a referência a esta conta de armazenamento, ela não adiciona uma nova entrada, mas atualiza a chave de acesso da entrada existente.

Nota

Esta função não valida se o nome da conta referida existe ou se está acessível com a chave de acesso fornecida. No entanto, ele valida se o nome da conta de armazenamento é válido, de acordo com as regras de validação de nomenclatura impostas às contas de armazenamento do Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

Há uma versão sobrecarregada dessa função, que aceita um account_config parâmetro que encapsula o nome da conta de Armazenamento do Azure referenciada e todas as configurações necessárias, como tipo de autenticação, tipo de conta ou credenciais de armazenamento.

azure_storage.account_add(account_config jsonb);

Permissões

Deve ser membro do azure_storage_admin.

Argumentos

account_name_p

text o nome da conta de armazenamento de blob do Azure que contém todos os seus objetos: blobs, arquivos, filas e tabelas. A conta de armazenamento fornece um namespace exclusivo que pode ser acessado de qualquer lugar do mundo por HTTPS.

account_key_p

text O valor de uma das chaves de acesso para a conta de armazenamento. Suas chaves de acesso de armazenamento de blob do Azure são semelhantes a uma senha de root para sua conta de armazenamento. Tenha sempre o cuidado de proteger as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança. A chave da conta é armazenada em uma tabela acessível apenas pelo superusuário. Os usuários que receberam a azure_storage_admin função podem interagir com essa tabela por meio de funções. Para ver quais contas de armazenamento são adicionadas, use a função azure_storage.account_list.

account_config

jsonb o nome da conta de Armazenamento do Azure e todas as configurações necessárias, como tipo de autenticação, tipo de conta ou credenciais de armazenamento. Recomendamos o uso das funções do utilitário azure_storage.account_options_managed_identity, azure_storage.account_options_credentials ou azure_storage.account_options para criar qualquer um dos valores válidos que devem ser passados como esse argumento.

Tipo de retorno

VOID

azure_storage.account_options_managed_identity

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro de azure_storage.account_add, e é útil para produzir um valor válido para o account_config argumento, ao usar uma identidade gerenciada atribuída ao sistema para interagir com a conta de Armazenamento do Azure.

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

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

nome

tipo

azure_storage.storage_type O valor de um dos tipos de armazenamento suportados. Apenas o valor suportado é blob.

Tipo de retorno

jsonb

azure_storage.account_options_credentials

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro azure_storage.account_add, e é útil para produzir um valor válido para o account_config argumento, ao usar uma chave de acesso do Armazenamento do Azure para interagir com a conta de Armazenamento do Azure.

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

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

nome

credenciais

tipo

azure_storage.storage_type O valor de um dos tipos de armazenamento suportados. Apenas o valor suportado é blob.

Tipo de retorno

jsonb

azure_storage.account_options

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro de azure_storage.account_add, e é útil para produzir um valor válido para o account_config argumento, ao usar uma chave de acesso do Armazenamento do Azure ou uma identidade gerenciada atribuída ao sistema para interagir com a conta de Armazenamento do Azure.

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

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

nome

auth_type

azure_storage.auth_type O valor de um dos tipos de armazenamento suportados. Apenas os valores suportados são access-key, e managed-identity.

storage_type

azure_storage.storage_type O valor de um dos tipos de armazenamento suportados. Apenas o valor suportado é blob.

credenciais

Tipo de retorno

jsonb

azure_storage.account_remove

Função que permite remover uma conta de armazenamento e sua chave de acesso associada da lista de contas de armazenamento que a azure_storage extensão pode acessar.

azure_storage.account_remove(account_name_p text);

Permissões

Deve ser membro do azure_storage_admin.

Argumentos

account_name_p

Tipo de retorno

VOID

azure_storage.account_user_add

Função que permite conceder a um usuário ou função PostgreSQL acesso a uma conta de armazenamento através das funções fornecidas pela azure_storage extensão.

Nota

A execução dessa função só será bem-sucedida se a conta de armazenamento, cujo nome está sendo passado como o primeiro argumento, já tiver sido criada usando azure_storage.account_add, e se o usuário ou função, cujo nome é passado como o segundo argumento, já existir.

azure_storage.account_add(account_name_p text, user_p regrole);

Permissões

Deve ser membro do azure_storage_admin.

Argumentos

account_name_p

user_p

regrole o nome de um usuário ou função PostgreSQL disponível no servidor.

Tipo de retorno

VOID

azure_storage.account_user_remove

Função que permite revogar o acesso de um usuário ou função PostgreSQL a uma conta de armazenamento através das azure_storage funções fornecidas pela extensão.

Nota

A execução dessa função só será bem-sucedida se a conta de armazenamento cujo nome está sendo passado como o primeiro argumento já tiver sido criada usando azure_storage.account_add e se o usuário ou função cujo nome é passado como o segundo argumento ainda existir. Quando um usuário ou função é descartado do servidor, ao executar DROP USER | ROLE, as permissões concedidas em qualquer referência às contas de Armazenamento do Azure também são eliminadas automaticamente.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Permissões

Deve ser membro do azure_storage_admin.

Argumentos

account_name_p

user_p

regrole o nome de um usuário ou função PostgreSQL disponível no servidor.

Tipo de retorno

VOID

azure_storage.lista_de_contas

Função que lista os nomes das contas de armazenamento que foram configuradas por meio da função azure_storage.account_add , juntamente com os usuários ou funções do PostgreSQL que recebem permissões para interagir com essa conta de armazenamento por meio das azure_storage funções fornecidas pela extensão.

azure_storage.account_list();

Permissões

Deve ser membro do azure_storage_admin.

Argumentos

Esta função não aceita quaisquer argumentos.

Tipo de retorno

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[]) uma tabela de quatro colunas com a lista de contas de Armazenamento do Azure adicionadas, o tipo de autenticação usado para interagir com cada conta, o tipo de armazenamento e a lista de usuários ou funções do PostgreSQL aos quais é concedido acesso a ela.

azure_storage.blob_list

Função que lista os nomes e outras propriedades (size, lastModified, eTag, contentType, contentEncoding, e contentHash) de blobs armazenados no contêiner determinado da conta de armazenamento referida.

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

Permissões

O usuário ou função que invoca essa função deve ser adicionado à lista de permissões para o account_name referenciado, executando azure_storage.account_user_add. Os membros de têm permissão automática para fazer referência a todas as contas de Armazenamento do azure_storage_admin Azure cujas referências foram adicionadas usando azure_storage.account_add.

Argumentos

account_name

container_name

text O nome de um contêiner. Um contentor organiza um conjunto de blobs, de forma semelhante a um diretório num sistema de ficheiros. Uma conta de armazenamento pode incluir um número ilimitado de contentores, e um contentor pode armazenar um número ilimitado de blobs. Um nome de contêiner deve ser um nome DNS (Sistema de Nomes de Domínio) válido, pois faz parte do URI exclusivo usado para endereçar o contêiner ou seus blobs. Ao nomear um contêiner, certifique-se de seguir estas regras.

O URI de um contêiner é semelhante a: https://myaccount.blob.core.windows.net/mycontainer

prefixo

text Quando especificada, a função retorna os blobs cujos nomes começam com o valor fornecido nesse parâmetro. O padrão é uma cadeia de caracteres vazia.

Tipo de retorno

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) Uma tabela com um registro por blob retornado, incluindo o nome completo do blob e algumas outras propriedades.

path

text O nome completo do blob.

bytes

bigint O tamanho do blob em bytes.

last_modified

timestamp with time zoneA data e a hora em que o blob foi modificado pela última vez. Qualquer operação que modifique o blob, incluindo uma atualização dos metadados ou propriedades do blob, altera a hora da última modificação do blob.

etag

text a propriedade ETag é usada para simultaneidade otimista durante as atualizações. Não é um carimbo de data/hora, pois há outra propriedade chamada Timestamp que armazena a última vez que um registro foi atualizado. Por exemplo, se você carregar uma entidade e quiser atualizá-la, o ETag deverá corresponder ao que está armazenado no momento. Definir a ETag apropriada é importante porque, se você tiver vários usuários editando o mesmo item, não deseja que eles substituam as alterações uns dos outros.

content_type

text O tipo de conteúdo especificado para o BLOB. O tipo de conteúdo padrão é application/octet-stream.

content_encoding

text a propriedade Content-Encoding de um blob que o Armazenamento do Azure permite definir. Para conteúdo compactado, você pode definir a propriedade como Gzip. Quando o navegador acessa o conteúdo, ele descompacta automaticamente o conteúdo.

content_hash

text O hash usado para verificar a integridade do blob durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento verifica o hash fornecido com um calculado a partir do conteúdo. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação incorreta).

azure_storage.blob_get

Função que permite importar dados. Ele baixa um ou mais arquivos de um contêiner de blob em uma conta de Armazenamento do Azure. Em seguida, ele traduz o conteúdo em linhas, que podem ser consumidas e processadas com construções de linguagem SQL. Esta função adiciona suporte para filtrar e manipular os dados obtidos do contêiner de blob antes de importá-lo.

Nota

Antes de tentar acessar o contêiner para a conta de armazenamento referida, essa função verifica se os nomes da conta de armazenamento e do contêiner passados como argumentos são válidos de acordo com as regras de validação de nomenclatura impostas às contas de armazenamento do Azure. Se qualquer um deles for inválido, um erro será gerado.

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

Há uma versão sobrecarregada dessa função, que aceita um rec parâmetro que permite definir convenientemente o registro do formato de saída.

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

Permissões

Argumentos

account_name

container_name

O URI de um contêiner é semelhante a: https://myaccount.blob.core.windows.net/mycontainer

path

text O nome completo do blob.

rec

anyelement a definição da estrutura de produção de registos.

descodificador

text A especificação do formato Blob. Pode ser definido como qualquer um dos seguintes valores:

Formato	Predefinição	Descrição
`auto`	`true`	Infere o valor com base na última série de caracteres atribuídos ao nome do blob. Se o nome do blob terminar com `.csv` ou `.csv.gz`, ele assume `csv`. Se termina com `.tsv` ou `.tsv.gz`, assume `tsv`. Se termina com `.json`, `.json.gz`, , `.xml.gz.xml`, `.txt`, ou `.txt.gz`, assume `text`.
`csv`		Formato de valores separados por vírgulas usado pelo PostgreSQL COPY.
`tsv`		Valores separados por tabulações, o formato padrão PostgreSQL COPY.
`binary`		Formato binário PostgreSQL COPY.
`text` \| `xml` \| `json`		Um arquivo que contém um único valor de texto.

compressão

text a especificação do tipo de compressão. Pode ser definido como qualquer um dos seguintes valores:

Formato	Predefinição	Descrição
`auto`	`true`	Infere o valor com base na última série de caracteres atribuídos ao nome do blob. Se o nome do blob terminar com `.gz`, ele assume `gzip`. Caso contrário, assume `none`.
`gzip`		Força usando o decodificador gzip para descompactar o blob.
`none`		Forças para tratar o blob como um que não requer descompressão.

A extensão não suporta outros tipos de compressão.

options

jsonb as configurações que definem a manipulação de cabeçalhos personalizados, separadores personalizados, caracteres de escape, etc. options afeta o comportamento dessa função de forma semelhante a como as opções que você pode passar para o COPY comando no PostgreSQL afetam seu comportamento.

Tipo de retorno

SETOF record SETOF anyelement

azure_storage.blob_put

Função que permite exportar dados, carregando arquivos em um contêiner de blob em uma conta de Armazenamento do Azure. O conteúdo dos arquivos é produzido a partir de linhas em PostgreSQL.

Nota

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

Há uma versão sobrecarregada da função, contendo encoder o parâmetro que permite especificar o codificador a ser usado quando ele não puder ser inferido a partir da extensão do path parâmetro ou quando você quiser substituir o inferido.

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

Há uma versão sobrecarregada da função que também contém um compression parâmetro que permite especificar a compactação a ser usada quando ela não puder ser inferida a partir da extensão do path parâmetro ou quando você quiser substituir a que foi inferida.

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

Há uma versão sobrecarregada da função que também contém um options parâmetro para lidar com cabeçalhos personalizados, separadores personalizados, caracteres de escape, etc. options funciona de forma semelhante às opções que podem ser passadas para o COPY comando no PostgreSQL.

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

Permissões

Argumentos

account_name

container_name

O URI de um contêiner é semelhante a: https://myaccount.blob.core.windows.net/mycontainer

path

text O nome completo do blob.

tuple

record a definição da estrutura de produção de registos.

encoder

text A especificação do formato Blob. Pode ser definido como qualquer um dos seguintes valores:

Formato	Predefinição	Descrição
`auto`	`true`	Infere o valor com base na última série de caracteres atribuídos ao nome do blob. Se o nome do blob terminar com `.csv` ou `.csv.gz`, ele assume `csv`. Se termina com `.tsv` ou `.tsv.gz`, assume `tsv`. Se termina com `.json`, `.json.gz`, , `.xml.gz.xml`, `.txt`, ou `.txt.gz`, assume `text`.
`csv`		Formato de valores separados por vírgulas usado pelo PostgreSQL COPY.
`tsv`		Valores separados por tabulações, o formato padrão PostgreSQL COPY.
`binary`		Formato binário PostgreSQL COPY.
`text` \| `xml` \| `json`		Um arquivo que contém um único valor de texto.

compressão

text a especificação do tipo de compressão. Pode ser definido como qualquer um dos seguintes valores:

Formato	Predefinição	Descrição
`auto`	`true`	Infere o valor com base na última série de caracteres atribuídos ao nome do blob. Se o nome do blob terminar com `.gz`, ele assume `gzip`. Caso contrário, assume `none`.
`gzip`		Força usando o decodificador gzip para descompactar o blob.
`none`		Forças para tratar o blob como um que não requer descompressão.

A extensão não suporta outros tipos de compressão.

options

Tipo de retorno

VOID

azure_storage.options_csv_get

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro blob_getdo , e é útil para decodificar o conteúdo de um arquivo 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);

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

delimitador

text O caractere que separa colunas dentro de cada linha (linha) do arquivo. Deve ser um único caractere de 1 byte. Embora essa função ofereça suporte a delimitadores de qualquer número de caracteres, se você tentar usar mais de um único caractere de 1 byte, o PostgreSQL relatará um COPY delimiter must be a single one-byte character erro.

null_string

text A cadeia de caracteres que representa um valor nulo. O padrão é \N (barra invertida-N) no formato de texto e uma cadeia de caracteres vazia sem aspas no formato CSV. Você pode preferir uma cadeia de caracteres vazia, mesmo em formato de texto, para casos em que não deseja distinguir nulos de cadeias de caracteres vazias.

boolean sinalizador que indica se o arquivo contém uma linha de cabeçalho com os nomes de cada coluna no arquivo. Na saída, a linha inicial contém os nomes das colunas da tabela.

citação

text O caractere de cotação a ser usado quando um valor de dados é cotado. O padrão é aspas duplas. Deve ser um único caractere de 1 byte. Embora essa função ofereça suporte a delimitadores de qualquer número de caracteres, se você tentar usar mais de um único caractere de 1 byte, o PostgreSQL relatará um COPY quote must be a single one-byte character erro.

escape

text o caractere que deve aparecer antes de um caractere de dados que corresponde ao valor QUOTE. O padrão é o mesmo que o valor QUOTE (para que o caractere de cotação seja dobrado se aparecer nos dados). Deve ser um único caractere de 1 byte. Embora essa função ofereça suporte a delimitadores de qualquer número de caracteres, se você tentar usar mais de um único caractere de 1 byte, o PostgreSQL relatará um COPY escape must be a single one-byte character erro.

force_not_null

text[] não correspondem aos valores das colunas especificadas em relação à cadeia de caracteres nula. No caso padrão em que a cadeia de caracteres nula está vazia, isso significa que os valores vazios são lidos como cadeias de caracteres de comprimento zero em vez de nulos, mesmo quando não estão entre aspas.

force_null

text[] corresponder aos valores das colunas especificadas em relação à cadeia de caracteres nula, mesmo se citada, e se uma correspondência for encontrada, defina o valor como NULL. No caso padrão em que a cadeia de caracteres nula está vazia, ela converte uma cadeia de caracteres vazia entre aspas em NULL.

content_encoding

text Nome da codificação com a qual o arquivo é codificado. Se a opção for omitida, a codificação do cliente atual será usada.

Tipo de retorno

jsonb

azure_storage.options_copy

Função que atua como uma função de utilidade, que pode ser chamada como um parâmetro dentro de blob_get. Ele atua como uma função auxiliar para options_csv_get, options_tsv e 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);

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

delimitador

null_string

cabeçalho

boolean sinalizador que indica se o arquivo contém uma linha de cabeçalho com os nomes de cada coluna no arquivo. Na saída, a linha inicial contém os nomes das colunas da tabela.

citação

escape

force_quote

text[] força a citação a ser usada para todos os valores não-NULL em cada coluna especificada. A saída NULL nunca é citada. Se * for especificado, valores não NULL serão citados em todas as colunas.

force_not_null

force_null

content_encoding

text Nome da codificação com a qual o arquivo é codificado. Se a opção for omitida, a codificação do cliente atual será usada.

Tipo de retorno

jsonb

azure_storage.options_tsv

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro blob_getdo , e é útil para decodificar o conteúdo de um arquivo tsv.

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

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

delimitador

null_string

content_encoding

text Nome da codificação com a qual o arquivo é codificado. Se a opção for omitida, a codificação do cliente atual será usada.

Tipo de retorno

jsonb

azure_storage.options_binary

Função que atua como uma função utilitária, que pode ser chamada como um parâmetro dentro blob_getdo , e é útil para decodificar o conteúdo de um arquivo binário.

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

Permissões

Qualquer utilizador ou função pode invocar esta função.

Argumentos

content_encoding

text Nome da codificação com a qual o arquivo é codificado. Se a opção for omitida, a codificação do cliente atual será usada.

Tipo de retorno

jsonb

Possíveis erros

ERRO: azure_storage: A permissão não é suficiente para executar a operação solicitada

Ao executar qualquer uma das funções que interagem com o Armazenamento do Azure (azure_storage.blob_list, azure_storage.blob_get ou azure_storage.blob_put) e a Identidade Gerenciada Atribuída ao Sistema não recebe as funções ou permissões adequadas do plano de dados (normalmente um mínimo de Colaborador de Dados de Blob de Armazenamento para azure_storage.blob_put e um mínimo de Leitor de Dados de Blob de Armazenamento para as outras duas funções).

Também pode ser o caso de você já ter concedido as permissões mínimas necessárias, mas elas ainda não estão em vigor. Pode levar alguns minutos até que essas permissões sejam propagadas.

ERRO: azure_storage: credenciais de armazenamento ausentes

Ao executar qualquer uma das funções que interagem com o Armazenamento do Azure (azure_storage.blob_list, azure_storage.blob_get ou azure_storage.blob_put) e as credenciais com as quais você deseja que a extensão se autentique com a conta de armazenamento não são registradas usando azure_storage.account_addo .

ERRO: azure_storage: erro interno ao conectar

Quando a Identidade Gerenciada Atribuída pelo Sistema não estiver habilitada na instância do Servidor Flexível.

ERRO: azure_storage: credenciais de armazenamento formato inválido

Quando a Identidade Gerenciada Atribuída pelo Sistema estiver habilitada na instância do Servidor Flexível, mas o servidor não tiver sido reiniciado após a habilitação.

ERRO: azure_storage: o usuário <atual user_or_role> não tem permissão para usar a conta <de armazenamento storage_account>

Ao executar qualquer uma das funções que interagem com o Armazenamento do Azure (azure_storage.blob_list, azure_storage.blob_get ou azure_storage.blob_put) com um usuário ou função que não é membro azure_storage_admin e não recebe permissões, usando azure_storage.account_user_add, para usar a conta de armazenamento referida.

Exemplos

Você deve atender aos seguintes pré-requisitos antes de executar os seguintes exemplos:

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 , <location>, <storage_account>e <blob_container>e execute o seguinte comando da CLI do <resource_group>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

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

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 Armazenamento do Azure que foram adicionadas azure_storage_admin usando azure_storage.account_add. Por padrão, apenas os membros do azure_pg_admin recebem a azure_storage_admin função.

Criar tabela na qual os dados são carregados

Vamos criar a tabela para a qual importamos o conteúdo do arquivo CSV que carregamos para a conta de armazenamento. Para fazer isso, conecte-se à sua instância do Banco de Dados do Azure para servidor flexível PostgreSQL usando PgAdmin, psqlou o cliente de sua preferência e execute a seguinte instrução:

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

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.

<storage_account> 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('<storage_account>', '<access_key>');

Gorjeta

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

Remover referência à conta de armazenamento

Este exemplo ilustra como remover qualquer referência a uma conta de armazenamento, para que nenhum usuário no banco de dados atual possa usar a azure_storage funcionalidade de extensão para acessar essa conta de armazenamento.

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

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('<storage_account>', '<regular_user>');

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.

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

SELECT * FROM azure_storage.account_user_remove('<storage_account>', '<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 <storage_account>de armazenamento.

<blob_container> 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('<storage_account>','<blob_container>');

Listar os objetos com prefixo de nome de blob específico

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

<blob_name_prefix> deve ser definido como o 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('<storage_account>','<blob_container>','<blob_name_prefix>');

Como alternativa, você pode usar a seguinte sintaxe:

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

Ler conteúdo de um blob em um contêiner

A blob_get função recupera o conteúdo de um blob específico (events.csv neste caso), no recipiente <blob_container> referido do <storage_account> 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 à events tabela que criamos no início.

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

Utilize a opção de descodificador

Este exemplo ilustra o decoder uso da opção. Normalmente, o formato é inferido a partir da extensão do arquivo, mas quando o conteúdo do arquivo não tem uma extensão correspondente, você pode passar o argumento do decodificador.

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

Use a compactação com a opção de decodificador

Este exemplo mostra como impor o uso da compactação gzip em um blob compactado gzip cujo nome não termina com uma extensão .gz.

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

Importar conteúdo filtrado e modificar antes de carregar do objeto de formato csv

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-',event_id::text) FROM azure_storage.blob_get
        ('<storage_account>'
        ,'<blob_container>'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Consultar conteúdo de arquivo com cabeçalhos, separadores personalizados, 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
        ('<storage_account>'
        ,'<blob_container>'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Consulta de agregaçã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 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;

Importar dados usando uma instrução COPY

O exemplo a seguir mostra a importação de dados de um blob chamado events.csv que reside no contêiner <blob_container> de blob na conta <storage_account>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 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 uma COPY instrução para copiar dados para a tabela de destino. Especifique que a primeira linha contém cabeçalhos de coluna.
```
COPY events
FROM 'https://<storage_account>.blob.core.windows.net/<blob_container>/events.csv'
WITH (FORMAT 'csv', header);
```

Gravar conteúdo em um blob em um contêiner

A blob_put função compõe o conteúdo de um blob específico (eventscopy.csv neste caso) e carrega-o para o recipiente <blob_container> referido do <storage_account> 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 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;

Exportar dados usando uma instrução COPY

O exemplo a seguir mostra a exportação de dados de uma tabela chamada events, para um blob chamado events_exported.csv que reside no contêiner <blob_container> de blob na conta <storage_account>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 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
        );

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

Use uma COPY instrução para copiar dados para a tabela de destino. Especifique que a primeira linha contém cabeçalhos de coluna.

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

Partilhe as suas sugestões e bugs com a equipa de produto da Base de Dados do Azure para PostgreSQL.

Partilhar via

Importar e exportar dados usando azure_storage extensão no Banco de Dados do Azure para PostgreSQL - Servidor Flexível

Visão geral do procedimento

Para usar a autorização com o Microsoft Entra ID

Para usar a autorização com a Chave Compartilhada

Funções

azure_storage.account_add

Permissões

Argumentos

account_name_p

account_key_p

account_config

Tipo de retorno

azure_storage.account_options_managed_identity

Permissões

Argumentos

nome

tipo

Tipo de retorno

azure_storage.account_options_credentials

Permissões

Argumentos

nome

credenciais

tipo

Tipo de retorno

azure_storage.account_options

Permissões

Argumentos

nome

auth_type

storage_type

credenciais

Tipo de retorno

azure_storage.account_remove

Permissões

Argumentos

account_name_p

Tipo de retorno

azure_storage.account_user_add

Permissões

Argumentos

account_name_p

user_p

Tipo de retorno

azure_storage.account_user_remove

Permissões

Argumentos

account_name_p

user_p

Tipo de retorno

azure_storage.lista_de_contas

Permissões

Argumentos

Tipo de retorno

azure_storage.blob_list

Permissões

Argumentos

account_name

container_name

prefixo

Tipo de retorno

path

bytes

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Permissões

Argumentos

account_name

container_name

path

rec

descodificador

compressão

options

Tipo de retorno