Contoh mulai cepat untuk ekstensi Azure Storage di Azure Database for PostgreSQL

Berikut ini adalah daftar contoh untuk membantu Anda mempelajari cara menggunakan ekstensi Azure Storage.

Membuat akun Azure Storage dan mengisinya dengan data

Buat akun Azure Storage. Untuk membuat akun Azure Storage, jika Anda belum memilikinya, kustomisasi nilai <resource_group>, , <location>, <account_name>dan <container_name>, dan jalankan perintah Azure CLI berikut:

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

Buat kontainer blob. Untuk membuat kontainer blob, jalankan Azure CLI berikut:

az storage container create --account-name $storage_account --name $blob_container -o tsv

Ambil salah satu dari dua kunci akses yang ditetapkan ke akun penyimpanan. Pastikan Anda menyalin nilai access_key karena Anda perlu meneruskannya sebagai argumen ke azure_storage.account_add di langkah berikutnya. Untuk mengambil kunci akses pertama dari dua kunci akses, jalankan perintah Azure CLI berikut:
```
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
```

Unduh file dengan himpunan data yang digunakan selama contoh, dan unggah ke kontainer blob Anda. Untuk mengunduh file dengan himpunan data, jalankan perintah Azure CLI berikut:

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

Nota

Anda dapat mencantumkan kontainer atau blob yang disimpan di dalamnya untuk akun penyimpanan tertentu, tetapi hanya jika pengguna atau peran PostgreSQL Anda diberikan izin pada referensi ke akun penyimpanan tersebut dengan menggunakan azure_storage.account_user_add. azure_storage_admin Anggota peran diberikan hak istimewa ini atas semua akun Azure Storage yang telah ditambahkan menggunakan azure_storage.account_add. Secara default, hanya anggota yang azure_pg_admin diberikan azure_storage_admin peran.

Membuat tabel tempat data dimuat

Mari kita buat tabel tempat kita mengimpor konten file yang kita unggah ke akun penyimpanan. Untuk melakukannya, sambungkan ke instans server fleksibel Azure Database for PostgreSQL Anda menggunakan PostgreSQL untuk Visual Studio Code (Pratinjau), psql, PgAdmin, atau klien preferensi Anda, dan jalankan pernyataan berikut:

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

Menyiapkan ekstensi untuk penggunaan

Sebelum melanjutkan, pastikan Anda:

Menambahkan kunci akses akun penyimpanan

Contoh ini menggambarkan cara menambahkan referensi ke akun penyimpanan, bersama dengan kunci akses akun penyimpanan tersebut yang diperlukan untuk mengakses kontennya melalui fungsionalitas yang disediakan oleh azure_storage ekstensi dalam instans server fleksibel Azure Database for PostgreSQL Anda.

<account_name> harus diatur ke nama akun penyimpanan Anda. Jika Anda menggunakan skrip sebelumnya, nilai ini harus cocok dengan nilai apa pun yang Anda tetapkan ke variabel lingkungan storage_account dalam skrip tersebut.

Demikian pula, <access_key> harus diatur ke nilai yang Anda ambil dari akun penyimpanan Anda.

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

Petunjuk / Saran

Jika Anda ingin mengambil nama akun penyimpanan dan salah satu kunci aksesnya dari portal Microsoft Azure, cari akun penyimpanan Anda, di menu sumber daya pilih Kunci akses, salin nama akun Penyimpanan dan salin bagian Kunci dari key1 (Anda harus memilih Tampilkan di samping kunci terlebih dahulu).

Memberikan akses ke pengguna atau peran pada referensi penyimpanan Azure Blob

Contoh ini menggambarkan cara memberikan akses ke pengguna atau peran bernama <regular_user>, sehingga pengguna PostgreSQL tersebut azure_storage dapat menggunakan ekstensi untuk mengakses blob yang disimpan dalam kontainer yang dihosting oleh akun penyimpanan Azure yang dirujuk.

<regular_user> harus diatur ke nama pengguna atau peran yang ada.

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

Mencantumkan semua blob dalam kontainer

Contoh ini menggambarkan cara mencantumkan semua blob yang ada di dalam kontainer <container_name> akun <account_name>penyimpanan .

<container_name> harus diatur ke nama kontainer blob Anda. Jika Anda menggunakan skrip sebelumnya, nilai ini harus cocok dengan nilai apa pun yang Anda tetapkan ke variabel lingkungan blob_container dalam skrip tersebut.

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

Mencantumkan blob dengan awalan nama tertentu

Contoh ini menggambarkan cara mencantumkan semua blob yang ada di dalam kontainer <container_name> akun <account_name>penyimpanan , yang nama blob-nya dimulai dengan <blob_name_prefix>.

<blob_name_prefix> harus diatur ke awalan apa pun yang Anda inginkan agar blob dijumlahkan untuk disertakan dalam namanya. Jika Anda ingin mengembalikan semua blob, Anda dapat mengatur parameter ini ke string kosong atau bahkan tidak menentukan nilai untuk parameter ini, dalam hal ini nilai default ke string kosong.

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

Atau, Anda dapat menggunakan sintaks berikut:

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

Mengimpor data menggunakan pernyataan COPY FROM

Contoh berikut menunjukkan impor data dari blob yang disebut storage_extension_sample.parquet yang berada di kontainer <container_name> blob di akun <account_name>Azure Storage , melalui COPY perintah :

Buat tabel yang cocok dengan skema file sumber:

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

COPY Gunakan pernyataan untuk menyalin data ke dalam tabel target. Format disimpulkan sebagai Parquet dari ekstensi file.

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

COPY Gunakan pernyataan untuk menyalin data ke dalam tabel target. Karena format pengodean tidak dapat disimpulkan dari ekstensi file, format tersebut secara eksplisit ditentukan melalui FORMAT opsi .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
COPY Gunakan pernyataan untuk menyalin data ke dalam tabel target. Format pengodean dapat disimpulkan dari ekstensi file. Namun, keberadaan header kolom di baris pertama perlu dikonfigurasi secara eksplisit melalui HEADERS opsi.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Jalankan pernyataan berikut SELECT untuk mengonfirmasi bahwa data dimuat ke dalam tabel.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Mengekspor data menggunakan pernyataan COPY TO

Contoh berikut menunjukkan ekspor data dari tabel yang disebut sample_data, ke beberapa blob dengan nama yang berbeda, dan karakteristik seperti format pengodeannya, yang semuanya berada di kontainer <container_name> blob di akun <account_name>Azure Storage , melalui COPY perintah :

Buat tabel yang cocok dengan skema file sumber:

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

Muat data ke dalam tabel. Jalankan pernyataan INSERT untuk mengisinya dengan beberapa baris sintetis, atau gunakan contoh pernyataan Impor data menggunakan COPY FROM untuk mengisinya dengan konten himpunan data sampel.

COPY Gunakan pernyataan untuk menyalin data dari tabel target. Tentukan bahwa format pengodean harus parquet.

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

COPY Gunakan pernyataan untuk menyalin data dari tabel target. Tentukan bahwa format pengodean harus CSV dan baris pertama dari file yang dihasilkan berisi header kolom.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Jalankan pernyataan berikut SELECT untuk mengonfirmasi bahwa blob ada di akun penyimpanan.

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

Membaca konten dari blob

Fungsi ini blob_get mengambil konten dari satu blob tertentu, dalam kontainer <container_name> penyimpanan yang <account_name> dirujuk. Untuk blob_get mengetahui cara mengurai data, Anda dapat meneruskan nilai dalam formulir NULL::table_name, di mana table_name mengacu pada tabel yang skemanya cocok dengan blob yang sedang dibaca. Dalam contoh, ini mengacu pada tabel yang sample_data kita buat di awal.

<blob_name> harus diatur ke jalur lengkap blob yang kontennya ingin Anda baca.

Dalam hal ini, dekoder yang harus digunakan untuk mengurai blob disimpulkan dari .parquet ekstensi file.

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

Atau, Anda dapat secara eksplisit menentukan skema hasil menggunakan AS klausa setelah fungsi blob_get .

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;

Membaca, memfilter, dan memodifikasi konten yang dibaca dari blob

Contoh ini menggambarkan kemungkinan untuk memfilter dan memodifikasi konten yang diimpor dari blob, sebelum memuatnya ke dalam tabel 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;

Membaca konten dari file dengan opsi kustom (header, pemisah kolom, karakter escape)

Contoh ini menggambarkan bagaimana Anda dapat menggunakan pemisah kustom dan karakter escape, dengan meneruskan hasil options_copy ke options argumen.

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

Gunakan opsi dekoder

Contoh ini mengilustrasikan penggunaan decoder opsi . Ketika opsi dekoder tidak ada, opsi tersebut disimpulkan dari ekstensi file. Tetapi ketika nama file tidak memiliki ekstensi, atau ketika ekstensi nama file tersebut tidak sesuai dengan yang terkait dengan dekoder yang harus digunakan untuk mengurai konten file dengan benar, Anda dapat secara eksplisit meneruskan argumen decoder.

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

Menghitung agregasi atas konten blob

Contoh ini menggambarkan bagaimana Anda dapat melakukan operasi agregasi atas informasi yang disimpan dalam kontainer blob, tanpa perlu mengimpor konten blob ke tabel 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;

Menulis konten ke blob

Fungsi ini blob_put menyusun konten dari satu blob tertentu (sample_data_copy.parquet dalam hal ini), dan mengunggahnya ke kontainer <container_name> penyimpanan yang <account_name> dirujuk. Contoh ini digunakan blob_get untuk membuat sekumpulan lima baris, yang kemudian diteruskan ke blob_put fungsi agregat yang mengunggahnya sebagai blob bernama sample_data_copy.parquet.

Format pengodean disimpulkan sebagai parkket, berdasarkan ekstensi .parquetfile .

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;

Format pengodean disimpulkan sebagai CSV, berdasarkan ekstensi .csvfile .

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;

Format pengodean tidak dapat disimpulkan karena file tidak memiliki ekstensi file, sehingga secara eksplisit dikonfigurasi sebagai parquet. Selain itu, algoritma kompresi diatur ke 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;

Mencantumkan semua referensi ke akun penyimpanan Azure

Contoh ini menggambarkan cara mengetahui akun azure_storage penyimpanan Azure mana yang dapat direferensikan ekstensi dalam database ini, bersama dengan jenis autentikasi yang digunakan untuk mengakses setiap akun penyimpanan, dan pengguna atau peran mana yang diberikan izin, melalui fungsi azure_storage.account_user_add , untuk mengakses akun penyimpanan Azure tersebut melalui fungsionalitas yang disediakan oleh ekstensi.

SELECT * FROM azure_storage.account_list();

Mencabut akses dari pengguna atau peran pada referensi penyimpanan Azure Blob

Contoh ini menggambarkan cara mencabut akses dari pengguna atau peran bernama <regular_user>, sehingga pengguna PostgreSQL tersebut azure_storage tidak dapat menggunakan ekstensi untuk mengakses blob yang disimpan dalam kontainer yang dihosting oleh akun penyimpanan Azure yang dirujuk.