Esnek PostgreSQL için Azure Veri Tabanı sunucudaki Azure Depolama uzantısı için hızlı başlangıç örnekleri

Aşağıdaki örnekler, Azure Depolama uzantısını kullanmayı öğrenmenize yardımcı olur.

Azure Depolama hesabı oluşturma ve bunu verilerle doldurma

Bir Azure Depolama hesabı oluşturun. Azure Depolama hesabı oluşturmak için, henüz yoksa <resource_group>, <location>, <account_name> ve <container_name> değerlerini özelleştirin ve aşağıdaki Azure CLI komutunu çalıştırın:

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

Blob kapsayıcısı oluşturma.

Blob kapsayıcısını oluşturmak için aşağıdaki Azure CLI komutunu çalıştırın:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Depolama hesabına atanan iki erişim anahtarından birini alın. Sonraki bir adımda azure_storage.account_add öğesine bağımsız değişken olarak geçirmeniz gerektiğinden erişim anahtarınızın değerini kopyaladığınızdan emin olun.

İki erişim anahtarından ilkini almak için aşağıdaki Azure CLI komutunu çalıştırın:
```
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
```

Örnekler sırasında kullanılan veri kümesini içeren dosyayı indirin ve blob kapsayıcınıza yükleyin.

Veri kümesini içeren dosyayı indirmek için aşağıdaki Azure CLI komutunu çalıştırın:

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

Uyarı

Kapsayıcıları veya belirli bir depolama hesabı için içinde depolanan blobları listeleyebilirsiniz, ancak yalnızca PostgreSQL kullanıcınıza veya rolüne azure_storage.account_user_add kullanarak söz konusu depolama hesabına başvuru izni verildiğinde. Rolün üyelerineazure_storage_admin, azure_storage.account_add kullanılarak eklenen tüm Azure Depolama hesaplarına göre bu ayrıcalık verilir. Varsayılan olarak, rolü yalnızca üyelerine azure_pg_adminazure_storage_admin verilir.

Verilerin yüklendiği bir tablo oluşturma

Depolama hesabına yüklediğiniz dosyaların içeriğini içeri aktardığınız tabloyu oluşturun. Bunu yapmak için Visual Studio Code için PostgreSQL (Önizleme), psql, PgAdmin veya tercihinizin istemcisini kullanarak esnek PostgreSQL için Azure Veri Tabanı sunucu örneğine bağlanın ve aşağıdaki deyimi yürütun:

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

Uzantıyı kullanıma hazırlama

Devam etmeden önce şunları yaptığınızdan emin olun:

Depolama hesabının erişim anahtarını ekleme

Bu örnekte, depolama hesabının erişim anahtarıyla birlikte bir depolama hesabına nasıl başvuru ekleneceği gösterilmektedir. Depolama hesabının içeriğine erişmek için, azure_storage PostgreSQL için Azure Veri Tabanı esnek sunucu örneğinizdeki uzantı erişim anahtarını gerektirir.

Depolama hesabınızın adına ayarlayın <account_name> . Önceki betikleri kullandıysanız, bu değer bu betiklerde ortam değişkeni için storage_account ayarladığınız değerle eşleşmelidir.

Depolama hesabınızdan getirdiğiniz değere ayarlayın <access_key> .

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

Tavsiye

depolama hesabı adını ve erişim anahtarlarından birini Azure portalından almak için depolama hesabınızı arayın. Kaynak menüsünde Erişim anahtarları'nı seçin. Depolama hesabı adını kopyalayın ve key1 bölümünden Anahtarı kopyalayın. Önce anahtarın yanındaki Göster'i seçmeniz gerekir.

Azure Blob depolama başvurusunda bir kullanıcıya veya role erişim izni verme

Bu örnekte, PostgreSQL kullanıcısının başvurulan Azure depolama hesabı tarafından barındırılan kapsayıcılarda depolanan bloblara erişmek için uzantıyı kullanabilmesi <regular_user> için adlı azure_storagebir kullanıcıya veya role nasıl erişim verebileceğiniz gösterilmektedir.

Mevcut bir kullanıcı veya rolün adına ayarlayın <regular_user> .

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

Kapsayıcıdaki tüm blobları listeleme

Bu örnekte, depolama hesabının kapsayıcısı <container_name> içindeki tüm mevcut blobların nasıl liste adı ve yer aldığı gösterilmektedir <account_name>.

Blob kapsayıcınızın adına ayarlayın <container_name> . Önceki betikleri kullandıysanız, bu değer bu betiklerde ortam değişkeni için blob_container ayarladığınız değerle eşleşmelidir.

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

Belirli bir ad ön ekiyle blobları listeleme

Bu örnek, blob adı ile <container_name>başlayan depolama hesabı <account_name>kapsayıcısı <blob_name_prefix> içindeki tüm mevcut blobların nasıl liste yapılacağını gösterir.

Blobların adlarına eklenmesini istediğiniz önek olarak ayarlayın <blob_name_prefix> . Tüm blobları döndürmek istiyorsanız, bu parametreyi boş bir dize olarak ayarlayın veya bu parametre için bir değer belirtmeyin; bu durumda değer varsayılan olarak boş bir dizeye ayarlanır.

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

Alternatif olarak, aşağıdaki söz dizimini kullanabilirsiniz:

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

COPY FROM deyimini kullanarak verileri içeri aktarma

Aşağıdaki örnekte, Azure Depolama hesabındaki storage_extension_sample.parquetblob kapsayıcısında <container_name> bulunan adlı <account_name> blobdan verileri içeri aktarma işlemi gösterilmektedir. İçeri aktarma şu COPY komutu kullanır:

Kaynak dosyanın şemasıyla eşleşen bir tablo oluşturun.

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

Verileri hedef tabloya kopyalamak için deyimini COPY kullanın. Biçim, dosyanın uzantısından Parquet olarak çıkarılır.

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

Verileri hedef tabloya kopyalamak için deyimini COPY kullanın. Kodlama biçimi dosya uzantısından çıkarılamadığından, seçeneğini kullanarak FORMAT açıkça belirtin.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Verileri hedef tabloya kopyalamak için deyimini COPY kullanın. Kodlama biçimi dosya uzantısından çıkarılabilir. Ancak, seçeneğini kullanarak HEADERS ilk satırda sütun üst bilgilerinin varlığını açıkça yapılandırmanız gerekir.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Verilerin tabloya yüklendiğini onaylamak için aşağıdaki SELECT deyimi yürütür.
```
SELECT *
FROM sample_data
LIMIT 100;
```

COPY TO deyimini kullanarak verileri dışarı aktarma

Aşağıdaki örneklerde, adlı sample_data bir tablodaki verilerin kodlama biçimleri gibi farklı adlara ve özelliklere sahip birden çok bloba nasıl dışarı aktarılması gösterilmektedir. Tüm bloblar Azure Depolama hesabındaki <account_name>blob kapsayıcısında <container_name> bulunur. COPY Verileri dışarı aktarmak için komutunu kullanın:

Kaynak dosyanın şemasıyla eşleşen bir tablo oluşturun.

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

Kaynak dosyanın şemasıyla eşleşen bir tablo oluşturun.

Hedef tablodan veri kopyalamak için deyimini COPY kullanın. Kodlama biçiminin parquet olması gerektiğini belirtin.

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

Hedef tablodan veri kopyalamak için deyimini COPY kullanın. Kodlama biçiminin CSV olması gerektiğini ve sonuçta elde edilen dosyanın ilk satırının sütun üst bilgileri içerdiğini belirtin.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Blob'un depolama hesabında mevcut olduğunu onaylamak için aşağıdaki SELECT deyimi yürütebilirsiniz.

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

Blobdan içerik okuma

işlevi, blob_get depolamanın başvuruda bulunan kapsayıcısında <container_name> belirli bir blobun <account_name> içeriğini alır. Verileri ayrıştırmaya yardımcı olmak blob_get için biçiminde NULL::table_namebir değer geçirin. Burada table_name , şeması okumakta olduğunuz blobla eşleşen bir tabloya başvurur. Örnekte, en başında oluşturduğunuz tabloya başvurur sample_data .

İçeriğini okumak istediğiniz blobun tam yoluna ayarlayın <blob_name> .

Bu durumda, blobu ayrıştıran kod çözücü dosya uzantısından .parquet çıkarılır.

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

Alternatif olarak, blob_get işlevinden sonraki yan tümcesini AS kullanarak sonucun şemasını açıkça tanımlayabilirsiniz.

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;

Blobdan okunan içeriği okuma, filtreleme ve değiştirme

Bu örnekte, bir SQL tablosuna yüklemeden önce blobdan içeri aktarılan içeriği nasıl filtreleyebileceğiniz ve değiştirebileceğiniz gösterilmektedir.

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;

Özel seçeneklerle dosyadan içerik okuma (üst bilgiler, sütun sınırlayıcıları, kaçış karakterleri)

Bu örnek, bağımsız değişkene options_copy sonucunu geçirerek özel ayırıcıların ve kaçış karakterlerinin options nasıl kullanılacağını gösterir.

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

Kod çözücü seçeneğini kullanma

Bu örnekte seçeneğin nasıl kullanılacağı gösterilmektedir decoder . Kod çözücü seçeneğini eklemediğinizde sistem bunu dosyanın uzantısından çıkartır. Dosya adında bir uzantı yoksa veya dosya adı uzantısı, sistemin dosyanın içeriğini düzgün ayrıştırması için gereken kod çözücüye karşılık gelmiyorsa, kod çözücü bağımsız değişkenini açıkça geçirebilirsiniz.

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

Blobun içeriği üzerinde işlem toplamaları

Bu örnekte, blobun içeriğini PostgreSQL tablolarına aktarmaya gerek kalmadan bir blob kapsayıcısında depolanan bilgiler üzerinde toplama işlemlerinin nasıl gerçekleştirildiğini gösterir.

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;

Bloba içerik yazma

İşlev, blob_put belirli bir blobun (sample_data_copy.parquet bu örnekte) içeriğini oluşturur ve depolamanın başvuruda bulunan kapsayıcısına <container_name><account_name> yükler. Bu örnek, beş satırdan oluşan bir küme oluşturmak için kullanırblob_get. Bu küme daha sonra bunları adlı sample_data_copy.parquetbir blob olarak karşıya yükleyen toplama işlevine blob_put geçirilir.

Kodlama biçimi, dosya uzantısına .parquetgöre Parquet olarak çıkarılır.

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;

Kodlama biçimi, dosya uzantısına .csvgöre CSV olarak çıkarılır.

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;

Dosyada bir dosya uzantısı olmadığından kodlama biçimi çıkarılamıyor, bu nedenle açıkça olarak parquetyapılandırılır. Ayrıca, sıkıştırma algoritması olarak zstdayarlanır.

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;

Azure depolama hesaplarına yapılan tüm başvuruları listeleme

Bu örnekte, uzantının bu veritabanında hangi Azure depolama hesaplarına azure_storage başvurabileceğini ve her depolama hesabına erişmek için kullanılan kimlik doğrulama türünü nasıl bulabileceğiniz gösterilmektedir. Ayrıca azure_storage.account_user_add işlevi aracılığıyla uzantı tarafından sağlanan işlevler aracılığıyla bu Azure depolama hesabına erişmek için hangi kullanıcılara veya rollere izin verildiğini gösterir.

SELECT * FROM azure_storage.account_list();

Azure Blob depolama başvurusunda kullanıcı veya rolden erişimi iptal etme

Bu örnekte, PostgreSQL kullanıcısının başvurulan Azure depolama hesabı tarafından barındırılan kapsayıcılarda depolanan bloblara erişmek için uzantıyı kullanamamaları azure_storage için adlı <regular_user>bir kullanıcı veya rolden erişimin nasıl iptal edildiği gösterilmektedir.