ekstensi pg_azure_storage

Penting

Azure Cosmos DB for PostgreSQL tidak lagi didukung untuk proyek baru. Jangan gunakan layanan ini untuk proyek baru. Sebagai gantinya, gunakan salah satu dari dua layanan ini:

• Gunakan Azure Cosmos DB for NoSQL untuk solusi database terdistribusi yang dirancang untuk skenario skala tinggi dengan perjanjian tingkat layanan ketersediaan (SLA) 99,999%, skala otomatis instan, dan failover otomatis di beberapa wilayah.

• Gunakan fitur Elastic Clusters dari Azure Database For PostgreSQL untuk PostgreSQL yang dipecah menggunakan ekstensi Citus sumber terbuka.

Ekstensi pg_azure_storage memungkinkan Anda memuat data dalam beberapa format file langsung dari penyimpanan blob Azure ke kluster Azure Cosmos DB for PostgreSQL Anda. Mengaktifkan ekstensi juga membuka kemampuan baru perintah COPY . Kontainer dengan tingkat akses "Privat" atau "Blob" memerlukan penambahan kunci akses privat.

Anda dapat membuat ekstensi dengan menjalankan:

SELECT create_extension('azure_storage');

azure_storage.account_add

Fungsi memungkinkan penambahan akses ke akun penyimpanan.

azure_storage.account_add
        (account_name_p text
        ,account_key_p text);

Argumen

account_name_p

Akun penyimpanan blob Azure (ABS) berisi semua objek ABS Anda: blob, file, antrean, dan tabel. Akun penyimpanan menyediakan namespace unik untuk ABS Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

account_key_p

Kunci akses penyimpanan blob Azure (ABS) Anda mirip dengan kata sandi akar untuk akun penyimpanan Anda. Selalu berhati-hatilah untuk melindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman. Kunci akun disimpan dalam tabel yang dapat diakses oleh superuser postgres, azure_storage_admin dan semua peran yang diberikan izin admin tersebut. Untuk melihat akun penyimpanan mana yang ada, gunakan fungsi account_list.

azure_storage.account_remove

Fungsi memungkinkan pencabutan akses akun ke akun penyimpanan.

azure_storage.account_remove
        (account_name_p text);

Argumen

account_name_p

Akun penyimpanan blob Azure (ABS) berisi semua objek ABS Anda: blob, file, antrean, dan tabel. Akun penyimpanan menyediakan namespace unik untuk ABS Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

azure_storage.account_user_add

Fungsi ini memungkinkan penambahan akses untuk peran ke akun penyimpanan.

azure_storage.account_user_add
        ( account_name_p text
        , user_p regrole);

Argumen

account_name_p

Akun penyimpanan blob Azure (ABS) berisi semua objek ABS Anda: blob, file, antrean, dan tabel. Akun penyimpanan menyediakan namespace unik untuk ABS Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

user_p

Peran yang dibuat oleh pengguna terlihat pada kluster.

Catatan

account_user_add,account_add,account_remove,account_user_remove fungsi memerlukan izin pengaturan untuk setiap node individu dalam kluster.

azure_storage.account_user_remove

Fungsi ini memungkinkan penghapusan akses untuk peran ke akun penyimpanan.

azure_storage.account_user_remove
        (account_name_p text
        ,user_p regrole);

Argumen

account_name_p

Akun penyimpanan blob Azure (ABS) berisi semua objek ABS Anda: blob, file, antrean, dan tabel. Akun penyimpanan menyediakan namespace unik untuk ABS Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

user_p

Peran yang dibuat oleh pengguna terlihat pada kluster.

azure_storage.account_list

Fungsi ini mencantumkan akun & peran yang memiliki akses ke penyimpanan blob Azure.

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

Argumen

account_name

Akun penyimpanan blob Azure (ABS) berisi semua objek ABS Anda: blob, file, antrean, dan tabel. Akun penyimpanan menyediakan namespace unik untuk ABS Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

allowed_users

Mencantumkan pengguna yang memiliki akses ke penyimpanan blob Azure.

Tipe hasil

TABLE

azure_storage.blob_list

Fungsi ini mencantumkan file blob yang tersedia dalam kontainer pengguna dengan propertinya.

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;

Argumen

account_name

menyediakan storage account name namespace unik untuk data penyimpanan Azure Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

container_name

Kontainer mengatur kumpulan blob, mirip dengan direktori dalam sistem file. Akun penyimpanan dapat mencakup kontainer dengan jumlah tak terbatas, dan kontainer dapat menyimpan blob dengan jumlah tak terbatas. Nama kontainer harus merupakan nama DNS yang valid, karena membentuk bagian dari URI unik yang digunakan untuk merujuk kontainer atau blobnya. Ikuti aturan ini saat menamai kontainer:

• Nama kontainer dapat sepanjang 3 sampai 63 karakter.
• Nama kontainer harus diawali dengan huruf atau angka, dan hanya dapat berisi huruf kecil, angka, dan karakter tanda hubung (-).
• Dua atau beberapa tanda hubung berturut-turut tidak diizinkan dalam nama kontainer.

URI untuk kontainer mirip dengan: https://myaccount.blob.core.windows.net/mycontainer

awalan

Mengembalikan file dari kontainer blob dengan inisial string yang cocok.

jalan

Jalur direktori blob Azure yang memenuhi syarat penuh.

byte

Ukuran objek file dalam byte.

last_modified

Kapan konten file terakhir diubah.

etag

Properti ETag digunakan untuk konkurensi optimis selama pembaruan. Ini bukan tanda waktu karena ada properti lain yang disebut Tanda Waktu yang menyimpan terakhir kali rekaman diperbarui. Misalnya, jika Anda memuat entitas dan ingin memperbaruinya, ETag harus cocok dengan apa yang saat ini disimpan. Mengatur ETag yang sesuai penting karena jika Anda memiliki beberapa pengguna yang mengedit item yang sama, Anda tidak ingin mereka menimpa perubahan satu sama lain.

content_type

Objek Blob mewakili blob, yang merupakan objek seperti file dari data mentah yang tidak dapat diubah. Mereka dapat dibaca sebagai teks atau data biner, atau dikonversi menjadi ReadableStream sehingga metodenya dapat digunakan untuk memproses data. Blob dapat mewakili data yang belum tentu dalam format asli JavaScript.

content_encoding

Azure Storage memungkinkan Anda menentukan properti Pengodean Konten pada blob. Untuk konten terkompresi, Anda dapat mengatur properti menjadi GZIP. Saat browser mengakses konten, browser secara otomatis mendekompresi konten.

content_hash

Hash ini digunakan untuk memverifikasi integritas blob selama transportasi. Ketika header ini ditentukan, layanan penyimpanan memeriksa hash yang telah tiba dengan yang dikirim. Jika dua hash tidak cocok, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).

Tipe hasil

Catatan SETOF

Catatan

Izin Sekarang Anda dapat mencantumkan kontainer yang diatur ke tingkat akses Privat dan Blob untuk penyimpanan tersebut citus usertetapi hanya sebagai , yang memiliki azure_storage_admin peran yang diberikan kepadanya. Jika Anda membuat pengguna baru bernama support, pengguna tersebut tidak akan diizinkan untuk mengakses konten kontainer secara default.

azure_storage.blob_get

Fungsi ini memungkinkan pemuatan konten file \ file dari dalam kontainer, dengan dukungan tambahan tentang pemfilteran atau manipulasi data, sebelum mengimpor.

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;

Ada versi fungsi yang kelebihan beban, yang berisi parameter rekam yang memungkinkan Anda menentukan rekaman format output dengan nyaman.

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;

Argumen

akun

Akun penyimpanan menyediakan namespace unik untuk data Azure Storage Anda yang dapat diakses dari mana saja di seluruh dunia melalui HTTPS.

container

Kontainer mengatur kumpulan blob, mirip dengan direktori dalam sistem file. Akun penyimpanan dapat mencakup kontainer dengan jumlah tak terbatas, dan kontainer dapat menyimpan blob dengan jumlah tak terbatas. Nama kontainer harus merupakan nama DNS yang valid, karena membentuk bagian dari URI unik yang digunakan untuk merujuk kontainer atau blobnya.

jalan

Nama blob yang ada dalam kontainer.

Rec

Tentukan struktur output rekaman.

Decoder

Tentukan decoder format blob dapat diatur ke otomatis (default) atau salah satu nilai berikut

deskripsi decoder

Format	Keterangan
CSV	Format nilai yang dipisahkan koma yang digunakan oleh PostgreSQL COPY
tsv	Nilai yang dipisahkan tab, format SALIN PostgreSQL default
biner	Format SALINAN PostgreSQL Biner
kirim pesan teks	File yang berisi nilai teks tunggal (misalnya, JSON atau XML besar)

pemadatan

Menentukan format kompresi. Opsi yang tersedia adalah auto, gzip & . none Penggunaan auto opsi (default), menebak kompresi berdasarkan ekstensi file (.gz == gzip). Opsi none memaksa untuk mengabaikan ekstensi dan tidak mencoba mendekode. Sementara gzip memaksa menggunakan dekoder gzip (saat Anda memiliki file gzip dengan ekstensi non-standar). Saat ini kami tidak mendukung format kompresi lainnya untuk ekstensi.

opsi

Untuk menangani header kustom, pemisah kustom, karakter escape, dll., options bekerja dengan cara COPY yang sama dengan perintah di PostgreSQL, parameter digunakan untuk blob_get fungsi.

Tipe hasil

Catatan SETOF / anyelement

Catatan

Ada empat fungsi utilitas, yang disebut sebagai parameter dalam blob_get yang membantu membangun nilai untuk itu. Setiap fungsi utilitas ditunjuk untuk dekoder yang cocok dengan namanya.

azure_storage.options_csv_get

Fungsi ini bertindak sebagai fungsi utilitas yang disebut sebagai parameter dalam blob_get, yang berguna untuk mendekode konten 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;

Argumen

pemisah

Menentukan karakter yang memisahkan kolom dalam setiap baris (baris) file. Defaultnya adalah karakter tab dalam format teks, koma dalam format CSV. Ini harus menjadi karakter satu byte.

null_string

Menentukan string yang mewakili nilai null. Defaultnya adalah \N (backslash-N) dalam format teks, dan string kosong yang tidak dikutip dalam format CSV. Anda mungkin lebih suka string kosong bahkan dalam format teks untuk kasus di mana Anda tidak ingin membedakan null dari string kosong.

header

Menentukan bahwa file berisi baris header dengan nama setiap kolom dalam file. Pada output, baris pertama berisi nama kolom dari tabel.

kuotasi

Menentukan karakter kutipan yang akan digunakan saat nilai data dikutip. Defaultnya adalah tanda kutip ganda. Ini harus menjadi karakter satu byte.

melarikan diri

Menentukan karakter yang akan muncul sebelum karakter data yang cocok dengan nilai QUOTE. Defaultnya sama dengan nilai QUOTE (sehingga karakter kutipan digandakan jika muncul dalam data). Ini harus menjadi karakter satu byte.

force_not_null

Jangan cocokkan nilai kolom yang ditentukan dengan string null. Dalam kasus default di mana string null kosong, itu berarti bahwa nilai kosong dibaca sebagai string panjang nol daripada null, bahkan ketika tidak dikutip.

force_null

Cocokkan nilai kolom yang ditentukan dengan string null, meskipun telah dikutip, dan jika kecocokan ditemukan, atur nilai ke NULL. Dalam kasus default di mana string null kosong, string tersebut mengonversi string kosong yang dikutip menjadi NULL.

content_encoding

Menentukan bahwa file dikodekan dalam encoding_name. Jika opsi dihilangkan, pengodean klien saat ini digunakan.

Tipe hasil

jsonb

azure_storage.options_copy

Fungsi ini bertindak sebagai fungsi utilitas yang disebut sebagai parameter dalam 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;

Argumen

pemisah

Menentukan karakter yang memisahkan kolom dalam setiap baris (baris) file. Defaultnya adalah karakter tab dalam format teks, koma dalam format CSV. Ini harus menjadi karakter satu byte.

null_string

Menentukan string yang mewakili nilai null. Defaultnya adalah \N (backslash-N) dalam format teks, dan string kosong yang tidak dikutip dalam format CSV. Anda mungkin lebih suka string kosong bahkan dalam format teks untuk kasus di mana Anda tidak ingin membedakan null dari string kosong.

header

Menentukan bahwa file berisi baris header dengan nama setiap kolom dalam file. Pada output, baris pertama berisi nama kolom dari tabel.

kuotasi

Menentukan karakter kutipan yang akan digunakan saat nilai data dikutip. Defaultnya adalah tanda kutip ganda. Ini harus menjadi karakter satu byte.

melarikan diri

Menentukan karakter yang akan muncul sebelum karakter data yang cocok dengan nilai QUOTE. Defaultnya sama dengan nilai QUOTE (sehingga karakter kutipan digandakan jika muncul dalam data). Ini harus menjadi karakter satu byte.

force_quote

Memaksa kutipan untuk digunakan untuk semua nilai non-NULL di setiap kolom yang ditentukan. Output NULL tidak pernah dikutip. Jika * ditentukan, nilai non-NULL dikutip di semua kolom.

force_not_null

Jangan cocokkan nilai kolom yang ditentukan dengan string null. Dalam kasus default di mana string null kosong, itu berarti bahwa nilai kosong dibaca sebagai string panjang nol daripada null, bahkan ketika tidak dikutip.

force_null

Cocokkan nilai kolom yang ditentukan dengan string null, meskipun telah dikutip, dan jika kecocokan ditemukan, atur nilai ke NULL. Dalam kasus default di mana string null kosong, string tersebut mengonversi string kosong yang dikutip menjadi NULL.

content_encoding

Menentukan bahwa file dikodekan dalam encoding_name. Jika opsi dihilangkan, pengodean klien saat ini digunakan.

Tipe hasil

jsonb

azure_storage.options_tsv

Fungsi ini bertindak sebagai fungsi utilitas yang disebut sebagai parameter dalam blob_get. Ini berguna untuk mendekode konten tsv.

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

Argumen

pemisah

Menentukan karakter yang memisahkan kolom dalam setiap baris (baris) file. Defaultnya adalah karakter tab dalam format teks, koma dalam format CSV. Ini harus menjadi karakter satu byte.

null_string

Menentukan string yang mewakili nilai null. Defaultnya adalah \N (backslash-N) dalam format teks, dan string kosong yang tidak dikutip dalam format CSV. Anda mungkin lebih suka string kosong bahkan dalam format teks untuk kasus di mana Anda tidak ingin membedakan null dari string kosong.

content_encoding

Menentukan bahwa file dikodekan dalam encoding_name. Jika opsi dihilangkan, pengodean klien saat ini digunakan.

Tipe hasil

jsonb

azure_storage.options_binary

Fungsi ini bertindak sebagai fungsi utilitas yang disebut sebagai parameter dalam blob_get. Ini berguna untuk mendekode konten biner.

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

Argumen

content_encoding

Menentukan bahwa file dikodekan dalam encoding_name. Jika opsi ini dihilangkan, pengodean klien saat ini digunakan.

Jenis Hasil

jsonb

Catatan

Izin Sekarang Anda dapat mencantumkan kontainer yang diatur ke tingkat akses Privat dan Blob untuk penyimpanan tersebut citus usertetapi hanya sebagai , yang memiliki azure_storage_admin peran yang diberikan kepadanya. Jika Anda membuat pengguna baru bernama dukungan, pengguna tersebut tidak akan diizinkan untuk mengakses konten kontainer secara default.

Contoh

Contoh yang digunakan menggunakan contoh akun (pgquickstart) penyimpanan Azure dengan file kustom yang diunggah untuk ditambahkan ke cakupan kasus penggunaan yang berbeda. Kita dapat memulai dengan membuat tabel yang digunakan di seluruh kumpulan contoh yang digunakan.

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

Menambahkan kunci akses akun penyimpanan (wajib untuk tingkat akses = privat)

Contoh ini mengilustrasikan penambahan kunci akses untuk akun penyimpanan guna mendapatkan akses untuk kueri dari sesi pada kluster Azure Cosmos DB for Postgres.

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

Tip

Di akun penyimpanan Anda, buka Kunci akses. Salin nama akun Penyimpanan dan salin bagian Kunci dari key1 (Anda harus memilih Tampilkan di samping kunci terlebih dahulu).

Menghapus kunci akses akun penyimpanan

Contoh ini mengilustrasikan penghapusan kunci akses untuk akun penyimpanan. Tindakan ini akan mengakibatkan penghapusan akses ke file yang dihosting dalam wadah privat dalam kontainer.

SELECT azure_storage.account_remove('pgquickstart');

Menambahkan akses untuk peran ke penyimpanan Azure Blob

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

Mencantumkan semua peran dengan akses di penyimpanan Azure Blob

SELECT * FROM azure_storage.account_list();

Menghapus peran dengan akses di penyimpanan Azure Blob

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

Mencantumkan objek dalam public kontainer

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

Mencantumkan objek dalam private kontainer

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

Catatan

Menambahkan kunci akses adalah wajib.

Mencantumkan objek dengan inisial string tertentu dalam kontainer publik

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

Atau

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

Membaca konten dari objek dalam kontainer

Fungsi ini blob_get mengambil file dari penyimpanan blob. Agar blob_get tahu cara mengurai data, Anda dapat meneruskan nilai (NULL::table_name), yang memiliki format yang sama dengan file.

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

Atau, kita dapat secara eksplisit menentukan kolom dalam FROM klausa.

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;

Gunakan opsi dekoder

Contoh mengilustrasikan penggunaan decoder opsi. Format biasanya disimpulkan dari ekstensi file, tetapi ketika konten file tidak memiliki ekstensi yang cocok, Anda dapat meneruskan argumen dekoder.

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

Gunakan kompresi dengan opsi dekoder

Contoh menunjukkan cara memberlakukan menggunakan kompresi gzip pada file terkompresi gzip tanpa ekstensi .gz standar.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events-compressed'
        , NULL::events
        , decoder := 'csv'
        , compression := 'gzip')
LIMIT 5;

Impor konten yang difilter & ubah sebelum memuat dari objek format csv

Contoh ini mengilustrasikan kemungkinan untuk memfilter & mengubah konten yang diimpor dari objek dalam kontainer sebelum memuatnya ke dalam tabel SQL.

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Mengkueri konten dari file dengan header, pemisah kustom, karakter escape

Anda dapat menggunakan pemisah kustom dan karakter escape dengan meneruskan hasil azure_storage.options_copy ke options argumen.

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

Kueri agregasi pada konten objek dalam kontainer

Dengan cara ini Anda bisa mengkueri data tanpa mengimpornya.

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;

Langkah berikutnya

Cara menggunakan Azure Blob Storage dengan perintah COPY

Cara menyerap data menggunakan pg_azure_storage