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
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro