Importera och exportera data med hjälp av azure_storage-tillägget i Azure Database for PostgreSQL – flexibel server

Artikel
01/02/2025

GÄLLER FÖR: Azure Database for PostgreSQL – flexibel server

Med tillägget azure_storage kan du importera eller exportera data i flera filformat, direkt mellan Azure Storage-konton och en instans av Azure Database for PostgreSQL – flexibel server.

Exempel på dataexport och import med det här tillägget finns i avsnittet Exempel i den här artikeln.

Om du vill använda azure_storage tillägget på din flexibla Azure Database for PostgreSQL-serverinstans måste du tillåta tillägget, läsa in dess bibliotek och skapa tillägget.

Översikt över proceduren

Identifiera de Azure Storage-konton som du vill att användarna av azure_storage tillägget ska interagera med.
Bestäm vilken typ av auktorisering du vill använda för begäranden som görs mot blobtjänsten för vart och ett av dessa Azure Storage-konton. azure_storage -tillägget stöder auktorisering med delad nyckel och auktorisering med Microsoft Entra-ID. Av dessa två typer av auktorisering ger Microsoft Entra ID överlägsen säkerhet och användarvänlighet över delad nyckel, och är den som Microsoft rekommenderar. Följ anvisningarna i motsvarande avsnitt för att uppfylla de krav som krävs i varje enskilt fall:
- Auktorisering med Microsoft Entra-ID, eller
- Auktorisering med delad nyckel.
Inkludera azure_storage i shared_preload_libraries:

Eftersom är shared_preload_libraries statisk måste servern startas om för att en ändring ska börja gälla:

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)

Eftersom är shared_preload_libraries statisk måste servern startas om för att en ändring ska börja gälla:

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

Inkludera azure_storage i 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)

Använd klienten som du föredrar (till exempel psql, pgAdmin osv.) och anslut till valfri databas i din instans av Azure Database for PostgreSQL – flexibel server. Kör följande instruktion för att skapa alla SQL-objekt (tabeller, typer, funktioner, vyer osv.) med vilka du kan använda azure_storage tillägget för att interagera med instanser av Azure Storage-konton:
```
CREATE EXTENSION azure_storage;
```
Med hjälp av azure_storage.account_* funktionerna lägger du till referenser till Azure Storage-konton som du vill ge PostgreSQL-användare eller roller åtkomst med azure_storage tillägget. Dessa referenser inkluderar namnet på det Azure Storage-konto som refereras och den autentiseringstyp som ska användas när du interagerar med Azure Storage-kontot. Beroende på vilken autentiseringstyp som valts kan du också behöva ange några andra parametrar, till exempel åtkomstnyckeln för Azure Storage-kontot eller SAS-token.

Viktigt!

För autentiseringstyper där du måste ange en åtkomstnyckel för Azure Storage-kontot bör du observera att dina Åtkomstnycklar för Azure Storage liknar ett rotlösenord för ditt lagringskonto. Var alltid noga med att skydda dem. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt. azure_storage -tillägget lagrar dessa nycklar i en tabell azure_storage.accounts som kan läsas av medlemmar i pg_read_all_data rollen.

Användare som beviljats azure_storage_admin rollen kan interagera med tabellen med azure_storage.accounts hjälp av följande funktioner:

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

Rollen azure_storage_admin tilldelas som standard rollen azure_pg_admin .

Så här använder du auktorisering med Microsoft Entra-ID

Aktivera systemtilldelad hanterad identitet på din instans av Azure Database for PostgreSQL – flexibel server.

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

Starta om instansen av Azure Database for PostgreSQL – flexibel server när du har aktiverat en systemtilldelad hanterad identitet på den.
Tilldela rollbaserad åtkomstkontroll (RBAC) behörigheter för åtkomst till blobdata, på Azure Storage-kontot, till den systemtilldelade hanterade identiteten för din instans av Azure Database for PostgreSQL – flexibel server.

Så här använder du auktorisering med delad nyckel

Ditt Azure Storage-konto måste ha Tillåt åtkomst till lagringskontonyckel aktiverat (det vill: den kan inte ha egenskapen AllowSharedKeyAccess inställd på false).

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

Om du vill skicka den till funktionen azure_storage.account_add hämtar du någon av de två åtkomstnycklarna för Azure Storage-kontot.

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

Funktioner

azure_storage.account_add

Funktion som gör det möjligt att lägga till ett lagringskonto och dess associerade åtkomstnyckel i listan över lagringskonton som azure_storage tillägget kan komma åt.

Om en tidigare anrop av den här funktionen redan har lagt till referensen till det här lagringskontot, lägger den inte till en ny post utan uppdaterar i stället åtkomstnyckeln för den befintliga posten.

Kommentar

Den här funktionen verifierar inte om det refererade kontonamnet finns eller om det är tillgängligt med den angivna åtkomstnyckeln. Den verifierar dock att namnet på lagringskontot är giltigt, enligt de namngivningsverifieringsregler som införts för Azure-lagringskonton.

azure_storage.account_add(account_name_p text, account_key_p text);

Det finns en överbelastad version av den här funktionen som accepterar en account_config parameter som kapslar in namnet på det refererade Azure Storage-kontot och alla nödvändiga inställningar som autentiseringstyp, kontotyp eller lagringsautentiseringsuppgifter.

azure_storage.account_add(account_config jsonb);

Behörigheter

Måste vara medlem i azure_storage_admin.

Argument

account_name_p

text namnet på Azure Blob Storage-kontot som innehåller alla dina objekt: blobar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde som är tillgängligt var som helst i världen via HTTPS.

account_key_p

text värdet för en av åtkomstnycklarna för lagringskontot. Åtkomstnycklarna för Azure Blob Storage liknar ett rotlösenord för ditt lagringskonto. Var alltid noga med att skydda dina åtkomstnycklar. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt. Kontonyckeln lagras i en tabell som endast är tillgänglig för superanvändaren. Användare som beviljats azure_storage_admin rollen kan interagera med den här tabellen via funktioner. Om du vill se vilka lagringskonton som läggs till använder du funktionen azure_storage.account_list.

account_config

jsonb Namnet på Azure Storage-kontot och alla nödvändiga inställningar som autentiseringstyp, kontotyp eller autentiseringsuppgifter för lagring. Vi rekommenderar att du använder verktygsfunktionerna azure_storage.account_options_managed_identity, azure_storage.account_options_credentials eller azure_storage.account_options för att skapa något av de giltiga värden som måste skickas som det här argumentet.

Returtyp

VOID

azure_storage.account_options_managed_identity

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i azure_storage.account_add, och är användbar för att skapa ett giltigt värde för account_config argumentet när du använder en systemtilldelad hanterad identitet för att interagera med Azure Storage-kontot.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

name

type

azure_storage.storage_type värdet för en av de typer av lagring som stöds. Endast värdet som stöds är blob.

Returtyp

jsonb

azure_storage.account_options_credentials

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i azure_storage.account_add, och är användbar för att skapa ett giltigt värde för account_config argumentet när du använder en Azure Storage-åtkomstnyckel för att interagera med Azure Storage-kontot.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

name

autentiseringsuppgifter

type

azure_storage.storage_type värdet för en av de typer av lagring som stöds. Endast värdet som stöds är blob.

Returtyp

jsonb

azure_storage.account_options

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i azure_storage.account_add, och är användbar för att skapa ett giltigt värde för account_config argumentet när du använder en Azure Storage-åtkomstnyckel eller ett system som tilldelats hanterad identitet för att interagera med Azure Storage-kontot.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

name

auth_type

azure_storage.auth_type värdet för en av de typer av lagring som stöds. Endast värden som stöds är access-key, och managed-identity.

storage_type

azure_storage.storage_type värdet för en av de typer av lagring som stöds. Endast värdet som stöds är blob.

autentiseringsuppgifter

Returtyp

jsonb

azure_storage.account_remove

Funktion som gör det möjligt att ta bort ett lagringskonto och dess associerade åtkomstnyckel från listan över lagringskonton som azure_storage tillägget kan komma åt.

azure_storage.account_remove(account_name_p text);

Behörigheter

Måste vara medlem i azure_storage_admin.

Argument

account_name_p

Returtyp

VOID

azure_storage.account_user_add

Funktion som gör det möjligt att bevilja en PostgreSQL-användare eller rollåtkomst till ett lagringskonto via de funktioner som tillhandahålls av azure_storage tillägget.

Kommentar

Körningen av den här funktionen lyckas bara om lagringskontot, vars namn skickas som det första argumentet, redan har skapats med hjälp av azure_storage.account_add, och om användaren eller rollen, vars namn skickas som det andra argumentet, redan finns.

azure_storage.account_add(account_name_p text, user_p regrole);

Behörigheter

Måste vara medlem i azure_storage_admin.

Argument

account_name_p

user_p

regrole namnet på en PostgreSQL-användare eller roll som är tillgänglig på servern.

Returtyp

VOID

azure_storage.account_user_remove

Funktion som gör det möjligt att återkalla en PostgreSQL-användare eller rollåtkomst till ett lagringskonto via de funktioner som tillhandahålls av azure_storage tillägget.

Kommentar

Körningen av den här funktionen lyckas bara om lagringskontot vars namn skickas som det första argumentet redan har skapats med hjälp av azure_storage.account_add och om den användare eller roll vars namn skickas som det andra argumentet fortfarande finns. När en användare eller roll tas bort från servern, genom att DROP USER | ROLEköra , elimineras även de behörigheter som beviljats för alla referenser till Azure Storage-konton automatiskt.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Behörigheter

Måste vara medlem i azure_storage_admin.

Argument

account_name_p

user_p

regrole namnet på en PostgreSQL-användare eller roll som är tillgänglig på servern.

Returtyp

VOID

azure_storage.account_list

Funktion som visar namnen på de lagringskonton som har konfigurerats via funktionen azure_storage.account_add , tillsammans med PostgreSQL-användare eller roller som har behörighet att interagera med lagringskontot via funktionerna i azure_storage tillägget.

azure_storage.account_list();

Behörigheter

Måste vara medlem i azure_storage_admin.

Argument

Den här funktionen tar inga argument.

Returtyp

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[]) en tabell med fyra kolumner med en lista över Azure Storage-konton som lagts till, vilken typ av autentisering som används för att interagera med varje konto, typen av lagring och listan över PostgreSQL-användare eller roller som beviljas åtkomst till det.

azure_storage.blob_list

Funktion som visar namn och andra egenskaper (storlek, lastModified, eTag, contentType, contentEncoding och contentHash) för blobar som lagras i den angivna containern för det refererade lagringskontot.

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

Behörigheter

Användare eller roll som anropar den här funktionen måste läggas till i listan över tillåtna för den account_name angivna genom att köra azure_storage.account_user_add. Medlemmar i får automatiskt referera till alla Azure Storage-konton vars referenser har lagts till med hjälp av azure_storage_admin azure_storage.account_add.

Argument

account_name

container_name

text namnet på en container. I en container finns en uppsättning med blobbar, ungefär som i en katalog i ett filsystem. Ett lagringskonto kan omfatta ett obegränsat antal containrar, och varje container kan lagra ett obegränsat antal blobar. Ett containernamn måste vara ett giltigt DNS-namn (Domain Name System), eftersom det utgör en del av den unika URI som används för att adressera containern eller dess blobar. När du namnger en container måste du följa dessa regler.

URI:n för en container liknar: https://myaccount.blob.core.windows.net/mycontainer

prefix

text när den anges returnerar funktionen de blobbar vars namn börjar med värdet som anges i den här parametern. Standardvärdet är en tom sträng.

Returtyp

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) en tabell med en post per blob returnerad, inklusive blobens fullständiga namn och några andra egenskaper.

path

text blobens fullständiga namn.

byte

bigint storleken på bloben i byte.

last_modified

timestamp with time zonedatum och tid då bloben senast ändrades. Alla åtgärder som ändrar bloben, inklusive en uppdatering av blobens metadata eller egenskaper, ändrar blobens senast ändrade tid.

etag

text ETag-egenskapen används för optimistisk samtidighet under uppdateringar. Det är inte en tidsstämpel eftersom det finns en annan egenskap som heter Tidsstämpel som lagrar den senaste gången en post uppdaterades. Om du till exempel läser in en entitet och vill uppdatera den måste ETag matcha det som för närvarande lagras. Det är viktigt att ange lämplig ETag eftersom du inte vill att flera användare ska skriva över varandras ändringar om du har flera användare som redigerar samma objekt.

content_type

text den innehållstyp som angetts för bloben. Standardinnehållstypen är application/octet-stream.

content_encoding

text egenskapen Content-Encoding för en blob som du kan definiera i Azure Storage. För komprimerat innehåll kan du ange egenskapen till Gzip. När webbläsaren kommer åt innehållet dekomprimerar den automatiskt innehållet.

content_hash

text den hash som används för att verifiera blobens integritet under transporten. När det här huvudet har angetts kontrollerar lagringstjänsten den angivna hashen med en som beräknas från innehåll. Om de två hashvärdena inte matchar misslyckas åtgärden med felkoden 400 (felaktig begäran).

azure_storage.blob_get

Funktion som gör det möjligt att importera data. Den laddar ned en eller flera filer från en blobcontainer i ett Azure Storage-konto. Sedan översätts innehållet till rader, som kan användas och bearbetas med SQL-språkkonstruktioner. Den här funktionen lägger till stöd för att filtrera och ändra data som hämtas från blobcontainern innan du importerar dem.

Kommentar

Innan du försöker komma åt containern för det angivna lagringskontot kontrollerar den här funktionen om namnen på lagringskontot och containern som skickas som argument är giltiga enligt de namngivningsverifieringsregler som införts för Azure-lagringskonton. Om någon av dem är ogiltig utlöses ett fel.

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

Det finns en överbelastad version av den här funktionen som accepterar en rec parameter som gör att du enkelt kan definiera utdataformatposten.

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

Behörigheter

Argument

account_name

container_name

URI:n för en container liknar: https://myaccount.blob.core.windows.net/mycontainer

path

text blobens fullständiga namn.

Rec

anyelement definitionen av postutdatastrukturen.

avkodare

text specifikationen för blobformatet. Kan anges till något av följande värden:

Format	Standardvärde	Beskrivning
`auto`	`true`	Härleder värdet baserat på den sista serien med tecken som tilldelats namnet på bloben. Om blobnamnet slutar med `.csv` eller `.csv.gz`förutsätter `csv`det . Om slutar med `.tsv` eller `.tsv.gz`förutsätter `tsv`det . Om slutar med `.json`, `.json.gz`, `.xml`, `.xml.gz`, `.txt`eller `.txt.gz`, förutsätter `text`det .
`csv`		Format för kommaavgränsade värden som används av PostgreSQL COPY.
`tsv`		Tabbavgränsade värden, standardformatet PostgreSQL COPY.
`binary`		Binärt PostgreSQL COPY-format.
`text` \| `xml` \| `json`		En fil som innehåller ett enda textvärde.

komprimering

text specifikationen av komprimeringstyp. Kan anges till något av följande värden:

Format	Standardvärde	Beskrivning
`auto`	`true`	Härleder värdet baserat på den sista serien med tecken som tilldelats namnet på bloben. Om blobnamnet slutar med `.gz`förutsätter `gzip`det . I annat fall förutsätter `none`det .
`gzip`		Tvingar fram användning av gzip-avkodare för att dekomprimera bloben.
`none`		Tvingar att behandla bloben som en som inte kräver dekomprimering.

Tillägget stöder inte andra komprimeringstyper.

alternativ

jsonb de inställningar som definierar hanteringen av anpassade rubriker, anpassade avgränsare, escape-tecken osv. options påverkar funktionens beteende på ett sätt som liknar hur de alternativ som du kan skicka till COPY kommandot i PostgreSQL påverkar dess beteende.

Returtyp

SETOF record SETOF anyelement

azure_storage.blob_put

Funktion som gör det möjligt att exportera data genom att ladda upp filer till en blobcontainer i ett Azure Storage-konto. Innehållet i filerna skapas från rader i PostgreSQL.

Kommentar

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

Det finns en överbelastad funktionsversion som innehåller encoder parametern som gör att du kan ange kodaren som ska användas när den inte kan härledas från parameterns tillägg path eller när du vill åsidosätta den härledda.

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

Det finns en överbelastad funktionsversion som också innehåller en compression parameter som gör att du kan ange vilken komprimering som ska användas när den inte kan härledas från parameterns tillägg path eller när du vill åsidosätta den härledda.

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

Det finns en överbelastad funktionsversion som också innehåller en options parameter för hantering av anpassade huvuden, anpassade avgränsare, escape-tecken osv. options fungerar på liknande sätt som de alternativ som kan skickas till COPY kommandot i PostgreSQL.

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

Behörigheter

Argument

account_name

container_name

URI:n för en container liknar: https://myaccount.blob.core.windows.net/mycontainer

path

text blobens fullständiga namn.

tuppel

record definitionen av postutdatastrukturen.

encoder

text specifikationen för blobformatet. Kan anges till något av följande värden:

Format	Standardvärde	Beskrivning
`auto`	`true`	Härleder värdet baserat på den sista serien med tecken som tilldelats namnet på bloben. Om blobnamnet slutar med `.csv` eller `.csv.gz`förutsätter `csv`det . Om slutar med `.tsv` eller `.tsv.gz`förutsätter `tsv`det . Om slutar med `.json`, `.json.gz`, `.xml`, `.xml.gz`, `.txt`eller `.txt.gz`, förutsätter `text`det .
`csv`		Format för kommaavgränsade värden som används av PostgreSQL COPY.
`tsv`		Tabbavgränsade värden, standardformatet PostgreSQL COPY.
`binary`		Binärt PostgreSQL COPY-format.
`text` \| `xml` \| `json`		En fil som innehåller ett enda textvärde.

komprimering

text specifikationen av komprimeringstyp. Kan anges till något av följande värden:

Format	Standardvärde	Beskrivning
`auto`	`true`	Härleder värdet baserat på den sista serien med tecken som tilldelats namnet på bloben. Om blobnamnet slutar med `.gz`förutsätter `gzip`det . I annat fall förutsätter `none`det .
`gzip`		Tvingar fram användning av gzip-avkodare för att dekomprimera bloben.
`none`		Tvingar att behandla bloben som en som inte kräver dekomprimering.

Tillägget stöder inte andra komprimeringstyper.

alternativ

Returtyp

VOID

azure_storage.options_csv_get

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i blob_getoch är användbar för att avkoda innehållet i en csv-fil.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

avgränsare

text tecknet som separerar kolumner inom varje rad (rad) i filen. Det måste vara ett enda 1 byte-tecken. Även om den här funktionen stöder avgränsare av valfritt antal tecken, rapporterar PostgreSQL ett COPY delimiter must be a single one-byte character fel om du försöker använda mer än ett enda 1 byte-tecken.

null_string

text strängen som representerar ett null-värde. Standardvärdet är \N (backslash-N) i textformat och en ociterad tom sträng i CSV-format. Du kanske föredrar en tom sträng även i textformat för fall där du inte vill skilja null-värden från tomma strängar.

boolean flagga som anger om filen innehåller en rubrikrad med namnen på varje kolumn i filen. Vid utdata innehåller den första raden kolumnnamnen från tabellen.

citera

text det citattecken som ska användas när ett datavärde citeras. Standardvärdet är dubbelcitat. Det måste vara ett enda 1 byte-tecken. Även om den här funktionen stöder avgränsare av valfritt antal tecken, rapporterar PostgreSQL ett COPY quote must be a single one-byte character fel om du försöker använda mer än ett enda 1 byte-tecken.

ESC

text det tecken som ska visas före ett datatecken som matchar CITAT-värdet. Standardvärdet är detsamma som OFFERT-värdet (så att citattecknet fördubblas om det visas i data). Det måste vara ett enda 1 byte-tecken. Även om den här funktionen stöder avgränsare av valfritt antal tecken, rapporterar PostgreSQL ett COPY escape must be a single one-byte character fel om du försöker använda mer än ett enda 1 byte-tecken.

force_not_null

text[] matcha inte de angivna kolumnernas värden mot null-strängen. I standardfallet där nullsträngen är tom innebär det att tomma värden läse som nolllängdssträngar i stället för null, även om de inte citeras.

force_null

text[] matcha de angivna kolumnernas värden mot null-strängen, även om de anges, och om en matchning hittas anger du värdet till NULL. I standardfallet där null-strängen är tom konverteras en citerad tom sträng till NULL.

content_encoding

text namnet på den kodning som filen är kodad med. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_copy

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i blob_get. Den fungerar som en hjälpfunktion för options_csv_get, options_tsv och 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);

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

avgränsare

null_string

sidhuvud

boolean flagga som anger om filen innehåller en rubrikrad med namnen på varje kolumn i filen. Vid utdata innehåller den första raden kolumnnamnen från tabellen.

citera

ESC

force_quote

text[] tvingar citat att användas för alla icke-NULL-värden i varje angiven kolumn. NULL-utdata citeras aldrig. Om * anges anges icke-NULL-värden i alla kolumner.

force_not_null

force_null

content_encoding

text namnet på den kodning som filen är kodad med. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_tsv

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i blob_getoch är användbar för att avkoda innehållet i en tsv-fil.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

avgränsare

null_string

content_encoding

text namnet på den kodning som filen är kodad med. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_binary

Funktion som fungerar som en verktygsfunktion, som kan anropas som en parameter i blob_getoch är användbar för att avkoda innehållet i en binär fil.

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

Behörigheter

Alla användare eller roller kan anropa den här funktionen.

Argument

content_encoding

text namnet på den kodning som filen är kodad med. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

Möjliga fel

FEL: azure_storage: Behörighet räcker inte för att utföra den begärda åtgärden

När du kör någon av de funktioner som interagerar med Azure Storage (azure_storage.blob_listeller azure_storage.blob_putazure_storage.blob_get ) och systemtilldelad hanterad identitet beviljas inte tillräckliga dataplansroller eller behörigheter (vanligtvis ett minimum av Storage Blob Data Contributor för azure_storage.blob_put och minst Storage Blob Data Reader för de andra två funktionerna).

Det kan också vara så att du redan har beviljat den lägsta behörighet som krävs, men de gäller inte ännu. Det kan ta några minuter innan dessa behörigheter sprids.

FEL: azure_storage: lagringsautentiseringsuppgifter saknas

När du kör någon av de funktioner som interagerar med Azure Storage (azure_storage.blob_listeller azure_storage.blob_putazure_storage.blob_get ) och de autentiseringsuppgifter som du vill att tillägget ska autentisera med lagringskontot registreras inte med .azure_storage.account_add

FEL: azure_storage: internt fel vid anslutning

När systemtilldelad hanterad identitet inte är aktiverad i instansen av flexibel server.

FEL: azure_storage: ogiltigt format för lagringsautentiseringsuppgifter

När den systemtilldelade hanterade identiteten är aktiverad på instansen av flexibel server, men servern inte har startats om när den har aktiverats.

FEL: azure_storage: aktuell användare <user_or_role> inte får använda lagringskontot <account_name>

När du kör någon av de funktioner som interagerar med Azure Storage (azure_storage.blob_listeller azure_storage.blob_putazure_storage.blob_get ) med en användare eller roll som inte är medlem i och inte beviljas behörigheter, med hjälp azure_storage.account_user_addav azure_storage_admin , för att använda det refererade lagringskontot.

Exempel

Du måste uppfylla följande krav innan du kan köra följande exempel:

skapa ett Azure Storage-konto Om du inte redan har ett Azure Storage-konto anpassar du värdena <resource_group>för , <location>, <account_name>och och <container_name>kör följande Azure CLI-kommando:

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

Skapa en blobcontainer. Kör följande Azure CLI för att skapa blobcontainern:

az storage container create --account-name $storage_account --name $blob_container -o tsv

Hämta en av de två åtkomstnycklar som tilldelats lagringskontot. Kontrollera att du kopierar värdet för din access_key eftersom du behöver skicka det som ett argument till azure_storage.account_add i ett efterföljande steg. Om du vill hämta den första av de två åtkomstnycklarna kör du följande Azure CLI-kommando:
```
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
```

Ladda ned filen med datauppsättningen som används under exemplen och ladda upp den till din blobcontainer. Om du vill ladda ned filen med datauppsättningen kör du följande Azure CLI-kommando:

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

Kommentar

Du kan visa containrar eller blobar som lagras i dem för ett visst lagringskonto, men bara om din PostgreSQL-användare eller roll beviljas behörighet för referensen till lagringskontot med hjälp av azure_storage.account_user_add. Medlemmar i rollen beviljas den här behörigheten azure_storage_admin för alla Azure Storage-konton som har lagts till med hjälp av azure_storage.account_add. Som standard beviljas endast medlemmar azure_pg_admin i azure_storage_admin rollen.

Skapa tabell där data läses in

Nu ska vi skapa tabellen där vi importerar innehållet i CSV-filen som vi laddade upp till lagringskontot. Det gör du genom att ansluta till din instans av Azure Database for PostgreSQL– flexibel server med hjälp av PgAdmin, psqleller klienten som du föredrar, och köra följande instruktion:

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

Lägga till åtkomstnyckel för lagringskonto

Det här exemplet illustrerar hur du lägger till en referens till ett lagringskonto, tillsammans med åtkomstnyckeln för det lagringskonto som krävs för att få åtkomst till dess innehåll via de funktioner som tillhandahålls av azure_storage tillägget i din instans av Azure Database for PostgreSQL – flexibel server.

<account_name> måste anges till namnet på ditt lagringskonto. Om du använde föregående skript bör det här värdet matcha det värde som du har angett till storage_account miljövariabeln i dessa skript.

<access_key> På samma sätt måste anges till det värde som du hämtade från ditt lagringskonto.

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

Dricks

Om du vill hämta lagringskontots namn och en av dess åtkomstnycklar från Azure Portal söker du efter ditt lagringskonto. På resursmenyn väljer du Åtkomstnycklar, kopierar lagringskontots namn och kopierar avsnittet Nyckel från key1 (du måste välja Visa bredvid nyckeln först).

Ta bort referens till lagringskonto

Det här exemplet visar hur du tar bort alla referenser till ett lagringskonto, så att ingen användare i den aktuella databasen kan använda tilläggsfunktionen azure_storage för att komma åt lagringskontot.

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

Bevilja åtkomst till en användare eller roll i Azure Blob Storage-referensen

Det här exemplet visar hur du beviljar åtkomst till en användare eller roll med namnet <regular_user>, så att en sådan PostgreSQL-användare kan använda azure_storage tillägget för att komma åt blobarna som lagras i containrar som hanteras av det refererade Azure Storage-kontot.

<regular_user> måste anges till namnet på en befintlig användare eller roll.

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

Visa en lista över alla referenser till Azure Storage-konton

Det här exemplet visar hur du tar reda på vilka Azure-lagringskonton azure_storage tillägget kan referera till i den här databasen, tillsammans med den typ av autentisering som används för att komma åt varje lagringskonto och vilka användare eller roller som beviljas behörighet, via funktionen azure_storage.account_user_add , för att få åtkomst till azure-lagringskontot via de funktioner som tillhandahålls av tillägget.

SELECT * FROM azure_storage.account_list();

Återkalla åtkomst från en användare eller roll i Azure Blob Storage-referensen

Det här exemplet visar hur du återkallar åtkomst från en användare eller roll med namnet <regular_user>, så att en sådan PostgreSQL-användare inte kan använda azure_storage tillägget för att komma åt blobarna som lagras i containrar som hanteras av det refererade Azure-lagringskontot.

<regular_user> måste anges till namnet på en befintlig användare eller roll.

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

Visa en lista över alla blobar i en container

Det här exemplet visar hur du listar alla befintliga blobar i containern <container_name> för lagringskontot <account_name>.

<container_name> måste anges till namnet på blobcontainern. Om du använde föregående skript ska det här värdet matcha det värde som du har angett till blob_container miljövariabeln i dessa skript.

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

Visa en lista över objekten med ett specifikt blobnamnsprefix

Det här exemplet visar hur du listar alla befintliga blobar i containern <container_name> för lagringskontot <account_name>, vars blobnamn börjar med <blob_name_prefix>.

<blob_name_prefix> ska anges till det prefix som du vill att blobarna ska innehålla i deras namn. Om du vill returnera alla blobar kan du ange den här parametern till en tom sträng eller inte ens ange ett värde för den här parametern, i vilket fall värdet som standard är en tom sträng.

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

Du kan också använda följande syntax:

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

Läsa innehåll från en blob i en container

Funktionen blob_get hämtar innehållet i en specifik blob (events.csv i det här fallet) i den refererade containern <container_name> för lagringen <account_name> . För att veta blob_get hur du parsar data kan du skicka ett värde i formuläret NULL::table_name, där table_name refererar till en tabell vars schema matchar den blob som läse. I exemplet refererar det till tabellen events som vi skapade i början.

<blob_name> ska anges till den fullständiga sökvägen för den blob vars innehåll du vill läsa.

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

Du kan också uttryckligen definiera schemat för resultatet med hjälp AS av -satsen efter funktionen 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;

Använd avkodningsalternativet

Det här exemplet illustrerar användningen av decoder alternativet. Normalt härleds formatet från filnamnstillägget, men när filinnehållet inte har något matchande tillägg kan du skicka avkodarargumentet.

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

Använda komprimering med avkodningsalternativet

Det här exemplet visar hur du framtvingar användning av gzip-komprimering på en gzip-komprimerad blob vars namn inte slutar med ett .gz-tillägg.

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

Importera filtrerat innehåll och ändra innan det läses in från csv-formatobjekt

Det här exemplet illustrerar möjligheten att filtrera och ändra innehållet som importerats från blobben innan det läses in i en SQL-tabell.

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;

Fråga efter innehåll från en fil med rubriker, anpassade avgränsare, escape-tecken

Det här exemplet illustrerar hur du kan använda anpassade avgränsare och escape-tecken genom att skicka resultatet av options_copy till options argumentet.

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

Sammansättningsfråga över innehållet i en blob

Det här exemplet illustrerar hur du kan utföra aggregeringsåtgärder över information som lagras i en blobcontainer, utan att behöva importera innehållet i bloben till PostgreSQL-tabeller.

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;

Importera data med hjälp av en COPY-instruktion

I följande exempel visas importen av data från en blob med namnet events.csv som finns i blobcontainern <container_name> i Azure Storage-kontot <account_name>via COPY kommandot :

Skapa en tabell som matchar källfilens schema:

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

Använd en COPY instruktion för att kopiera data till måltabellen. Ange att den första raden innehåller kolumnrubriker.

COPY events
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/events.csv'
WITH (FORMAT 'csv', header);

Skriva innehåll till en blob i en container

Funktionen blob_put består av innehållet i en specifik blob (eventscopy.csv i det här fallet) och laddar upp den till den refererade containern <container_name> för lagringen <account_name> . I det här exemplet används blob_get för att skapa en uppsättning med fem rader, som sedan skickas till den blob_put mängdfunktion som överför dem som en blob med namnet 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;

Exportera data med hjälp av en COPY-instruktion

I följande exempel visas exporten av data från en tabell med namnet events, till en blob med namnet events_exported.csv som finns i blobcontainern <container_name> i Azure Storage-kontot <account_name>, via COPY kommandot :

Skapa en tabell som matchar källfilens schema:

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

Läs in data i tabellen. Kör antingen INSERT-instruktioner för att fylla i det med flera syntetiska rader eller använd importdata med hjälp av ett COPY-instruktionsexempel för att fylla i dem med innehållet i exempeldatauppsättningen.

Använd en COPY instruktion för att kopiera data till måltabellen. Ange att den första raden innehåller kolumnrubriker.

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

Dela dina förslag och buggar med produktteamet för Azure Database for PostgreSQL.

Dela via

Importera och exportera data med hjälp av azure_storage-tillägget i Azure Database for PostgreSQL – flexibel server

Översikt över proceduren

Så här använder du auktorisering med Microsoft Entra-ID

Så här använder du auktorisering med delad nyckel

Funktioner

azure_storage.account_add

Behörigheter

Argument

account_name_p

account_key_p

account_config

Returtyp

azure_storage.account_options_managed_identity

Behörigheter

Argument

name

type

Returtyp

azure_storage.account_options_credentials

Behörigheter

Argument

name

autentiseringsuppgifter

type

Returtyp

azure_storage.account_options

Behörigheter

Argument

name

auth_type

storage_type

autentiseringsuppgifter

Returtyp

azure_storage.account_remove

Behörigheter

Argument

account_name_p

Returtyp

azure_storage.account_user_add

Behörigheter

Argument

account_name_p

user_p

Returtyp

azure_storage.account_user_remove

Behörigheter

Argument

account_name_p

user_p

Returtyp

azure_storage.account_list

Behörigheter

Argument

Returtyp

azure_storage.blob_list

Behörigheter

Argument

account_name

container_name

prefix

Returtyp

path

byte

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Behörigheter

Argument

account_name

container_name

path

Rec

avkodare

komprimering

alternativ

Returtyp