Import a export dat pomocí rozšíření azure_storage na flexibilním serveru Azure Database for PostgreSQL

Článek
01/02/2025

PLATÍ PRO: Flexibilní server Azure Database for PostgreSQL

Rozšíření azure_storage umožňuje importovat nebo exportovat data ve více formátech souborů přímo mezi účty Azure Storage a instancí flexibilního serveru Azure Database for PostgreSQL.

Příklady exportu a importu dat pomocí tohoto rozšíření najdete v části Příklady tohoto článku.

Pokud chcete rozšíření použít na instanci flexibilního azure_storage serveru Azure Database for PostgreSQL, musíte rozšíření povolit, načíst její knihovnu a vytvořit rozšíření.

Přehled postupu

Identifikujte účty Azure Storage, se kterými chcete, aby uživatelé azure_storage rozšíření komunikovali.
Rozhodněte se, jaký typ autorizace chcete použít pro požadavky provedené ve službě Blob Service každého z těchto účtů Azure Storage. azure_storage rozšíření podporuje autorizaci se sdíleným klíčem a autorizaci s ID Microsoft Entra. Z těchto dvou typů autorizace poskytuje Microsoft Entra ID vynikající zabezpečení a snadné použití prostřednictvím sdíleného klíče a je to ten, který Microsoft doporučuje. Pokud chcete splnit požadavky potřebné v každém případě, postupujte podle pokynů v odpovídajících částech:
- Autorizace pomocí MICROSOFT Entra ID nebo
- Autorizace pomocí sdíleného klíče
Zahrnout azure_storage do shared_preload_libraries:

Vzhledem k tomu, že shared_preload_libraries je statický, musí se server restartovat, aby se změna projevila:

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)

Vzhledem k tomu, že shared_preload_libraries je statický, musí se server restartovat, aby se změna projevila:

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

Zahrnout azure_storage do 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)

Pomocí klienta podle vašich preferencí (například psql, pgAdmin atd.) se připojte k libovolné databázi ve vaší instanci flexibilního serveru Azure Database for PostgreSQL. Pokud chcete vytvořit všechny objekty SQL (tabulky, typy, funkce, zobrazení atd.), pomocí kterých můžete pomocí azure_storage rozšíření pracovat s instancemi účtů Azure Storage, spusťte následující příkaz:
```
CREATE EXTENSION azure_storage;
```
azure_storage.account_* Pomocí funkcí přidejte odkazy na účty Azure Storage, ke kterým chcete umožnit přístup uživatelům nebo rolím PostgreSQL s rozšířenímazure_storage. Tyto odkazy zahrnují název odkazovaného účtu služby Azure Storage a typ ověřování, který se má použít při interakci s účtem Azure Storage. V závislosti na vybraném typu ověřování možná budete muset zadat i některé další parametry, jako je přístupový klíč účtu Azure Storage nebo token SAS.

Důležité

U typů ověřování, pro které musíte zadat přístupový klíč účtu azure Storage, si všimněte, že přístupové klíče azure Storage jsou podobné kořenovému heslu pro váš účet úložiště. Vždy buďte opatrní, abyste je ochránili. Pomocí služby Azure Key Vault můžete klíče bezpečně spravovat a otáčet. azure_storage Rozšíření ukládá tyto klíče do tabulky azure_storage.accounts , kterou můžou číst členové pg_read_all_data role.

Uživatelé, kterým byla azure_storage_admin role udělena, můžou s azure_storage.accounts tabulkou pracovat pomocí následujících funkcí:

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

Tato azure_storage_admin role je ve výchozím nastavení udělena azure_pg_admin této roli.

Použití autorizace s ID Microsoft Entra

Povolte spravovanou identitu přiřazenou systémem na flexibilním serveru Azure Database for 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"}}'

Po povolení spravované identity přiřazené systémem restartujte instanci flexibilního serveru Azure Database for PostgreSQL.
Přiřaďte oprávnění řízení přístupu na základě role (RBAC) pro přístup k datům objektů blob v účtu Azure Storage spravované identitě přiřazené systémem vaší instance flexibilního serveru Azure Database for PostgreSQL.

Použití autorizace se sdíleným klíčem

Váš účet Azure Storage musí mít povolený přístup k klíči účtu úložiště (to znamená, že nemůže mít vlastnost AllowSharedKeyAccess nastavenou na false).

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

Pokud ho chcete předat funkci azure_storage.account_add , načtěte jeden ze dvou přístupových klíčů účtu Azure Storage.

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

Funkce

azure_storage.account_add

Funkce, která umožňuje přidat účet úložiště a jeho přidružený přístupový klíč do seznamu účtů úložiště, ke kterým azure_storage má rozšíření přístup.

Pokud předchozí vyvolání této funkce už přidalo odkaz na tento účet úložiště, nepřidá novou položku, ale aktualizuje přístupový klíč existující položky.

Poznámka:

Tato funkce neověřuje, jestli název odkazovaného účtu existuje nebo jestli je přístupný pomocí zadaného přístupového klíče. Ověří ale, že název účtu úložiště je platný podle ověřovacích pravidel pojmenování uložených pro účty úložiště Azure.

azure_storage.account_add(account_name_p text, account_key_p text);

Existuje přetížená verze této funkce, která přijímá account_config parametr, který zapouzdřuje název odkazovaného účtu služby Azure Storage a všechna požadovaná nastavení, jako je typ ověřování, typ účtu nebo přihlašovací údaje k úložišti.

azure_storage.account_add(account_config jsonb);

Oprávnění

Musí být členem .azure_storage_admin

Argumenty

account_name_p

text název účtu služby Azure Blob Storage, který obsahuje všechny objekty: objekty blob, soubory, fronty a tabulky. Účet úložiště poskytuje jedinečný obor názvů, který je přístupný odkudkoli na světě přes HTTPS.

account_key_p

text hodnota jednoho z přístupových klíčů pro účet úložiště. Přístupové klíče služby Azure Blob Storage se podobají kořenovému heslu pro váš účet úložiště. Vždy buďte opatrní při ochraně přístupových klíčů. Pomocí služby Azure Key Vault můžete klíče bezpečně spravovat a otáčet. Klíč účtu je uložený v tabulce, která je přístupná pouze superuživatelem. Uživatelé, kterým byla role udělena azure_storage_admin , můžou s touto tabulkou pracovat prostřednictvím funkcí. Pokud chcete zjistit, které účty úložiště se přidají, použijte funkci azure_storage.account_list.

account_config

jsonb název účtu Azure Storage a všechna požadovaná nastavení, jako je typ ověřování, typ účtu nebo přihlašovací údaje k úložišti. Doporučujeme použít funkce nástroje azure_storage.account_options_managed_identity, azure_storage.account_options_credentials nebo azure_storage.account_options_options k vytvoření libovolné z platných hodnot, které se musí předat jako tento argument.

Návratový typ

VOID

azure_storage.account_options_managed_identity

Funkce, která funguje jako utility funkce, která se dá volat jako parametr v rámci azure_storage.account_add a je užitečná k vytvoření platné hodnoty argumentu account_config při použití spravované identity přiřazené systémem pro interakci s účtem Azure Storage.

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

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

name

type

azure_storage.storage_type hodnota jednoho z podporovaných typů úložiště. Podporovaná hodnota je blobpouze .

Návratový typ

jsonb

azure_storage.account_options_credentials

Funkce, která funguje jako utility funkce, která se dá volat jako parametr v rámci azure_storage.account_add a je užitečná k vytvoření platné hodnoty argumentu account_config při použití přístupového klíče Azure Storage k interakci s účtem Azure Storage.

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

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

name

přihlašovací údaje

type

azure_storage.storage_type hodnota jednoho z podporovaných typů úložiště. Podporovaná hodnota je blobpouze .

Návratový typ

jsonb

azure_storage.account_options

Funkce, která funguje jako utility funkce, která se dá volat jako parametr v rámci azure_storage.account_add a je užitečná k vytvoření platné hodnoty argumentu account_config při použití přístupového klíče azure Storage nebo spravované identity přiřazené systémem pro interakci s účtem Azure Storage.

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

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

name

auth_type

azure_storage.auth_type hodnota jednoho z podporovaných typů úložiště. Pouze podporované hodnoty jsou access-keya managed-identity.

storage_type

azure_storage.storage_type hodnota jednoho z podporovaných typů úložiště. Podporovaná hodnota je blobpouze .

přihlašovací údaje

Návratový typ

jsonb

azure_storage.account_remove

Funkce, která umožňuje odebrání účtu úložiště a jeho přidruženého přístupového klíče ze seznamu účtů úložiště, ke kterým azure_storage má rozšíření přístup.

azure_storage.account_remove(account_name_p text);

Oprávnění

Musí být členem .azure_storage_admin

Argumenty

account_name_p

Návratový typ

VOID

azure_storage.account_user_add

Funkce, která umožňuje udělit uživateli nebo roli PostgreSQL přístup k účtu úložiště prostřednictvím funkcí poskytovaných rozšířením azure_storage .

Poznámka:

Spuštění této funkce bude úspěšné pouze v případě, že účet úložiště, jehož název se předává jako první argument, již byl vytvořen pomocí azure_storage.account_add, a pokud již existuje uživatel nebo role, jehož název je předán jako druhý argument.

azure_storage.account_add(account_name_p text, user_p regrole);

Oprávnění

Musí být členem .azure_storage_admin

Argumenty

account_name_p

user_p

regrole název uživatele nebo role PostgreSQL, který je k dispozici na serveru.

Návratový typ

VOID

azure_storage.account_user_remove

Funkce, která umožňuje odvolání přístupu uživatele nebo role PostgreSQL k účtu úložiště prostřednictvím funkcí poskytovaných rozšířením azure_storage .

Poznámka:

Spuštění této funkce bude úspěšné pouze v případě, že se účet úložiště, jehož název se předává jako první argument, již byl vytvořen pomocí azure_storage.account_add a pokud uživatel nebo role, jejíž název je předán jako druhý argument, stále existuje. Při vyřazení uživatele nebo role ze serveru spuštěním se DROP USER | ROLEautomaticky odstraní také oprávnění udělená u všech odkazů na účty Azure Storage.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Oprávnění

Musí být členem .azure_storage_admin

Argumenty

account_name_p

user_p

regrole název uživatele nebo role PostgreSQL, který je k dispozici na serveru.

Návratový typ

VOID

azure_storage.account_list

Funkce, která uvádí názvy účtů úložiště nakonfigurovaných prostřednictvím funkce azure_storage.account_add spolu s uživateli nebo rolemi PostgreSQL, kterým jsou udělena oprávnění pro interakci s tímto účtem úložiště prostřednictvím funkcí poskytovaných rozšířením azure_storage .

azure_storage.account_list();

Oprávnění

Musí být členem .azure_storage_admin

Argumenty

Tato funkce nepřebírají žádné argumenty.

Návratový typ

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[]) Tabulka se čtyřmi sloupci se seznamem přidaných účtů Azure Storage, typem ověřování používaného k interakci s každým účtem, typem úložiště a seznamem uživatelů nebo rolí PostgreSQL, kterým je udělen přístup.

azure_storage.blob_list

Funkce, která uvádí názvy a další vlastnosti (velikost, lastModified, eTag, contentType, contentEncoding a contentHash) objektů blob uložených v daném kontejneru uvedeného účtu úložiště.

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

Oprávnění

Uživatel nebo role vyvolávající tuto funkci musí být přidány do seznamu povolených pro account_name odkazované spuštěním azure_storage.account_user_add. azure_storage_admin Členové mají automaticky povoleno odkazovat na všechny účty Azure Storage, jejichž odkazy byly přidány pomocí azure_storage.account_add.

Argumenty

account_name

container_name

text název kontejneru. Kontejner slouží k uspořádání sady objektů blob podobně, jako se v systému souborů používají adresáře. Účet úložiště může zahrnovat neomezený počet kontejnerů a v každém kontejneru může být neomezený počet objektů blob. Název kontejneru musí být platný název DNS (Domain Name System), protože je součástí jedinečného identifikátoru URI použitého k adresování kontejneru nebo jeho objektů blob. Při pojmenování kontejneru nezapomeňte postupovat podle těchto pravidel.

Identifikátor URI kontejneru je podobný následujícímu: https://myaccount.blob.core.windows.net/mycontainer

předpona

text po zadání vrátí funkce objekty blob, jejichž názvy začínají hodnotou zadanou v tomto parametru. Výchozí hodnota je prázdný řetězec.

Návratový typ

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) tabulka s jedním záznamem na vrácený objekt blob, včetně celého názvu objektu blob a některých dalších vlastností.

path

text úplný název objektu blob.

bajtů

bigint velikost objektu blob v bajtech.

last_modified

timestamp with time zonedatum a čas poslední změny objektu blob. Jakákoli operace, která upraví objekt blob, včetně aktualizace metadat nebo vlastností objektu blob, změní čas poslední změny objektu blob.

etag

text Vlastnost ETag se používá pro optimistickou souběžnost během aktualizací. Nejedná se o časové razítko, protože existuje jiná vlastnost s názvem Timestamp, která ukládá čas poslední aktualizace záznamu. Pokud například načtete entitu a chcete ji aktualizovat, musí eTag odpovídat aktuálně uložené entitě. Nastavení příslušné značky ETag je důležité, protože pokud máte více uživatelů, kteří upravují stejnou položku, nechcete, aby přepsali změny ostatních uživatelů.

content_type

text typ obsahu zadaný pro objekt blob. Výchozí typ obsahu je application/octet-stream.

content_encoding

text Vlastnost Content-Encoding objektu blob, který azure Storage umožňuje definovat. U komprimovaného obsahu můžete nastavit vlastnost na Gzip. Když prohlížeč přistupuje k obsahu, automaticky dekomprimuje obsah.

content_hash

text hodnota hash použitá k ověření integrity objektu blob během přenosu. Pokud je tato hlavička zadaná, služba úložiště zkontroluje zadanou hodnotu hash s jednou vypočítanou z obsahu. Pokud se dvě hodnoty hash neshoduje, operace selže s kódem chyby 400 (Chybný požadavek).

azure_storage.blob_get

Funkce, která umožňuje import dat. Stáhne soubor z kontejneru objektů blob v účtu azure Storage. Pak přeloží obsah na řádky, které lze využívat a zpracovávat pomocí konstruktorů jazyka SQL. Tato funkce přidává podporu filtrování a manipulace s daty načtenými z kontejneru objektů blob před importem.

Poznámka:

Než se pokusíte získat přístup ke kontejneru pro uvedený účet úložiště, tato funkce zkontroluje, jestli jsou názvy účtu úložiště a kontejneru předané jako argumenty platné podle ověřovacích pravidel pojmenování uložených pro účty úložiště Azure. Pokud je některý z nich neplatný, vyvolá se chyba.

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

Existuje přetížená verze této funkce, která přijímá rec parametr, který umožňuje pohodlně definovat záznam výstupního formátu.

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

Oprávnění

Argumenty

account_name

container_name

Identifikátor URI kontejneru je podobný následujícímu: https://myaccount.blob.core.windows.net/mycontainer

path

text úplný název objektu blob.

Rec

anyelement definice výstupní struktury záznamu.

dekodér

text specifikace formátu objektu blob. Lze nastavit na některou z následujících hodnot:

Formát	Výchozí	Popis
`auto`	`true`	Odvodí hodnotu na základě poslední řady znaků přiřazených k názvu objektu blob. Pokud název objektu blob končí `.csv` nebo `.csv.gz`, předpokládá `csv`. Pokud končí `.tsv` nebo `.tsv.gz`, předpokládá `tsv`. Pokud končí na `.json`, , `.xml.json.gz`, `.xml.gz`, `.txt`nebo `.txt.gz`, předpokládá `text`.
`csv`		Formát hodnot oddělených čárkami používaný nástrojem PostgreSQL COPY.
`tsv`		Hodnoty oddělené tabulátorem, výchozí formát PostgreSQL COPY.
`binary`		Binární formát PostgreSQL COPY.
`text` \| `xml` \| `json`		Soubor obsahující jednu textovou hodnotu.

komprese

text specifikace typu komprese. Lze nastavit na některou z následujících hodnot:

Formát	Výchozí	Popis
`auto`	`true`	Odvodí hodnotu na základě poslední řady znaků přiřazených k názvu objektu blob. Pokud název objektu blob končí `.gz`, předpokládá `gzip`. V opačném případě předpokládá `none`.
`gzip`		Vynutí dekodér gzip k dekompresi objektu blob.
`none`		Vynutí, aby objekt blob zachází jako s objektem blob, který nevyžaduje dekompresi.

Rozšíření nepodporuje žádné jiné typy komprese.

options

jsonb nastavení definující zpracování vlastních hlaviček, vlastních oddělovačů, řídicích znaků atd. options ovlivňuje chování této funkce způsobem podobným způsobem jako možnosti, které můžete předat COPY příkazu v PostgreSQL, ovlivňují jeho chování.

Návratový typ

SETOF record SETOF anyelement

azure_storage.blob_put

Funkce, která umožňuje exportovat data tak, že nahraje soubory do kontejneru objektů blob v účtu Azure Storage. Obsah souborů se vytváří z řádků v PostgreSQL.

Poznámka:

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

Existuje přetížená verze funkce, která obsahuje encoder parametr, který umožňuje určit kodér, který se má použít, když ho nelze odvodit z rozšíření parametru path nebo když chcete přepsat odvozený parametr.

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

Existuje přetížená verze funkce, která obsahuje compression také parametr, který umožňuje určit kompresi, která se má použít, když ji nelze odvodit z rozšíření parametru path nebo když chcete přepsat odvozenou verzi.

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

Existuje přetížená verze funkce, která obsahuje options také parametr pro zpracování vlastních hlaviček, vlastních oddělovačů, řídicích znaků atd. options funguje podobně jako možnosti, které lze předat COPY příkazu v PostgreSQL.

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

Oprávnění

Argumenty

account_name

container_name

Identifikátor URI kontejneru je podobný následujícímu: https://myaccount.blob.core.windows.net/mycontainer

path

text úplný název objektu blob.

tuple

record definice výstupní struktury záznamu.

encoder

text specifikace formátu objektu blob. Lze nastavit na některou z následujících hodnot:

Formát	Výchozí	Popis
`auto`	`true`	Odvodí hodnotu na základě poslední řady znaků přiřazených k názvu objektu blob. Pokud název objektu blob končí `.csv` nebo `.csv.gz`, předpokládá `csv`. Pokud končí `.tsv` nebo `.tsv.gz`, předpokládá `tsv`. Pokud končí na `.json`, , `.xml.json.gz`, `.xml.gz`, `.txt`nebo `.txt.gz`, předpokládá `text`.
`csv`		Formát hodnot oddělených čárkami používaný nástrojem PostgreSQL COPY.
`tsv`		Hodnoty oddělené tabulátorem, výchozí formát PostgreSQL COPY.
`binary`		Binární formát PostgreSQL COPY.
`text` \| `xml` \| `json`		Soubor obsahující jednu textovou hodnotu.

komprese

text specifikace typu komprese. Lze nastavit na některou z následujících hodnot:

Formát	Výchozí	Popis
`auto`	`true`	Odvodí hodnotu na základě poslední řady znaků přiřazených k názvu objektu blob. Pokud název objektu blob končí `.gz`, předpokládá `gzip`. V opačném případě předpokládá `none`.
`gzip`		Vynutí dekodér gzip k dekompresi objektu blob.
`none`		Vynutí, aby objekt blob zachází jako s objektem blob, který nevyžaduje dekompresi.

Rozšíření nepodporuje žádné jiné typy komprese.

options

Návratový typ

VOID

azure_storage.options_csv_get

Funkce, která funguje jako utility funkce, kterou lze volat jako parametr uvnitř blob_geta je užitečná pro dekódování obsahu souboru 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);

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

oddělovač

text znak, který odděluje sloupce v každém řádku (řádku) souboru. Musí to být jeden 1 bajtový znak. I když tato funkce podporuje oddělovače libovolného počtu znaků, pokud se pokusíte použít více než jeden 1 bajtový znak, PostgreSQL hlásí chybu COPY delimiter must be a single one-byte character .

null_string

text řetězec, který představuje hodnotu null. Výchozí hodnota je \N (zpětné lomítko-N) v textovém formátu a necitovaný prázdný řetězec ve formátu CSV. Prázdný řetězec můžete preferovat i v textovém formátu v případech, kdy nechcete rozlišovat hodnoty null od prázdných řetězců.

boolean příznak, který označuje, jestli soubor obsahuje řádek záhlaví s názvy jednotlivých sloupců v souboru. Ve výstupu obsahuje počáteční řádek názvy sloupců z tabulky.

citát

text znak uvozování, který se použije při uvozování datové hodnoty. Výchozí hodnota je dvojitá uvozovka. Musí to být jeden 1 bajtový znak. I když tato funkce podporuje oddělovače libovolného počtu znaků, pokud se pokusíte použít více než jeden 1 bajtový znak, PostgreSQL hlásí chybu COPY quote must be a single one-byte character .

escape

text znak, který by se měl zobrazit před datovým znakem, který odpovídá hodnotě QUOTE. Výchozí hodnota je stejná jako hodnota QUOTE (aby se znak uvozovek zdvojnásobil, pokud se zobrazí v datech). Musí to být jeden 1 bajtový znak. I když tato funkce podporuje oddělovače libovolného počtu znaků, pokud se pokusíte použít více než jeden 1 bajtový znak, PostgreSQL hlásí chybu COPY escape must be a single one-byte character .

force_not_null

text[] neodpovídají hodnotám zadaných sloupců s řetězcem null. Ve výchozím případě, kdy je řetězec null prázdný, znamená to, že prázdné hodnoty se čtou jako řetězce nulové délky místo hodnot null, i když nejsou v uvozovácích.

force_null

text[] porovná hodnoty zadaných sloupců s řetězcem null, i když je uvozováno, a pokud je nalezena shoda, nastavte hodnotu na HODNOTU NULL. Ve výchozím případě, kdy je řetězec null prázdný, převede uvozovaný prázdný řetězec na hodnotu NULL.

content_encoding

text název kódování, se kterým je soubor kódován. Pokud je tato možnost vynechána, použije se aktuální kódování klienta.

Návratový typ

jsonb

azure_storage.options_copy

Funkce, která funguje jako utility funkce, kterou lze volat jako parametr v rámci blob_get. Funguje jako pomocná funkce pro options_csv_get, options_tsv a 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);

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

oddělovač

null_string

záhlaví

boolean příznak, který označuje, jestli soubor obsahuje řádek záhlaví s názvy jednotlivých sloupců v souboru. Ve výstupu obsahuje počáteční řádek názvy sloupců z tabulky.

citát

escape

force_quote

text[] vynutí použití uvozování pro všechny hodnoty, které nejsou null v každém zadaném sloupci. Výstup NULL se nikdy neuvozuje. Pokud je zadána hodnota *, hodnoty, které nemají hodnotu NULL, se uvozují ve všech sloupcích.

force_not_null

force_null

content_encoding

text název kódování, se kterým je soubor kódován. Pokud je tato možnost vynechána, použije se aktuální kódování klienta.

Návratový typ

jsonb

azure_storage.options_tsv

Funkce, která funguje jako utility funkce, která může být volána jako parametr uvnitř blob_geta je užitečná pro dekódování obsahu souboru tsv.

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

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

oddělovač

null_string

content_encoding

text název kódování, se kterým je soubor kódován. Pokud je tato možnost vynechána, použije se aktuální kódování klienta.

Návratový typ

jsonb

azure_storage.options_binary

Funkce, která funguje jako utility funkce, která může být volána jako parametr uvnitř blob_get, a je užitečná pro dekódování obsahu binárního souboru.

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

Oprávnění

Tuto funkci může vyvolat libovolný uživatel nebo role.

Argumenty

content_encoding

text název kódování, se kterým je soubor kódován. Pokud je tato možnost vynechána, použije se aktuální kódování klienta.

Návratový typ

jsonb

Možné chyby

CHYBA: azure_storage: Oprávnění není dostatečné k provedení požadované operace

Při spouštění některé z funkcí, které pracují se službou Azure Storage (azure_storage.blob_getazure_storage.blob_listneboazure_storage.blob_put) a spravovanou identitou přiřazenou systémem, není udělena odpovídající role nebo oprávnění roviny dat (obvykle minimálně Přispěvatel dat objektů blob služby Storage pro azure_storage.blob_put a minimálně čtenář dat objektů blob služby Storage pro ostatní dvě funkce).

Může se jednat také o případ, že jste již udělili minimální požadovaná oprávnění, ale ještě nejsou platná. Rozšíření těchto oprávnění může trvat několik minut.

CHYBA: azure_storage: Chybějící přihlašovací údaje k úložišti

Při spouštění některé z funkcí, které komunikují se službou Azure Storage (azure_storage.blob_listneboazure_storage.blob_put) a přihlašovacími údaji, azure_storage.blob_get se kterými chcete, aby se rozšíření ověřilo pomocí účtu úložiště, se neregistruje pomocí azure_storage.account_add.

CHYBA: azure_storage: vnitřní chyba při připojování

Pokud instance flexibilního serveru nemůže dosáhnout cílového účtu úložiště. K tomu může dojít v následujících případech:

Účet úložiště neexistuje.
Konfigurace sítě neumožňuje, aby provoz pocházející z instance flexibilního serveru dosáhl účtu úložiště. Například když je instance flexibilního serveru nasazená se sítí veřejného přístupu a účet úložiště je přístupný jenom prostřednictvím privátních koncových bodů.

Pokud v instanci flexibilního serveru není povolená spravovaná identita přiřazená systémem.

CHYBA: azure_storage: Přihlašovací údaje úložiště mají neplatný formát

Pokud je na instanci flexibilního serveru povolená spravovaná identita přiřazená systémem, ale po povolení se server nerestartoval.

CHYBA: azure_storage: Aktuální uživatelský <user_or_role> nesmí používat account_name účtu <úložiště>

Při spouštění některé z funkcí, které komunikují se službou Azure Storage (azure_storage.blob_listneboazure_storage.blob_put) s uživatelem nebo rolí, azure_storage.blob_get které nejsou členy azure_storage_admin a které nejsou uděleny oprávnění, pomocí použití azure_storage.account_user_adduvedeného účtu úložiště.

Příklady

Před spuštěním následujících příkladů musíte splnit následující požadavky:

Vytvořit účet služby Azure Storage Pokud chcete vytvořit účet Azure Storage, pokud ho ještě nemáte, přizpůsobte hodnoty <resource_group>, <location><account_name>a <container_name>a spusťte následující příkaz Azure CLI:

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

Vytvořte kontejner objektů blob. Pokud chcete vytvořit kontejner objektů blob, spusťte následující Azure CLI:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Načtěte jeden ze dvou přístupových klíčů přiřazených k účtu úložiště. Nezapomeňte zkopírovat hodnotu access_key, protože ji potřebujete předat jako argument pro azure_storage.account_add v dalším kroku. Pokud chcete načíst první ze dvou přístupových klíčů, spusťte následující příkaz Azure CLI:
```
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
```

Stáhněte si soubor s datovou sadou, která se používá během příkladů, a nahrajte ho do kontejneru objektů blob. Pokud chcete stáhnout soubor s datovou sadou, spusťte následující příkaz Azure CLI:

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

Poznámka:

Kontejnery nebo objekty blob, které jsou v nich uložené, můžete vypsat pro konkrétní účet úložiště, ale jenom v případě, že má uživatel nebo role PostgreSQL udělená oprávnění k odkazu na tento účet úložiště pomocí azure_storage.account_user_add. Členům azure_storage_admin této role se udělí toto oprávnění pro všechny účty Azure Storage, které byly přidány pomocí azure_storage.account_add. Ve výchozím nastavení jsou této roli uděleni azure_storage_admin pouze členovéazure_pg_admin.

Vytvoření tabulky, ve které se načtou data

Vytvoříme tabulku, do které naimportujeme obsah souboru CSV, který jsme nahráli do účtu úložiště. Pokud to chcete udělat, připojte se k instanci flexibilního serveru Azure Database for PostgreSQL pomocí PgAdminnástroje , psqlnebo klienta podle vašich preferencí a spusťte následující příkaz:

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

Přidání přístupového klíče účtu úložiště

Tento příklad ukazuje, jak přidat odkaz na účet úložiště společně s přístupovým klíčem tohoto účtu úložiště, který je nutný pro přístup k jeho obsahu prostřednictvím funkcí poskytovaných rozšířením azure_storage ve vaší instanci flexibilního serveru Azure Database for PostgreSQL.

<account_name> musí být nastaven na název vašeho účtu úložiště. Pokud jste použili předchozí skripty, měla by tato hodnota odpovídat libovolné hodnotě, kterou jste v těchto skriptech nastavili na proměnnou prostředí storage_account.

Podobně je nutné nastavit hodnotu, <access_key> kterou jste načítáli ze svého účtu úložiště.

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

Tip

Pokud chcete načíst název účtu úložiště a jeden z jeho přístupových klíčů z webu Azure Portal, vyhledejte svůj účet úložiště, v nabídce prostředků vyberte Přístupové klíče, zkopírujte název účtu úložiště a zkopírujte klíč z oddílu key1 (musíte nejprve vybrat Možnost Zobrazit vedle klíče).

Odebrání odkazu na účet úložiště

Tento příklad ukazuje, jak odebrat všechny odkazy na účet úložiště, aby k tomuto účtu úložiště neměli azure_storage přístup žádní uživatelé v aktuální databázi.

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

Udělení přístupu uživateli nebo roli v referenčních informacích k úložišti objektů blob v Azure

Tento příklad ukazuje, jak udělit přístup k uživateli nebo roli s názvem <regular_user>, aby takový uživatel PostgreSQL mohl použít azure_storage rozšíření pro přístup k objektům blob uloženým v kontejnerech hostovaných odkazovaným účtem úložiště Azure.

<regular_user> musí být nastaveno na název existujícího uživatele nebo role.

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

Výpis všech odkazů na účty úložiště Azure

Tento příklad ukazuje, jak zjistit, na které účty azure_storage úložiště Azure může toto rozšíření odkazovat v této databázi, spolu s typem ověřování, které se používá pro přístup k jednotlivým účtům úložiště a kteří uživatelé nebo role mají udělená oprávnění prostřednictvím funkce azure_storage.account_user_add , abyste k tomuto účtu úložiště Azure získali přístup prostřednictvím funkcí poskytovaných rozšířením.

SELECT * FROM azure_storage.account_list();

Odvolání přístupu od uživatele nebo role v referenčních informacích k úložišti objektů blob v Azure

Tento příklad ukazuje, jak odvolat přístup od uživatele nebo role s názvem <regular_user>, aby takový uživatel PostgreSQL nemohl použít azure_storage rozšíření pro přístup k objektům blob uloženým v kontejnerech hostovaných odkazovaným účtem úložiště Azure.

<regular_user> musí být nastaveno na název existujícího uživatele nebo role.

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

Výpis všech objektů blob v kontejneru

Tento příklad ukazuje, jak vypsat všechny existující objekty blob uvnitř kontejneru <container_name> účtu <account_name>úložiště .

<container_name> musí být nastaven na název kontejneru objektů blob. Pokud jste použili předchozí skripty, měla by tato hodnota odpovídat libovolné hodnotě, kterou jste v těchto skriptech nastavili na proměnnou prostředí blob_container.

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

Výpis objektů s konkrétní předponou názvu objektu blob

Tento příklad ukazuje, jak vypsat všechny existující objekty blob uvnitř kontejneru <container_name> účtu <account_name>úložiště, jehož název objektu blob začíná <blob_name_prefix>.

<blob_name_prefix> měla by být nastavena na libovolnou předponu, kterou mají objekty blob vyčíslit, aby zahrnovaly jejich názvy. Pokud chcete vrátit všechny objekty blob, můžete tento parametr nastavit na prázdný řetězec nebo nezadávat ani hodnotu pro tento parametr. V takovém případě se hodnota ve výchozím nastavení nastaví na prázdný řetězec.

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

Alternativně můžete použít následující syntaxi:

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

Čtení obsahu z objektu blob v kontejneru

Funkce blob_get načte obsah jednoho konkrétního objektu blob (events.csv v tomto případě) v uvedeném kontejneru <container_name> <account_name> úložiště. Abyste blob_get věděli, jak analyzovat data, můžete předat hodnotu ve formuláři NULL::table_name, kde table_name odkazuje na tabulku, jejíž schéma odpovídá čteného objektu blob. V příkladu odkazuje na events tabulku, kterou jsme vytvořili na samém začátku.

<blob_name> měla by být nastavena na úplnou cestu objektu blob, jejíž obsah chcete přečíst.

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

Alternativně můžete explicitně definovat schéma výsledku pomocí AS klauzule za blob_get funkcí.

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;

Použití možnosti dekodéru

Tento příklad znázorňuje použití decoder možnosti. Obvykle se formát odvodí z přípony souboru, ale pokud obsah souboru nemá odpovídající příponu, můžete předat argument dekodéru.

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

Použití komprese s možností dekodéru

Tento příklad ukazuje, jak vynutit použití komprese gzip u komprimovaného objektu blob gzip, jehož název nekončí rozšířením .gz.

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

Import filtrovaného obsahu a úpravy před načtením z objektu formátu CSV

Tento příklad ukazuje možnost filtrovat a upravovat obsah importovaný z objektu blob před načtením do tabulky 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;

Dotazování obsahu ze souboru pomocí hlaviček, vlastních oddělovačů, řídicích znaků

Tento příklad ukazuje, jak můžete použít vlastní oddělovače a řídicí znaky předáním výsledku options_copy argumentu 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')
        );

Agregační dotaz nad obsahem objektu blob

Tento příklad ukazuje, jak můžete provádět agregační operace nad informacemi uloženými v kontejneru objektů blob, aniž byste museli importovat obsah objektu blob do tabulek 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;

Import dat pomocí příkazu COPY

Následující příklad ukazuje import dat z objektu blob, který se nachází events.csv v kontejneru <container_name> objektů blob v účtu <account_name>služby Azure Storage, pomocí COPY příkazu:

Vytvořte tabulku, která odpovídá schématu zdrojového souboru:

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

COPY Pomocí příkazu zkopírujte data do cílové tabulky. Určete, že první řádek obsahuje záhlaví sloupců.

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

Zápis obsahu do objektu blob v kontejneru

Funkce blob_put sestaví obsah jednoho konkrétního objektu blob (eventscopy.csv v tomto případě) a nahraje ho do odkazového kontejneru <container_name> <account_name> úložiště. Tento příklad používá blob_get k vytvoření sady pěti řádků, které se pak předají blob_put agregační funkci, která je nahraje jako objekt blob s názvem 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;

Export dat pomocí příkazu COPY

Následující příklad ukazuje export dat z tabulky s názvem eventsevents_exported.csv do objektu blob, který se nachází v kontejneru <container_name> objektů blob v účtu <account_name>Služby Azure Storage pomocí COPY příkazu:

Vytvořte tabulku, která odpovídá schématu zdrojového souboru:

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

Načtěte data do tabulky. Buď spusťte příkazy INSERT, které ho naplní několika syntetickými řádky, nebo použijte import dat pomocí příkladu příkazu COPY k naplnění obsahem ukázkové datové sady.

COPY Pomocí příkazu zkopírujte data do cílové tabulky. Určete, že první řádek obsahuje záhlaví sloupců.

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

Import a export dat pomocí Azure Storage na flexibilním serveru Azure Database for PostgreSQL
Správa rozšíření PostgreSQL na flexibilním serveru Azure Database for PostgreSQL

Sdílet prostřednictvím

Import a export dat pomocí rozšíření azure_storage na flexibilním serveru Azure Database for PostgreSQL

Přehled postupu

Použití autorizace s ID Microsoft Entra

Použití autorizace se sdíleným klíčem

Funkce

azure_storage.account_add

Oprávnění

Argumenty

account_name_p

account_key_p

account_config

Návratový typ

azure_storage.account_options_managed_identity

Oprávnění

Argumenty

name

type

Návratový typ

azure_storage.account_options_credentials

Oprávnění

Argumenty

name

přihlašovací údaje

type

Návratový typ

azure_storage.account_options

Oprávnění

Argumenty

name

auth_type

storage_type

přihlašovací údaje

Návratový typ

azure_storage.account_remove

Oprávnění

Argumenty

account_name_p

Návratový typ

azure_storage.account_user_add

Oprávnění

Argumenty

account_name_p

user_p

Návratový typ

azure_storage.account_user_remove

Oprávnění

Argumenty

account_name_p

user_p

Návratový typ

azure_storage.account_list

Oprávnění

Argumenty

Návratový typ

azure_storage.blob_list

Oprávnění

Argumenty

account_name

container_name

předpona

Návratový typ

path

bajtů

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Oprávnění

Argumenty

account_name

container_name

path

Rec

dekodér

komprese

options

Návratový typ