Importare ed esportare dati usando l'estensione azure_storage in Database di Azure per PostgreSQL - Server flessibile

Articolo
11/19/2024

SI APPLICA A: Database di Azure per PostgreSQL - Server flessibile

L'estensione azure_storage consente di importare o esportare dati in più formati di file, direttamente tra gli account Archiviazione di Azure e un'istanza di Database di Azure per PostgreSQL server flessibile.

Esempi di esportazione e importazione di dati con questa estensione sono disponibili nella sezione Esempi di questo articolo.

Per usare l'estensione nell'istanza azure_storage del server flessibile Database di Azure per PostgreSQL, è necessario consentire l'estensione, caricarne la libreria e creare l'estensione.

Panoramica della procedura

Identificare gli account Archiviazione di Azure con cui si vuole che gli utenti dell'estensione azure_storage interagiscano.
Decidere quale tipo di autorizzazione si vuole usare per le richieste effettuate sul servizio BLOB di ognuno di questi account Archiviazione di Azure. azure_storage l'estensione supporta l'autorizzazione con chiave condivisa e l'autorizzazione con Microsoft Entra ID. Di questi due tipi di autorizzazione, Microsoft Entra ID offre maggiore sicurezza e facilità d'uso tramite chiave condivisa ed è quello consigliato da Microsoft. Per soddisfare i prerequisiti necessari in ogni caso, seguire le istruzioni nelle sezioni corrispondenti:
- Autorizzazione con Microsoft Entra ID o
- Autorizzazione con chiave condivisa.
Includere azure_storage in shared_preload_libraries:

shared_preload_libraries Poiché è statico, il server deve essere riavviato per rendere effettiva una modifica:

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)

shared_preload_libraries Poiché è statico, il server deve essere riavviato per rendere effettiva una modifica:

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

Includere azure_storage in 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 il client delle preferenze, ad esempio psql, pgAdmin e così via, connettersi a qualsiasi database nell'istanza di Database di Azure per PostgreSQL server flessibile. Per creare tutti gli oggetti SQL (tabelle, tipi, funzioni, viste e così via) con cui è possibile usare l'estensione azure_storage per interagire con istanze di account Archiviazione di Azure, eseguire l'istruzione seguente:
```
CREATE EXTENSION azure_storage;
```
Usando le azure_storage.account_* funzioni, aggiungere riferimenti a Archiviazione di Azure account a cui si vuole consentire agli utenti o ai ruoli postgreSQL di accedere con l'estensione azure_storage . Tali riferimenti includono il nome dell'account Archiviazione di Azure a cui viene fatto riferimento e il tipo di autenticazione da usare durante l'interazione con l'account Archiviazione di Azure. A seconda del tipo di autenticazione selezionato, potrebbe essere necessario specificare anche altri parametri, ad esempio la chiave di accesso dell'account Archiviazione di Azure o il token di firma di accesso condiviso.

Importante

Per i tipi di autenticazione per i quali è necessario specificare una chiave di accesso dell'account Archiviazione di Azure, si noti che le chiavi di accesso Archiviazione di Azure sono simili a una password radice per l'account di archiviazione. Prestare sempre attenzione a proteggerli. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro. azure_storage l'estensione archivia tali chiavi in una tabella azure_storage.accounts che può essere letta dai membri del pg_read_all_data ruolo.

Gli utenti a cui è concesso il azure_storage_admin ruolo possono interagire con la azure_storage.accounts tabella usando le funzioni seguenti:

azure_storage.account_add
azure_storage.account_list
azure_storage.account_remove
azure_storage.account_user_add
azure_storage.account_user_remove

Il azure_storage_admin ruolo è, per impostazione predefinita, concesso al azure_pg_admin ruolo.

Per usare l'autorizzazione con Microsoft Entra ID

Abilitare l'identità gestita assegnata dal sistema nell'istanza di Database di Azure per PostgreSQL server flessibile.

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"}}'

Riavviare l'istanza di Database di Azure per PostgreSQL server flessibile, dopo aver abilitato un'identità gestita assegnata dal sistema.
Assegnare le autorizzazioni di controllo degli accessi in base al ruolo per l'accesso ai dati BLOB nell'account Archiviazione di Azure all'identità gestita assegnata dal sistema dell'istanza di Database di Azure per PostgreSQL server flessibile.

Per usare l'autorizzazione con chiave condivisa

L'account Archiviazione di Azure deve disporre dell'opzione Consenti l'accesso alla chiave dell'account di archiviazione abilitata, ovvero non può avere la proprietà AllowSharedKeyAccess impostata su false.

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

Per passarlo alla funzione azure_storage.account_add, recuperare una delle due chiavi di accesso dell'account Archiviazione di Azure.

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

Funzioni

azure_storage.account_add

Funzione che consente di aggiungere un account di archiviazione e la chiave di accesso associata all'elenco di account di archiviazione a cui l'estensione azure_storage può accedere.

Se una chiamata precedente di questa funzione ha già aggiunto il riferimento a questo account di archiviazione, non aggiunge una nuova voce ma aggiorna invece la chiave di accesso della voce esistente.

Nota

Questa funzione non convalida se il nome dell'account di riferimento esiste o se è accessibile con la chiave di accesso fornita. Tuttavia, convalida che il nome dell'account di archiviazione sia valido, in base alle regole di convalida dei nomi imposte agli account di archiviazione di Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

È disponibile una versione di overload di questa funzione, che accetta un account_config parametro che incapsula il nome dell'account di Archiviazione di Azure a cui si fa riferimento e tutte le impostazioni necessarie, ad esempio il tipo di autenticazione, il tipo di account o le credenziali di archiviazione.

azure_storage.account_add(account_config jsonb);

Autorizzazioni

Deve essere un membro di azure_storage_admin.

Argomenti

account_name_p

text nome dell'account di archiviazione BLOB di Azure che contiene tutti gli oggetti: BLOB, file, code e tabelle. L'account di archiviazione fornisce uno spazio dei nomi univoco accessibile da qualsiasi parte del mondo tramite HTTPS.

account_key_p

text valore di una delle chiavi di accesso per l'account di archiviazione. Le chiavi di accesso dell'archiviazione BLOB di Azure sono simili a una password radice per l'account di archiviazione. Fare sempre attenzione a proteggere le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro. La chiave dell'account viene archiviata in una tabella accessibile solo dall'utente con privilegi avanzati. Gli utenti a cui è stato concesso il azure_storage_admin ruolo possono interagire con questa tabella tramite funzioni. Per visualizzare gli account di archiviazione aggiunti, usare la funzione azure_storage.account_list.

account_config

jsonbil nome dell'account Archiviazione di Azure e tutte le impostazioni necessarie, ad esempio il tipo di autenticazione, il tipo di account o le credenziali di archiviazione. È consigliabile usare le funzioni di utilità azure_storage.account_options_managed_identity, azure_storage.account_options_credentials o azure_storage.account_options per creare uno dei valori validi che devono essere passati come argomento.

Tipo restituito

VOID

azure_storage.account_options_managed_identity

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno di azure_storage.account_add ed è utile per produrre un valore valido per l'argomento, quando si usa un'identità account_config gestita assegnata dal sistema per interagire con l'account Archiviazione di Azure.

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

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

name

type

azure_storage.storage_type valore di uno dei tipi di archiviazione supportati. Solo il valore supportato è blob.

Tipo restituito

jsonb

azure_storage.account_options_credentials

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno di azure_storage.account_add ed è utile per produrre un valore valido per l'argomentoaccount_config, quando si usa una chiave di accesso Archiviazione di Azure per interagire con l'account Archiviazione di Azure.

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

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

name

credentials

type

azure_storage.storage_type valore di uno dei tipi di archiviazione supportati. Solo il valore supportato è blob.

Tipo restituito

jsonb

azure_storage.account_options

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno di azure_storage.account_add ed è utile per produrre un valore valido per l'argomentoaccount_config, quando si usa una chiave di accesso Archiviazione di Azure o un'identità gestita assegnata dal sistema per interagire con l'account Archiviazione di Azure.

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

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

name

auth_type

azure_storage.auth_type valore di uno dei tipi di archiviazione supportati. Solo i valori supportati sono access-keye managed-identity.

storage_type

azure_storage.storage_type valore di uno dei tipi di archiviazione supportati. Solo il valore supportato è blob.

credentials

Tipo restituito

jsonb

azure_storage.account_remove

Funzione che consente di rimuovere un account di archiviazione e la chiave di accesso associata dall'elenco di account di archiviazione a cui l'estensione azure_storage può accedere.

azure_storage.account_remove(account_name_p text);

Autorizzazioni

Deve essere un membro di azure_storage_admin.

Argomenti

account_name_p

Tipo restituito

VOID

azure_storage.account_user_add

Funzione che consente di concedere a un utente o a un ruolo PostgreSQL l'accesso a un account di archiviazione tramite le funzioni fornite dall'estensione azure_storage .

Nota

L'esecuzione di questa funzione ha esito positivo solo se l'account di archiviazione, il cui nome viene passato come primo argomento, è già stato creato usando azure_storage.account_add e se l'utente o il ruolo, il cui nome viene passato come secondo argomento, esiste già.

azure_storage.account_add(account_name_p text, user_p regrole);

Autorizzazioni

Deve essere un membro di azure_storage_admin.

Argomenti

account_name_p

user_p

regrole nome di un utente o di un ruolo PostgreSQL disponibile nel server.

Tipo restituito

VOID

azure_storage.account_user_remove

Funzione che consente di revocare un utente o un ruolo PostgreSQL all'accesso a un account di archiviazione tramite le funzioni fornite dall'estensione azure_storage .

Nota

L'esecuzione di questa funzione ha esito positivo solo se l'account di archiviazione il cui nome viene passato come primo argomento è già stato creato usando azure_storage.account_add e se l'utente o il ruolo il cui nome viene passato come secondo argomento esiste ancora. Quando un utente o un ruolo viene eliminato dal server, eseguendo DROP USER | ROLE, le autorizzazioni concesse per qualsiasi riferimento agli account Archiviazione di Azure vengono eliminate automaticamente.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Autorizzazioni

Deve essere un membro di azure_storage_admin.

Argomenti

account_name_p

user_p

regrole nome di un utente o di un ruolo PostgreSQL disponibile nel server.

Tipo restituito

VOID

azure_storage.account_list

Funzione che elenca i nomi degli account di archiviazione configurati tramite la funzione azure_storage.account_add , insieme agli utenti o ai ruoli PostgreSQL a cui sono concesse le autorizzazioni per interagire con tale account di archiviazione tramite le funzioni fornite dall'estensione azure_storage .

azure_storage.account_list();

Autorizzazioni

Deve essere un membro di azure_storage_admin.

Argomenti

Questa funzione non accetta argomenti.

Tipo restituito

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[])una tabella a quattro colonne con l'elenco di account Archiviazione di Azure aggiunti, il tipo di autenticazione usato per interagire con ogni account, il tipo di archiviazione e l'elenco di utenti o ruoli PostgreSQL a cui è concesso l'accesso.

azure_storage.blob_list

Funzione che elenca i nomi e altre proprietà (size, lastModified, eTag, contentType, contentEncoding e contentHash) di BLOB archiviati nel contenitore specificato dell'account di archiviazione di riferimento.

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

Autorizzazioni

L'utente o il ruolo che richiama questa funzione deve essere aggiunto all'elenco consentito per l'oggetto account_name a cui viene fatto riferimento eseguendo azure_storage.account_user_add. I membri di azure_storage_admin sono autorizzati automaticamente a fare riferimento a tutti gli account Archiviazione di Azure i cui riferimenti sono stati aggiunti usando azure_storage.account_add.

Argomenti

account_name

container_name

text nome di un contenitore. Un contenitore consente di organizzare un set di BLOB, in modo simile a una directory in un file system. Un account di archiviazione può contenere un numero illimitato di contenitori, ciascuno dei quali può archiviare un numero illimitato di BLOB. Un nome contenitore deve essere un nome DNS (Domain Name System) valido, perché fa parte dell'URI univoco usato per indirizzare il contenitore o i relativi BLOB. Quando si assegna un nome a un contenitore, assicurarsi di seguire queste regole.

L'URI per un contenitore è simile al seguente: https://myaccount.blob.core.windows.net/mycontainer

prefix

text se specificato, la funzione restituisce i BLOB i cui nomi iniziano con il valore fornito in questo parametro. Il valore predefinito è una stringa vuota.

Tipo restituito

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) una tabella con un record per BLOB restituito, incluso il nome completo del BLOB e altre proprietà.

path

text nome completo del BLOB.

bytes

bigint dimensioni del BLOB in byte.

last_modified

timestamp with time zonedata e ora dell'ultima modifica del BLOB. Le operazioni che comportano la modifica del BLOB, incluso un aggiornamento dei metadati o delle proprietà del Blob, comportano la modifica dell'ora dell'ultima modifica del Blob.

etag

text la proprietà ETag viene utilizzata per la concorrenza ottimistica durante gli aggiornamenti. Non è un timestamp perché esiste un'altra proprietà denominata Timestamp che archivia l'ultima volta che un record è stato aggiornato. Ad esempio, se si carica un'entità e si vuole aggiornarla, l'ETag deve corrispondere a ciò che è attualmente archiviato. L'impostazione dell'ETag appropriato è importante perché se sono presenti più utenti che modificano lo stesso elemento, non si vogliono sovrascrivere le modifiche dell'altro.

content_type

text tipo di contenuto specificato per il BLOB. Il tipo di contenuto predefinito è application/octet-stream.

content_encoding

textla proprietà Content-Encoding di un BLOB che Archiviazione di Azure consente di definire. Per il contenuto compresso, è possibile impostare la proprietà su Gzip. Quando il browser accede al contenuto, decomprime automaticamente il contenuto.

content_hash

text hash usato per verificare l'integrità del BLOB durante il trasporto. Quando si specifica questa intestazione, il servizio di archiviazione controlla l'hash fornito con un hash calcolato dal contenuto. Se i due hash non corrispondono, l'operazione non riesce con codice di errore 400 (richiesta non valida).

azure_storage.blob_get

Funzione che consente l'importazione di dati. Scarica un file da un contenitore BLOB in un account Archiviazione di Azure. Converte quindi il contenuto in righe, che possono essere utilizzate ed elaborate con costrutti di linguaggio SQL. Questa funzione aggiunge il supporto per filtrare e modificare i dati recuperati dal contenitore BLOB prima di importarli.

Nota

Prima di tentare di accedere al contenitore per l'account di archiviazione di riferimento, questa funzione controlla se i nomi dell'account di archiviazione e del contenitore passati come argomenti sono validi in base alle regole di convalida dei nomi imposte agli account di archiviazione di Azure. Se uno di essi non è valido, viene generato un errore.

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

È disponibile una versione di overload di questa funzione, che accetta un rec parametro che consente di definire facilmente il record di formato di output.

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

Autorizzazioni

Argomenti

account_name

container_name

L'URI per un contenitore è simile al seguente: https://myaccount.blob.core.windows.net/mycontainer

path

text nome completo del BLOB.

Rec

anyelement definizione della struttura di output del record.

decodificatore

text specifica del formato BLOB. Può essere impostato su uno dei valori seguenti:

Formato	Predefinita	Descrizione
`auto`	`true`	Deduce il valore in base all'ultima serie di caratteri assegnati al nome del BLOB. Se il nome del BLOB termina con `.csv` o `.csv.gz`, presuppone `csv`. Se termina con `.tsv` o `.tsv.gz`, presuppone `tsv`. Se termina con `.json`, `.json.gz.xml`, `.xml.gz`, `.txt`, o `.txt.gz`, presuppone `text`.
`csv`		Formato di valori delimitati da virgole usato da PostgreSQL COPY.
`tsv`		Valori delimitati da tabulazioni, il formato predefinito di PostgreSQL COPY.
`binary`		Formato di copia di PostgreSQL binario.
`text` \| `xml` \| `json`		File contenente un singolo valore di testo.

compressione

text specifica del tipo di compressione. Può essere impostato su uno dei valori seguenti:

Formato	Predefinita	Descrizione
`auto`	`true`	Deduce il valore in base all'ultima serie di caratteri assegnati al nome del BLOB. Se il nome del BLOB termina con `.gz`, presuppone `gzip`. In caso contrario, presuppone `none`.
`gzip`		Forza l'uso del decodificatore gzip per decomprimere il BLOB.
`none`		Forza a trattare il BLOB come uno che non richiede la decompressione.

L'estensione non supporta altri tipi di compressione.

opzioni

jsonb impostazioni che definiscono la gestione di intestazioni personalizzate, separatori personalizzati, caratteri di escape e così via. options influisce sul comportamento di questa funzione in modo simile al modo in cui le opzioni che è possibile passare al COPY comando in PostgreSQL ne influiscono sul comportamento.

Tipo restituito

SETOF record SETOF anyelement

azure_storage.blob_put

Funzione che consente di esportare i dati caricando i file in un contenitore BLOB in un account Archiviazione di Azure. Il contenuto dei file viene generato dalle righe in PostgreSQL.

Nota

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

È disponibile una versione di overload della funzione contenente encoder il parametro che consente di specificare il codificatore da usare quando non può essere dedotto dall'estensione del path parametro o quando si vuole eseguire l'override di quello dedotto.

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

È disponibile una versione di overload della funzione che contiene anche un compression parametro che consente di specificare la compressione da usare quando non può essere dedotto dall'estensione del path parametro o quando si vuole eseguire l'override di quello dedotto.

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

Esiste una versione di overload della funzione che contiene anche un options parametro per la gestione di intestazioni personalizzate, separatori personalizzati, caratteri di escape e così via. options Funziona in modo analogo alle opzioni che possono essere passate al COPY comando in PostgreSQL.

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

Autorizzazioni

Argomenti

account_name

container_name

L'URI per un contenitore è simile al seguente: https://myaccount.blob.core.windows.net/mycontainer

path

text nome completo del BLOB.

tupla

record definizione della struttura di output del record.

codificatore

text specifica del formato BLOB. Può essere impostato su uno dei valori seguenti:

Formato	Predefinita	Descrizione
`auto`	`true`	Deduce il valore in base all'ultima serie di caratteri assegnati al nome del BLOB. Se il nome del BLOB termina con `.csv` o `.csv.gz`, presuppone `csv`. Se termina con `.tsv` o `.tsv.gz`, presuppone `tsv`. Se termina con `.json`, `.json.gz.xml`, `.xml.gz`, `.txt`, o `.txt.gz`, presuppone `text`.
`csv`		Formato di valori delimitati da virgole usato da PostgreSQL COPY.
`tsv`		Valori delimitati da tabulazioni, il formato predefinito di PostgreSQL COPY.
`binary`		Formato di copia di PostgreSQL binario.
`text` \| `xml` \| `json`		File contenente un singolo valore di testo.

compressione

text specifica del tipo di compressione. Può essere impostato su uno dei valori seguenti:

Formato	Predefinita	Descrizione
`auto`	`true`	Deduce il valore in base all'ultima serie di caratteri assegnati al nome del BLOB. Se il nome del BLOB termina con `.gz`, presuppone `gzip`. In caso contrario, presuppone `none`.
`gzip`		Forza l'uso del decodificatore gzip per decomprimere il BLOB.
`none`		Forza a trattare il BLOB come uno che non richiede la decompressione.

L'estensione non supporta altri tipi di compressione.

opzioni

Tipo restituito

VOID

azure_storage.options_csv_get

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno blob_getdi ed è utile per decodificare il contenuto di un file 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);

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

delimiter

text carattere che separa le colonne all'interno di ogni riga (riga) del file. Deve essere un singolo carattere a 1 byte. Anche se questa funzione supporta delimitatori di un numero qualsiasi di caratteri, se si tenta di usare più di un singolo carattere a 1 byte, PostgreSQL restituisce un COPY delimiter must be a single one-byte character errore.

null_string

text stringa che rappresenta un valore Null. Il valore predefinito è \N (barra rovesciata-N) in formato testo e una stringa vuota senza virgolette in formato CSV. È possibile preferire una stringa vuota anche in formato testo per i casi in cui non si vogliono distinguere i valori Null dalle stringhe vuote.

boolean flag che indica se il file contiene una riga di intestazione con i nomi di ogni colonna nel file. Nell'output la riga iniziale contiene i nomi delle colonne della tabella.

Offerta

text carattere di virgolette da utilizzare quando viene racchiuso tra virgolette un valore di dati. Il valore predefinito è virgolette doppie. Deve essere un singolo carattere a 1 byte. Anche se questa funzione supporta delimitatori di un numero qualsiasi di caratteri, se si tenta di usare più di un singolo carattere a 1 byte, PostgreSQL restituisce un COPY quote must be a single one-byte character errore.

escape

text carattere che deve essere visualizzato prima di un carattere di dati corrispondente al valore quote. Il valore predefinito è uguale al valore quote (in modo che il carattere tra virgolette venga raddoppiato se viene visualizzato nei dati). Deve essere un singolo carattere a 1 byte. Anche se questa funzione supporta delimitatori di un numero qualsiasi di caratteri, se si tenta di usare più di un singolo carattere a 1 byte, PostgreSQL restituisce un COPY escape must be a single one-byte character errore.

force_not_null

text[] non corrispondono ai valori delle colonne specificate rispetto alla stringa Null. Nel caso predefinito in cui la stringa Null è vuota, significa che i valori vuoti vengono letti come stringhe di lunghezza zero anziché null, anche quando non sono racchiusi tra virgolette.

force_null

text[] associare i valori delle colonne specificate alla stringa Null, anche se tra virgolette e, se viene trovata una corrispondenza, impostare il valore su NULL. Nel caso predefinito in cui la stringa Null è vuota, converte una stringa vuota tra virgolette in NULL.

content_encoding

text nome della codifica con cui viene codificato il file. Se l'opzione viene omessa, viene usata la codifica client corrente.

Tipo restituito

jsonb

azure_storage.options_copy

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno blob_getdi . Funge da funzione helper per 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);

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

delimiter

null_string

di autorizzazione

boolean flag che indica se il file contiene una riga di intestazione con i nomi di ogni colonna nel file. Nell'output la riga iniziale contiene i nomi delle colonne della tabella.

Offerta

escape

force_quote

text[] forza l'uso delle virgolette per tutti i valori non NULL in ogni colonna specificata. L'output NULL non è mai racchiuso tra virgolette. Se * è specificato, i valori non NULL vengono racchiusi tra virgolette in tutte le colonne.

force_not_null

force_null

content_encoding

text nome della codifica con cui viene codificato il file. Se l'opzione viene omessa, viene usata la codifica client corrente.

Tipo restituito

jsonb

azure_storage.options_tsv

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno blob_getdi ed è utile per decodificare il contenuto di un file tsv.

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

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

delimiter

null_string

content_encoding

text nome della codifica con cui viene codificato il file. Se l'opzione viene omessa, viene usata la codifica client corrente.

Tipo restituito

jsonb

azure_storage.options_binary

Funzione che funge da funzione di utilità, che può essere chiamata come parametro all'interno blob_getdi ed è utile per decodificare il contenuto di un file binario.

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

Autorizzazioni

Qualsiasi utente o ruolo può richiamare questa funzione.

Argomenti

content_encoding

text nome della codifica con cui viene codificato il file. Se l'opzione viene omessa, viene usata la codifica client corrente.

Tipo restituito

jsonb

Possibili errori

ERRORE: azure_storage: L'autorizzazione non è sufficiente per eseguire l'operazione richiesta

Quando si esegue una delle funzioni che interagiscono con Archiviazione di Azure (azure_storage.blob_listo azure_storage.blob_get azure_storage.blob_put) e l'identità gestita assegnata dal sistema non vengono concesse le autorizzazioni o i ruoli del piano dati adeguati (in genere un minimo di Collaboratore ai dati del BLOB di archiviazione per azure_storage.blob_put e almeno lettore di dati BLOB di archiviazione per le altre due funzioni).

Può anche essere il caso in cui siano già state concesse le autorizzazioni minime necessarie, ma non sono ancora effettive. La propagazione di tali autorizzazioni può richiedere alcuni minuti.

ERRORE: azure_storage: credenziali di archiviazione mancanti

Quando si esegue una delle funzioni che interagiscono con Archiviazione di Azure (azure_storage.blob_listo azure_storage.blob_get azure_storage.blob_put) e le credenziali con cui si vuole che l'estensione esegua l'autenticazione con l'account di archiviazione non siano registrate usando azure_storage.account_add.

ERRORE: azure_storage: errore interno durante la connessione

Quando l'istanza del server flessibile non riesce a raggiungere l'account di archiviazione di destinazione. Ciò può verificarsi nei casi seguenti:

L'account di archiviazione non esiste.
La configurazione di rete non consente al traffico originato dall'istanza del server flessibile di raggiungere l'account di archiviazione. Ad esempio, quando l'istanza del server flessibile viene distribuita con la rete di accesso pubblico e l'account di archiviazione è accessibile solo tramite endpoint privati.

Quando l'identità gestita assegnata dal sistema non è abilitata nell'istanza del server flessibile.

ERRORE: azure_storage: formato delle credenziali di archiviazione non valido

Quando l'identità gestita assegnata dal sistema è abilitata nell'istanza del server flessibile, ma il server non è stato riavviato dopo l'abilitazione.

ERRORE: azure_storage: l'user_or_role utente corrente non è autorizzato a usare l'account <> <di archiviazione account_name>

Quando si esegue una delle funzioni che interagiscono con Archiviazione di Azure (azure_storage.blob_list, azure_storage.blob_get o azure_storage.blob_put) con un utente o un ruolo di cui non è membro e non viene concessa autorizzazioni, usando azure_storage.account_user_add, per usare l'account di azure_storage_admin archiviazione di riferimento.

Esempi

Prima di poter eseguire gli esempi seguenti, è necessario soddisfare i prerequisiti seguenti:

Creare un account di archiviazione di Azure. Per creare un account Archiviazione di Azure, se non ne è già disponibile uno, personalizzare i valori di <resource_group>, <location><account_name>, e <container_name>ed eseguire il comando dell'interfaccia della riga di comando di Azure seguente:

resource_group=<resource_group>
location=<location>
storage_account=<account_name>
blob_container=<container_name>
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

Creare un contenitore BLOB. Per creare il contenitore BLOB, eseguire l'interfaccia della riga di comando di Azure seguente:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Recuperare una delle due chiavi di accesso assegnate all'account di archiviazione. Assicurarsi di copiare il valore del access_key perché è necessario passarlo come argomento a azure_storage.account_add in un passaggio successivo. Per recuperare la prima delle due chiavi di accesso, eseguire il comando seguente dell'interfaccia della riga di comando di 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
```

Scaricare il file con il set di dati usato durante gli esempi e caricarlo nel contenitore BLOB. Per scaricare il file con il set di dati, eseguire il comando seguente dell'interfaccia della riga di comando di 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

È possibile elencare i contenitori o i BLOB archiviati in essi per un account di archiviazione specifico, ma solo se all'utente o al ruolo PostgreSQL viene concessa l'autorizzazione per il riferimento a tale account di archiviazione usando azure_storage.account_user_add. Ai membri del azure_storage_admin ruolo viene concesso questo privilegio su tutti gli account Archiviazione di Azure aggiunti usando azure_storage.account_add. Per impostazione predefinita, al ruolo vengono concessi azure_storage_admin solo i membri di azure_pg_admin .

Creare una tabella in cui vengono caricati i dati

Verrà ora creata la tabella in cui si importa il contenuto del file CSV caricato nell'account di archiviazione. A tale scopo, connettersi all'istanza di Database di Azure per PostgreSQL server flessibile usando PgAdmin, psqlo il client delle preferenze ed eseguire l'istruzione seguente:

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

Aggiungere la chiave di accesso dell'account di archiviazione

Questo esempio illustra come aggiungere un riferimento a un account di archiviazione, insieme alla chiave di accesso dell'account di archiviazione necessario per accedere al contenuto tramite la funzionalità fornita dall'estensione nell'istanza azure_storage di Database di Azure per PostgreSQL server flessibile.

<account_name> deve essere impostato sul nome dell'account di archiviazione. Se sono stati usati gli script precedenti, questo valore deve corrispondere a qualsiasi valore impostato sulla variabile di ambiente storage_account in tali script.

Analogamente, <access_key> deve essere impostato sul valore recuperato dall'account di archiviazione.

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

Suggerimento

Se si desidera recuperare il nome dell'account di archiviazione e una delle relative chiavi di accesso dal portale di Azure, cercare l'account di archiviazione, nel menu delle risorse selezionare Chiavi di accesso, copiare il nome dell'account di archiviazione e copiare la chiave dalla sezione key1 (è necessario selezionare Mostra accanto alla chiave per prima).

Rimuovere il riferimento all'account di archiviazione

In questo esempio viene illustrato come rimuovere qualsiasi riferimento a un account di archiviazione, in modo che nessun utente nel database corrente possa usare la azure_storage funzionalità di estensione per accedere a tale account di archiviazione.

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

Concedere l'accesso a un utente o a un ruolo nel riferimento all'archiviazione BLOB di Azure

Questo esempio illustra come concedere l'accesso a un utente o a un ruolo denominato <regular_user>, in modo che tale utente PostgreSQL possa usare l'estensione azure_storage per accedere ai BLOB archiviati nei contenitori ospitati dall'account di archiviazione di Azure di riferimento.

<regular_user> deve essere impostato sul nome di un utente o di un ruolo esistente.

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

Elencare tutti i riferimenti agli account di archiviazione di Azure

Questo esempio illustra come individuare gli account di archiviazione di Azure a cui l'estensione azure_storage può fare riferimento in questo database, insieme al tipo di autenticazione usato per accedere a ogni account di archiviazione e quali utenti o ruoli vengono concessi, tramite la funzione azure_storage.account_user_add , per accedere all'account di archiviazione di Azure tramite la funzionalità fornita dall'estensione.

SELECT * FROM azure_storage.account_list();

Revocare l'accesso a un utente o a un ruolo nel riferimento all'archiviazione BLOB di Azure

Questo esempio illustra come revocare l'accesso a un utente o a un ruolo denominato <regular_user>, in modo che tale utente PostgreSQL non possa usare l'estensione azure_storage per accedere ai BLOB archiviati in contenitori ospitati dall'account di archiviazione di Azure di riferimento.

<regular_user> deve essere impostato sul nome di un utente o di un ruolo esistente.

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

Elencare tutti i BLOB in un contenitore

Questo esempio illustra come elencare tutti i BLOB esistenti all'interno del contenitore <container_name> dell'account <account_name>di archiviazione .

<container_name> deve essere impostato sul nome del contenitore BLOB. Se sono stati usati gli script precedenti, questo valore deve corrispondere a qualsiasi valore impostato sulla variabile di ambiente blob_container in tali script.

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

Elencare gli oggetti con prefisso di nome BLOB specifico

Questo esempio illustra come elencare tutti i BLOB esistenti all'interno del contenitore <container_name> dell'account <account_name>di archiviazione , il cui nome BLOB inizia con <blob_name_prefix>.

<blob_name_prefix> deve essere impostato su qualsiasi prefisso che si vuole che i BLOB enumerati includano nei nomi. Se si desidera restituire tutti i BLOB, è possibile impostare questo parametro su una stringa vuota o non specificare nemmeno un valore per questo parametro, nel qual caso il valore predefinito è una stringa vuota.

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

In alternativa, è possibile usare la sintassi seguente:

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

Leggere il contenuto da un BLOB in un contenitore

La blob_get funzione recupera il contenuto di un BLOB specifico (events.csv in questo caso), nel contenitore <container_name> di riferimento dell'archiviazione <account_name> . Per blob_get sapere come analizzare i dati, è possibile passare un valore nel formato NULL::table_name, dove table_name fa riferimento a una tabella il cui schema corrisponde a quello del BLOB letto. Nell'esempio si riferisce alla events tabella creata all'inizio.

<blob_name> deve essere impostato sul percorso completo del BLOB di cui si vuole leggere il contenuto.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
LIMIT 5;

In alternativa, è possibile definire in modo esplicito lo schema del risultato usando la AS clausola dopo la funzione blob_get .

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','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;

Usare l'opzione decodificatore

In questo esempio viene illustrato l'uso dell'opzione decoder . In genere il formato viene dedotto dall'estensione del file, ma quando il contenuto del file non ha un'estensione corrispondente, è possibile passare l'argomento decodificatore.

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

Usare la compressione con l'opzione decodificatore

Questo esempio illustra come applicare l'uso della compressione gzip in un BLOB compresso gzip il cui nome non termina con un'estensione .gz.

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

Importare contenuto filtrato e modificare prima del caricamento dall'oggetto formato CSV

Questo esempio illustra la possibilità di filtrare e modificare il contenuto importato dal BLOB, prima di caricarlo in una tabella SQL.

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Eseguire query sul contenuto dal file con intestazioni, separatori personalizzati, caratteri di escape

In questo esempio viene illustrato come usare separatori personalizzati e caratteri di escape passando il risultato di options_copy all'argomento options .

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Query di aggregazione sul contenuto di un BLOB

Questo esempio illustra come eseguire operazioni di aggregazione sulle informazioni archiviate in un contenitore BLOB, senza la necessità di importare il contenuto del BLOB nelle tabelle PostgreSQL.

SELECT event_type, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Importare dati usando un'istruzione COPY

L'esempio seguente illustra l'importazione di dati da un BLOB denominato events.csv che si trova nel contenitore <container_name> BLOB nell'account <account_name>Archiviazione di Azure , tramite il COPY comando :

Creare una tabella che corrisponda allo schema del file di origine:

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

Usare un'istruzione COPY per copiare i dati nella tabella di destinazione. Specificare che la prima riga contiene intestazioni di colonna.
```
COPY events
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/events.csv'
WITH (FORMAT 'csv', header);
```

Scrivere contenuto in un BLOB in un contenitore

La blob_put funzione compone il contenuto di un BLOB specifico (eventscopy.csv in questo caso) e lo carica nel contenitore <container_name> di riferimento dell'archiviazione <account_name> . Questo esempio usa blob_get per costruire un set di cinque righe, che vengono quindi passate alla blob_put funzione di aggregazione che le carica come BLOB denominato eventscopy.csv.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'eventscopy.csv'
        , top_5_events)
FROM (SELECT * FROM azure_storage.blob_get
                     ('<account_name>'
                     ,'<container_name>'
                     ,'events.csv'
                     , NULL::events) LIMIT 5) AS top_5_events;

Esportare dati usando un'istruzione COPY

L'esempio seguente illustra l'esportazione di dati da una tabella denominata events, in un BLOB denominato events_exported.csv che risiede nel contenitore <container_name> BLOB nell'account <account_name>Archiviazione di Azure , tramite il COPY comando :

Creare una tabella che corrisponda allo schema del file di origine:

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

Caricare i dati nella tabella. Eseguire istruzioni INSERT per popolarlo con diverse righe sintetiche oppure usare l'esempio di importazione dei dati usando un'istruzione COPY per popolarlo con il contenuto del set di dati di esempio.
Usare un'istruzione COPY per copiare i dati nella tabella di destinazione. Specificare che la prima riga contiene intestazioni di colonna.
```
COPY events
TO 'https://<account_name>.blob.core.windows.net/<container_name>/events_exported.csv'
WITH (FORMAT 'csv', header);
```

Condividi tramite

Importare ed esportare dati usando l'estensione azure_storage in Database di Azure per PostgreSQL - Server flessibile

Panoramica della procedura

Per usare l'autorizzazione con Microsoft Entra ID

Per usare l'autorizzazione con chiave condivisa

Funzioni

azure_storage.account_add

Autorizzazioni

Argomenti

account_name_p

account_key_p

account_config

Tipo restituito

azure_storage.account_options_managed_identity

Autorizzazioni

Argomenti

name

type

Tipo restituito

azure_storage.account_options_credentials

Autorizzazioni

Argomenti

name

credentials

type

Tipo restituito

azure_storage.account_options

Autorizzazioni

Argomenti

name

auth_type

storage_type

credentials

Tipo restituito

azure_storage.account_remove

Autorizzazioni

Argomenti

account_name_p

Tipo restituito

azure_storage.account_user_add

Autorizzazioni

Argomenti

account_name_p

user_p

Tipo restituito

azure_storage.account_user_remove

Autorizzazioni

Argomenti

account_name_p

user_p

Tipo restituito

azure_storage.account_list

Autorizzazioni

Argomenti

Tipo restituito

azure_storage.blob_list

Autorizzazioni

Argomenti

account_name

container_name

prefix

Tipo restituito

path

bytes

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Autorizzazioni

Argomenti

account_name

container_name

path

Rec

decodificatore

compressione

opzioni

Tipo restituito