Rövid útmutató példák az Azure Storage-bővítményhez az Azure Database for PostgreSQL-ben

Az alábbi példák segítségével megtudhatja, hogyan használhatja az Azure Storage-bővítményt.

Azure Storage-fiók létrehozása és feltöltése adatokkal

Azure Storage-fiók létrehozása. Azure Storage-fiók létrehozásához, ha még nem rendelkezik ilyen fiókkal, szabja testre a , <resource_group>, <location>és , értékeket<account_name>, és <container_name>futtassa a következő Azure CLI-parancsot:

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

Blobtároló létrehozása. A blobtároló létrehozásához futtassa a következő Azure CLI-t:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Kérje le a tárfiókhoz rendelt két hozzáférési kulcs egyikét. Győződjön meg arról, hogy a access_key értékét átmásolja argumentumként a azure_storage.account_add fájlba egy következő lépésben. A két hozzáférési kulcs közül az első lekéréséhez futtassa a következő Azure CLI-parancsot:
```
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
```

Töltse le a fájlt a példák során használt adatkészlettel, és töltse fel a blobtárolóba. A fájl adatkészlettel való letöltéséhez futtassa a következő Azure CLI-parancsot:

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

Megjegyzés:

A tárolókat vagy a bennük tárolt blobokat egy adott tárfiókhoz listázhatja, de csak akkor, ha a PostgreSQL-felhasználó vagy -szerepkör engedélyt kap a tárfiókra való hivatkozáshoz a azure_storage.account_user_add használatával. A szerepkör tagjai ezt a azure_storage_admin jogosultságot kapják a azure_storage.account_add használatával hozzáadott összes Azure Storage-fiókhoz. Alapértelmezés szerint csak a azure_pg_admin tagok kapják meg a szerepkört azure_storage_admin .

Olyan tábla létrehozása, amelyben az adatok betöltve vannak

Hozzuk létre azt a táblát, amelybe importáljuk a tárfiókba feltöltött fájlok tartalmát. Ehhez csatlakozzon rugalmas Azure Database for PostgreSQL-kiszolgálóhoz a PostgreSQL for Visual Studio Code (előzetes verzió), a psql, a PgAdmin vagy az Ön által preferált ügyfél használatával, és hajtsa végre a következő utasítást:

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

A bővítmény előkészítése a használathoz

A folytatás előtt győződjön meg arról, hogy:

Tárfiók hozzáférési kulcsának hozzáadása

Ez a példa bemutatja, hogyan adhat hozzá hivatkozást egy tárfiókhoz, valamint a tárfiók hozzáférési kulcsát, amely a rugalmas Azure Database for PostgreSQL-kiszolgáló példányában a bővítmény által azure_storage biztosított funkciókon keresztül szükséges a tartalom eléréséhez.

<account_name> A tárfiók nevét kell megadni. Ha az előző szkripteket használta, ennek az értéknek meg kell egyeznie a szkriptekben beállított storage_account környezeti változó értékével.

Hasonlóképpen, <access_key> a tárfiókból lekért értékre kell állítani.

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

Jótanács

Ha le szeretné kérni a tárfiók nevét és egyik hozzáférési kulcsát az Azure Portalról, keresse meg a tárfiókot, az erőforrás menüjében válassza a Hozzáférési kulcsok lehetőséget, másolja ki a Tárfiók nevét , és másolja a kulcsot az 1. kulcsból (először a Megjelenítés gombot kell választania a kulcs mellett).

Hozzáférés biztosítása egy felhasználóhoz vagy szerepkörhöz az Azure Blob Storage-referencia alapján

Ez a példa bemutatja, hogyan adhat hozzáférést egy felhasználónak vagy szerepkörnek, <regular_user>hogy az ilyen PostgreSQL-felhasználó a azure_storage bővítmény használatával hozzáférhessen a hivatkozott Azure Storage-fiók által üzemeltetett tárolókban tárolt blobokhoz.

<regular_user> egy meglévő felhasználó vagy szerepkör nevére kell állítani.

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

Tároló összes blobának listázása

Ez a példa bemutatja, hogyan listázhatja az összes meglévő blobot a tárfiók <container_name>tárolójába<account_name>.

<container_name> A blobtároló nevét kell megadni. Ha az előző szkripteket használta, ennek az értéknek meg kell egyeznie a szkriptekben beállított blob_container környezeti változó értékével.

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

Adott névelőtaggal rendelkező blobok listázása

Ez a példa bemutatja, hogyan listázhatja az összes meglévő blobot a tárfiók <container_name>tárolójába<account_name>, amelynek blobneve a következővel <blob_name_prefix>kezdődik: .

<blob_name_prefix> A blobokat a nevükben fel kell sorolni. Ha az összes blobot vissza szeretné adni, beállíthatja ezt a paramétert üres sztringre, vagy nem is adhat meg értéket ehhez a paraméterhez, ebben az esetben az érték alapértelmezés szerint üres sztring lesz.

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

Másik lehetőségként használhatja a következő szintaxist:

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

Adatok importálása COPY FROM utasítással

Az alábbi példa egy olyan blobból storage_extension_sample.parquet származó adatok importálását mutatja be, amely az Azure Storage-fiók <container_name>blobtárolójában <account_name> található a COPY parancson keresztül:

Hozzon létre egy táblázatot, amely megfelel a forrásfájl sémájának:

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

COPY Egy utasítással adatokat másolhat a céltáblába. A formátum a fájl kiterjesztése után parquetként lesz kikövetkeztetve.

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

COPY Egy utasítással adatokat másolhat a céltáblába. Mivel a kódolási formátum nem vonható le a fájlbővítményből, explicit módon van megadva a FORMAT beállításon keresztül.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
COPY Egy utasítással adatokat másolhat a céltáblába. A kódolási formátum a fájlkiterjesztésből következtethető. Az oszlopfejlécek első sorban való jelenlétét azonban explicit módon kell konfigurálni a beállítással HEADERS .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Az alábbi SELECT utasítás végrehajtásával ellenőrizze, hogy az adatok be vannak-e töltve a táblába.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Adatok exportálása COPY TO utasítással

Az alábbi példák az adatok exportálását mutatják be egy nevű sample_datatáblából több különböző nevű blobba, és olyan jellemzőkkel, mint például a kódolási formátumuk, amelyek mindegyike az Azure Storage-fiók <account_name>blobtárolójában <container_name> található a COPY parancson keresztül:

Hozzon létre egy táblázatot, amely megfelel a forrásfájl sémájának:

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

Adatok betöltése a táblába. Futtassa az INSERT utasításokat több szintetikus sor kitöltéséhez, vagy használja az Adatok importálása a COPY FROM utasítás példájával a mintaadatkészlet tartalmával való feltöltéséhez.

Az utasítással COPY adatokat másolhat ki a céltáblából. Adja meg, hogy a kódolási formátumnak parquetnek kell lennie.

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

Az utasítással COPY adatokat másolhat ki a céltáblából. Adja meg, hogy a kódolási formátumnak CSV-nek kell lennie, és az eredményül kapott fájl első sora oszlopfejléceket tartalmaz.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

A következő SELECT utasítás végrehajtásával ellenőrizze, hogy a blob létezik-e a tárfiókban.

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

Tartalom olvasása blobból

A blob_get függvény egy adott blob tartalmát kéri le a tároló hivatkozott tárolójában <container_name><account_name> . Annak érdekében blob_get , hogy megtudja, hogyan elemezheti az adatokat, átadhat egy értéket az űrlapon NULL::table_name, ahol table_name egy olyan táblára hivatkozik, amelynek sémája megegyezik az éppen olvasott blobéval. A példában az sample_data elején létrehozott táblára hivatkozik.

<blob_name> annak a blobnak a teljes elérési útját kell megadnia, amelynek a tartalmát el szeretné olvasni.

Ebben az esetben a blob elemzéséhez használandó dekóder a .parquet fájlkiterjesztésből következik.

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

Azt is megteheti, hogy explicit módon definiálja az eredmény sémáját a ASblob_get függvény utáni záradék használatával.

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;

Blobból beolvasott tartalom olvasása, szűrése és módosítása

Ez a példa bemutatja a blobból importált tartalom szűrésének és módosításának lehetőségét, mielőtt betöltené azt egy SQL-táblába.

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;

Tartalom olvasása fájlból egyéni beállításokkal (fejlécek, oszlophatárolók, feloldó karakterek)

Ez a példa bemutatja, hogyan használhat egyéni elválasztó és feloldó karaktereket úgy, hogy a options_copy eredményét átadja az options argumentumnak.

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

A dekóder használata

Ez a példa a beállítás használatát decoder mutatja be. Ha a dekóder nem jelenik meg, a fájl kiterjesztése alapján következtetünk rá. Ha azonban a fájlnév nem rendelkezik kiterjesztéssel, vagy ha a fájlnévkiterjesztés nem felel meg a dekóderhez társított kiterjesztésnek, amelyet a fájl tartalmának megfelelő elemzéséhez kell használni, explicit módon átadhatja a dekóder argumentumot.

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

Blob tartalmának összesítése

Ez a példa bemutatja, hogyan hajthat végre összesítési műveleteket egy blobtárolóban tárolt információkon anélkül, hogy a blob tartalmát postgreSQL-táblákba kellene importálnia.

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;

Tartalom írása blobba

A blob_put függvény egy adott blob tartalmát írja össze (sample_data_copy.parquet ebben az esetben), és feltölti a tároló hivatkozott tárolójára <container_name><account_name> . Ez a példa öt sorból álló csoportot hoz blob_get létre, amelyet aztán átad a rendszer az blob_put összesítő függvénynek, amely feltölti őket egy blobként nevű sample_data_copy.parquetblobként.

A kódolási formátum a fájlkiterjesztés .parquetalapján parquetként van kikövetkeztetve.

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;

A kódolási formátum CSV-ként van kikövetkeztetve a fájlkiterjesztés .csvalapján.

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;

A kódolási formátum nem vonható le, mert a fájl nem rendelkezik fájlkiterjesztéssel, ezért explicit módon van konfigurálva parquet. A tömörítési algoritmus is a következőre zstdvan állítva: .

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;

Az Azure Storage-fiókokra mutató összes hivatkozás listázása

Ez a példa bemutatja, hogyan állapítható meg, hogy a bővítmény mely Azure Storage-fiókokra azure_storage hivatkozhat ebben az adatbázisban, valamint az egyes tárfiókok eléréséhez használt hitelesítés típusát, valamint hogy mely felhasználók vagy szerepkörök kapnak engedélyt a azure_storage.account_user_add függvényen keresztül az Adott Azure-tárfiók eléréséhez a bővítmény által biztosított funkciókon keresztül.

SELECT * FROM azure_storage.account_list();

Hozzáférés visszavonása egy felhasználótól vagy szerepkörtől az Azure Blob Storage-referencia alapján

Ez a példa bemutatja, hogyan vonhatja vissza a hozzáférést egy nevesített <regular_user>felhasználótól vagy szerepkörtől, hogy az ilyen PostgreSQL-felhasználó ne tudja használni a azure_storage bővítményt a hivatkozott Azure Storage-fiók által üzemeltetett tárolókban tárolt blobok eléréséhez.