rozšíření pg_azure_storage

PLATÍ PRO: Azure Cosmos DB for PostgreSQL (využívající rozšíření databáze Citus do PostgreSQL)

Rozšíření pg_azure_storage umožňuje načíst data ve více formátech souborů přímo z úložiště objektů blob v Azure do clusteru Azure Cosmos DB for PostgreSQL. Povolení rozšíření také odemkne nové funkce příkazu COPY . Kontejnery s úrovní přístupu Private nebo Blob vyžadují přidání privátního přístupového klíče.

Rozšíření můžete vytvořit spuštěním následujícího příkazu:

SELECT create_extension('azure_storage');

azure_storage.account_add

Funkce umožňuje přidat přístup k účtu úložiště.

azure_storage.account_add
        (account_name_p text
        ,account_key_p text);

Argumenty

account_name_p

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

account_key_p

Přístupové klíče služby Azure Blob Storage (ABS) se podobají kořenovému heslu vašeho účtu ú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á superuživatelem postgres, azure_storage_admin a všem rolím uděleným těmto oprávněním správce. Pokud chcete zjistit, které účty úložiště existují, použijte funkci account_list.

azure_storage.account_remove

Funkce umožňuje odvolání přístupu k účtu úložiště.

azure_storage.account_remove
        (account_name_p text);

Argumenty

account_name_p

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

azure_storage.account_user_add

Tato funkce umožňuje přidat přístup pro roli k účtu úložiště.

azure_storage.account_user_add
        ( account_name_p text
        , user_p regrole);

Argumenty

account_name_p

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

user_p

Role vytvořená uživatelem viditelná v clusteru

Poznámka:

account_user_addaccount_removeaccount_user_remove Funkceaccount_add vyžadují nastavení oprávnění pro jednotlivé uzly v clusteru.

azure_storage.account_user_remove

Tato funkce umožňuje odebrat přístup pro roli k účtu úložiště.

azure_storage.account_user_remove
        (account_name_p text
        ,user_p regrole);

Argumenty

account_name_p

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

user_p

Role vytvořená uživatelem viditelná v clusteru

azure_storage.account_list

Tato funkce zobrazí seznam účtů a rolí, které mají přístup k úložišti objektů blob v Azure.

azure_storage.account_list
        (OUT account_name text
        ,OUT allowed_users regrole[]
        )
Returns TABLE;

Argumenty

account_name

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

allowed_users

Zobrazí seznam uživatelů, kteří mají přístup k úložišti objektů blob v Azure.

Návratový typ

TABULKA

azure_storage.blob_list

Funkce zobrazí seznam dostupných souborů objektů blob v kontejneru uživatele se svými vlastnostmi.

azure_storage.blob_list
        (account_name text
        ,container_name text
        ,prefix text DEFAULT ''::text
        ,OUT path text
        ,OUT bytes bigint
        ,OUT last_modified timestamp with time zone
        ,OUT etag text
        ,OUT content_type text
        ,OUT content_encoding text
        ,OUT content_hash text
        )
Returns SETOF record;

Argumenty

account_name

Poskytuje storage account name jedinečný obor názvů pro vaše data úložiště Azure, která jsou přístupná odkudkoli na světě přes HTTPS.

container_name

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, 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 postupujte podle těchto pravidel:

• Názvy kontejnerů můžou mít délku 3 až 63 znaků.
• Názvy kontejnerů musí začínat písmenem nebo číslicí a mohou obsahovat pouze malá písmena, číslice a znak pomlčky (-).
• V názvech kontejnerů nejsou povolené dva nebo více po sobě jdoucích pomlček.

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

předpona

Vrátí soubor z kontejneru objektů blob s odpovídajícími řetězcovými iniciály.

path

Úplná cesta k adresáři objektů blob Azure.

bajtů

Velikost objektu souboru v bajtech

last_modified

Kdy byl obsah souboru naposledy změněn.

etag

Vlastnost ETag se používá k optimistické souběžnosti 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

Objekt blob představuje objekt blob, což je objekt podobný souboru neměnných nezpracovaných dat. Dají se číst jako textová nebo binární data nebo je převést na ReadableStream, aby se jejich metody mohly použít ke zpracování dat. Objekty blob můžou představovat data, která nemusí být nutně v nativním javascriptovém formátu.

content_encoding

Azure Storage umožňuje definovat vlastnost Kódování obsahu v objektu blob. U komprimovaného obsahu můžete nastavit vlastnost na GZIP. Když prohlížeč přistupuje k obsahu, automaticky dekomprimuje obsah.

content_hash

Tato hodnota hash se používá k ověření integrity objektu blob během přenosu. Pokud je tato hlavička zadaná, služba úložiště zkontroluje hodnotu hash, která přišla s hodnotou, která byla odeslána. Pokud se dvě hodnoty hash neshoduje, operace selže s kódem chyby 400 (Chybný požadavek).

Návratový typ

SETOF – záznam

Poznámka:

Oprávnění teď můžete vypsat kontejnery nastavené na úrovně přístupu k privátním objektům a objektům blob pro toto úložiště, ale pouze jako kontejnery citus user, které mají přiřazenou azure_storage_admin roli. Pokud vytvoříte nového uživatele s názvem support, ve výchozím nastavení nebude mít povolený přístup k obsahu kontejneru.

azure_storage.blob_get

Funkce umožňuje načtení obsahu souborů \ souborů z kontejneru s přidanou podporou filtrování nebo manipulace s daty před importem.

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
        )
RETURNS SETOF record;

Existuje přetížená verze funkce, která obsahuje parametr rec, 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
        )
RETURNS SETOF anyelement;

Argumenty

account

Účet úložiště poskytuje jedinečný obor názvů pro vaše data Azure Storage, která jsou přístupná odkudkoli na světě přes HTTPS.

kontejner

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, protože je součástí jedinečného identifikátoru URI použitého k adresování kontejneru nebo jeho objektů blob.

path

Název objektu blob existující v kontejneru

Rec

Definujte výstupní strukturu záznamu.

dekodér

Určení dekodéru formátu objektu blob lze nastavit na automatické (výchozí) nebo na některou z následujících hodnot.

popis dekodéru

Formát	Popis
csv	Formát hodnot oddělených čárkami používaný nástrojem PostgreSQL COPY
tsv	Hodnoty oddělené tabulátory, výchozí formát PostgreSQL COPY
binární	Binární formát PostgreSQL COPY
text	Soubor obsahující jednu textovou hodnotu (například velký JSON nebo XML)

komprese

Definuje formát komprese. Dostupné možnosti jsou auto, gzip & none. Použití možnosti (výchozí) auto uhodne kompresi na základě přípony souboru (.gz == gzip). Možnost none vynutí ignorovat rozšíření a nepokouší se dekódovat. I když gzip vynutí použití dekodéru gzip (pro kdy máte gzipped soubor s nestandardní příponou). V současné době nepodporujeme žádné jiné formáty komprese rozšíření.

options

Pro zpracování vlastních hlaviček, vlastních oddělovačů, řídicích znaků atd., options funguje podobně jako COPY příkaz v PostgreSQL parametr blob_get funkce.

Návratový typ

SETOF Record / anyelement

Poznámka:

V rámci blob_get existují čtyři utility funkce, které se nazývají jako parametr, které pomáhají vytvářet hodnoty pro něj. Každá funkce nástroje je určena pro dekodér odpovídající jeho názvu.

azure_storage.options_csv_get

Funkce funguje jako utility funkce volaná jako parametr v rámci blob_get, což je užitečné pro dekódování obsahu 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
        )
Returns jsonb;

Argumenty

oddělovač

Určuje znak, který odděluje sloupce v každém řádku (řádku) souboru. Výchozí hodnota je znak tabulátoru v textovém formátu, čárka ve formátu CSV. Musí to být jeden bajtový znak.

null_string

Určuje ř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ů.

záhlaví

Určuje, že soubor obsahuje řádek záhlaví s názvy jednotlivých sloupců v souboru. Ve výstupu první řádek obsahuje názvy sloupců z tabulky.

citát

Určuje znak uvozování, který se má použít při uvozování datové hodnoty. Výchozí hodnota je dvojitá uvozovka. Musí to být jeden bajtový znak.

escape

Určuje znak, který se má 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 bajtový znak.

force_not_null

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

Porovná hodnoty zadaných sloupců s řetězcem null, i když byl uvozován, 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

Určuje, že soubor je kódován v encoding_name. 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 funguje jako utility funkce volaná jako parametr v rámci blob_get.

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

Argumenty

oddělovač

Určuje znak, který odděluje sloupce v každém řádku (řádku) souboru. Výchozí hodnota je znak tabulátoru v textovém formátu, čárka ve formátu CSV. Musí to být jeden bajtový znak.

null_string

Určuje ř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ů.

záhlaví

Určuje, že soubor obsahuje řádek záhlaví s názvy jednotlivých sloupců v souboru. Ve výstupu první řádek obsahuje názvy sloupců z tabulky.

citát

Určuje znak uvozování, který se má použít při uvozování datové hodnoty. Výchozí hodnota je dvojitá uvozovka. Musí to být jeden bajtový znak.

escape

Určuje znak, který se má 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 bajtový znak.

force_quote

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

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

Porovná hodnoty zadaných sloupců s řetězcem null, i když byl uvozován, 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

Určuje, že soubor je kódován v encoding_name. 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 funguje jako utility funkce volaná jako parametr v rámci blob_get. Je užitečné pro dekódování obsahu tsv.

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

Argumenty

oddělovač

Určuje znak, který odděluje sloupce v každém řádku (řádku) souboru. Výchozí hodnota je znak tabulátoru v textovém formátu, čárka ve formátu CSV. Musí to být jeden bajtový znak.

null_string

Určuje ř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ů.

content_encoding

Určuje, že soubor je kódován v encoding_name. 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 funguje jako utility funkce volaná jako parametr v rámci blob_get. Je užitečné dekódovat binární obsah.

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

Argumenty

content_encoding

Určuje, že soubor je kódován v encoding_name. Pokud tuto možnost vynecháte, použije se aktuální kódování klienta.

Návratový typ

jsonb

Poznámka:

Oprávnění teď můžete vypsat kontejnery nastavené na úrovně přístupu k privátním objektům a objektům blob pro toto úložiště, ale pouze jako kontejnery citus user, které mají přiřazenou azure_storage_admin roli. Pokud vytvoříte novou podporu pojmenovanou uživatelem, nebude mít ve výchozím nastavení povolený přístup k obsahu kontejneru.

Příklady

Použité příklady využívají ukázkový účet (pgquickstart) úložiště Azure s vlastními soubory nahranými k přidání pokrytí různých případů použití. Můžeme začít vytvořením tabulky použité v sadě použitých příkladů.

CREATE TABLE IF NOT EXISTS public.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ě (povinné pro úroveň přístupu = privátní)

Příklad znázorňuje přidání přístupového klíče pro účet úložiště pro získání přístupu k dotazování z relace v clusteru Azure Cosmos DB for Postgres.

SELECT azure_storage.account_add('pgquickstart', 'SECRET_ACCESS_KEY');

Tip

V účtu úložiště otevřete přístupové klíče. Zkopírujte název účtu úložiště a zkopírujte klíč z oddílu key1 (musíte nejprve vybrat Zobrazit vedle klíče).

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

Příklad ukazuje odebrání přístupového klíče pro účet úložiště. Výsledkem této akce by bylo odebrání přístupu k souborům hostovaným v privátním kontejneru v kontejneru.

SELECT azure_storage.account_remove('pgquickstart');

Přidání přístupu pro roli do služby Azure Blob Storage

SELECT * FROM azure_storage.account_user_add('pgquickstart', 'support');

Výpis všech rolí s přístupem ve službě Azure Blob Storage

SELECT * FROM azure_storage.account_list();

Odebrání rolí s přístupem ke službě Azure Blob Storage

SELECT * FROM azure_storage.account_user_remove('pgquickstart', 'support');

Výpis objektů v rámci kontejneru public

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer');

Výpis objektů v rámci kontejneru private

SELECT * FROM azure_storage.blob_list('pgquickstart','privatecontainer');

Poznámka:

Přidání přístupového klíče je povinné.

Výpis objektů s konkrétními řetězcovými iniciály v rámci veřejného kontejneru

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer','e');

Alternativně

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer') WHERE path LIKE 'e%';

Čtení obsahu z objektu v kontejneru

Funkce blob_get načte soubor z úložiště objektů blob. Pokud chcete blob_get vědět, jak analyzovat data, můžete předat hodnotu (NULL::table_name), která má stejný formát jako soubor.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv.gz'
        , NULL::events)
LIMIT 5;

Alternativně můžeme explicitně definovat sloupce v FROM klauzuli.

SELECT * FROM azure_storage.blob_get('pgquickstart','publiccontainer','events.csv')
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

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
        ('pgquickstart'
        ,'publiccontainer'
        ,'events'
        , NULL::events
        , decoder := 'csv')
LIMIT 5;

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

Příklad ukazuje, jak vynutit použití komprese gzip u komprimovaného souboru gzip bez standardního rozšíření .gz.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'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

Příklad ukazuje možnost filtrovat a upravit obsah importovaný z objektu v kontejneru před načtením do tabulky SQL.

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'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ů

Vlastní oddělovače a řídicí znaky můžete použít předáním výsledku azure_storage.options_copy argumentu options .

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Agregační dotaz na obsah objektu v kontejneru

Tímto způsobem můžete dotazovat data bez importu.

SELECT event_type,COUNT(1) FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Další kroky

Použití služby Azure Blob Storage s příkazem COPY

Jak ingestovat data pomocí pg_azure_storage