Příklady rychlého startu pro rozšíření Azure Storage ve službě Azure Database for PostgreSQL

Následuje seznam příkladů, které vám pomůžou naučit se používat rozšíření Azure Storage.

Vytvoření účtu služby Azure Storage a jeho naplnění daty

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:

random_suffix=$(tr -dc 'a-z0-9' </dev/urandom | head -c8)
resource_group="resource-group-$random_suffix"
location="eastus2"
storage_account="storageaccount$random_suffix"
blob_container="container-$random_suffix"
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
echo "Take note of the storage account name, which you'll have to replace in subsequent examples, whenever you find a reference to <account_name>:"
echo $storage_account
echo "Take note of the container name, which you'll have to replace in subsequent examples, whenever you find a reference to <container_name>:"
echo $blob_container

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 -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.parquet
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.parquet" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/parquet_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "parquet_without_extension" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.csv" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/csv_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "csv_without_extension" --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_pg_admin pouze členovéazure_storage_admin.

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

Pojďme vytvořit tabulku, do které naimportujeme obsah souborů, 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í PostgreSQL pro Visual Studio Code (Preview),psql, PgAdmin nebo klienta podle vašich preferencí a spusťte následující příkaz:

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

Příprava rozšíření na využití

Než budete pokračovat, ujistěte se, že:

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

Návod

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

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 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ů blob s konkrétní předponou názvu

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>%';

Import dat pomocí příkazu COPY FROM

Následující příklad ukazuje import dat z objektu blob, který se nachází storage_extension_sample.parquet 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 sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

COPY Pomocí příkazu zkopírujte data do cílové tabulky. Formát je odvozen jako Parquet z přípony souboru.

TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.parquet';

COPY Pomocí příkazu zkopírujte data do cílové tabulky. Vzhledem k tomu, že formát kódování nelze odvodit z přípony souboru, je explicitně určen prostřednictvím této FORMAT možnosti.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
COPY Pomocí příkazu zkopírujte data do cílové tabulky. Formát kódování lze odvodit z přípony souboru. Přítomnost záhlaví sloupců v prvním řádku ale musí být explicitně nakonfigurovaná prostřednictvím HEADERS možnosti.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Spuštěním následujícího SELECT příkazu potvrďte, že jsou data načtena do tabulky.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Export dat pomocí příkazu COPY TO

Následující příklady ukazují export dat z tabulky s názvem sample_data, do více objektů blob s různými názvy a charakteristiky, jako je jejich formát kódování, všechny, které se nacházejí v kontejneru <container_name> objektů blob v účtu <account_name>Azure Storage , prostřednictvím COPY příkazu:

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

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

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 FROM k naplnění obsahem ukázkové datové sady.

COPY Pomocí příkazu zkopírujte data z cílové tabulky. Určete, že formát kódování musí být parquet.

COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.parquet'
WITH (FORMAT 'parquet');

COPY Pomocí příkazu zkopírujte data z cílové tabulky. Určete, že formát kódování musí být CSV a první řádek výsledného souboru obsahuje záhlaví sloupců.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Spuštěním následujícího SELECT příkazu potvrďte, že objekt blob existuje v účtu úložiště.

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

Čtení obsahu z objektu blob

Funkce blob_get načte obsah jednoho konkrétního objektu blob 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 sample_data 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.

V tomto případě je dekodér, který se musí použít k analýze objektu blob, odvozen z přípony .parquet souboru.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
LIMIT 5;

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

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','storage_extension_sample.parquet')
AS res (
        id BIGINT PRIMARY KEY,
        sample_text TEXT,
        sample_integer INTEGER,
        sample_timestamp TIMESTAMP)
LIMIT 5;

Čtení, filtrování a úprava obsahu načteného z objektu blob

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-',id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
WHERE sample_integer=780
LIMIT 5;

Čtení obsahu ze souboru s vlastními možnostmi (záhlaví, oddělovače sloupců, řídicí znaky)

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>'
        ,'storage_extension_sample.csv'
        ,NULL::sample_data
        ,options := azure_storage.options_csv_get(header := 'true')
        );

Použití možnosti dekodéru

Tento příklad znázorňuje použití decoder možnosti. Pokud není možnost dekodéru k dispozici, je odvozena z přípony souboru. Pokud ale název souboru nemá příponu nebo pokud přípona názvu souboru neodpovídá příponě přidružené k dekodéru, který se musí použít k správné analýze obsahu souboru, můžete explicitně předat argument dekodéru.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'parquet_without_extension'
        , NULL::sample_data
        , decoder := 'parquet')
LIMIT 5;

Výpočet agregací 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 sample_integer, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
GROUP BY sample_integer
ORDER BY 2 DESC
LIMIT 5;

Zápis obsahu do objektu blob

Funkce blob_put sestaví obsah jednoho konkrétního objektu blob (sample_data_copy.parquet 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 sample_data_copy.parquet.

Formát kódování je odvozen jako parquet na základě přípony .parquetsouboru .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.parquet'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Formát kódování je odvozen jako CSV na základě přípony .csvsouboru .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.csv'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Formát kódování nelze odvodit, protože soubor nemá příponu souboru, takže je explicitně nakonfigurovaný jako parquet. Také je algoritmus komprese nastaven na zstd.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_parquet_data_copy_without_extension_with_zstd_compression'
        , top_5_sample_data
        ,'parquet'
        ,'zstd')
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

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ůžou odkazovat v této databázi, společně 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.