أمثلة التشغيل السريع لملحق Azure Storage في قاعدة بيانات Azure ل PostgreSQL

فيما يلي قائمة من الأمثلة لمساعدتك على معرفة كيفية استخدام ملحق Azure Storage.

إنشاء حساب Azure Storage وملئه بالبيانات

إنشاء حساب Azure Storage. لإنشاء حساب Azure Storage، إذا لم يكن لديك حساب بالفعل، فقم بتخصيص قيم <resource_group>و <location><account_name>و <container_name>وتشغيل أمر 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

إنشاء حاوية كائن ثنائي كبير الحجم. لإنشاء حاوية كائن ثنائي كبير الحجم، قم بتشغيل Azure CLI التالي:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
إحضار أحد مفتاحي الوصول المعينين لحساب التخزين. تأكد من نسخ قيمة access_key حيث تحتاج إلى تمريرها كوسيطة إلى azure_storage.account_add في خطوة لاحقة. لجلب أول مفتاحي وصول، قم بتشغيل أمر 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
```

قم بتنزيل الملف مع مجموعة البيانات المستخدمة أثناء الأمثلة، وقم بتحميله إلى حاوية الكائن الثنائي كبير الحجم. لتنزيل الملف مع مجموعة البيانات، قم بتشغيل أمر 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

ملاحظة

يمكنك سرد الحاويات أو الكائنات الثنائية كبيرة الحجم المخزنة فيها لحساب تخزين معين، ولكن فقط إذا تم منح مستخدم PostgreSQL أو دوره إذنا على المرجع إلى حساب التخزين هذا باستخدام azure_storage.account_user_add. azure_storage_admin يتم منح أعضاء الدور هذا الامتياز على جميع حسابات Azure Storage التي تمت إضافتها باستخدام azure_storage.account_add. بشكل افتراضي، يتم منح azure_pg_admin أعضاء azure_storage_admin الدور فقط.

إنشاء جدول يتم فيه تحميل البيانات

دعونا ننشئ الجدول الذي نقوم باستيراد محتويات الملفات التي قمنا بتحميلها إلى حساب التخزين. للقيام بذلك، اتصل بمثيل Azure Database لخادم PostgreSQL المرن باستخدام PostgreSQL ل Visual Studio Code (معاينة) أو psql أو PgAdmin أو عميل تفضيلك، وقم بتنفيذ العبارة التالية:

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

إعداد الملحق للاستخدام

قبل المتابعة، تأكد من:

إضافة مفتاح الوصول لحساب التخزين

يوضح هذا المثال كيفية إضافة مرجع إلى حساب تخزين، جنبا إلى جنب مع مفتاح الوصول لحساب التخزين هذا المطلوب للوصول إلى محتواه عبر الوظيفة التي يوفرها azure_storage الملحق في مثيل قاعدة بيانات Azure لخادم PostgreSQL المرن.

<account_name> يجب تعيين إلى اسم حساب التخزين الخاص بك. إذا استخدمت البرامج النصية السابقة، يجب أن تتطابق هذه القيمة مع أي قيمة قمت بتعيينها إلى متغير البيئة storage_account في تلك البرامج النصية.

وبالمثل، <access_key> يجب تعيين إلى القيمة التي جلبتها من حساب التخزين الخاص بك.

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

تلميح

إذا كنت ترغب في استرداد اسم حساب التخزين وأحد مفاتيح الوصول الخاصة به من مدخل Microsoft Azure، فابحث عن حساب التخزين الخاص بك، في قائمة الموارد حدد مفاتيح الوصول، وانسخ اسم حساب التخزين وانسخ قسم Key from key1 (يجب عليك تحديد Show بجوار المفتاح أولا).

منح حق الوصول إلى مستخدم أو دور على مرجع تخزين Azure Blob

يوضح هذا المثال كيفية منح حق الوصول إلى مستخدم أو دور يسمى <regular_user>، بحيث يمكن لمستخدم PostgreSQL هذا استخدام azure_storage الملحق للوصول إلى الكائنات الثنائية كبيرة الحجم المخزنة في حاويات مستضافة بواسطة حساب تخزين Azure المشار إليه.

<regular_user> يجب تعيين إلى اسم مستخدم أو دور موجود.

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

سرد كافة الكائنات الثنائية كبيرة الحجم في حاوية

يوضح هذا المثال كيفية سرد جميع الكائنات الثنائية كبيرة الحجم الموجودة داخل حاوية <container_name> حساب <account_name>التخزين .

<container_name> يجب تعيين إلى اسم حاوية الكائن الثنائي كبير الحجم. إذا استخدمت البرامج النصية السابقة، يجب أن تتطابق هذه القيمة مع أي قيمة قمت بتعيينها إلى متغير البيئة blob_container في تلك البرامج النصية.

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

سرد الكائنات الثنائية كبيرة الحجم ببادئة اسم محددة

يوضح هذا المثال كيفية سرد جميع الكائنات الثنائية كبيرة الحجم الموجودة داخل حاوية <container_name> حساب <account_name>التخزين ، والتي يبدأ اسم الكائن الثنائي كبير الحجم الخاص بها ب <blob_name_prefix>.

<blob_name_prefix> يجب تعيين إلى أي بادئة تريد أن يتم تعداد الكائنات الثنائية كبيرة الحجم لتضمينها في أسمائها. إذا كنت تريد إرجاع كافة الكائنات الثنائية كبيرة الحجم، يمكنك تعيين هذه المعلمة إلى سلسلة فارغة أو حتى عدم تحديد قيمة لهذه المعلمة، وفي هذه الحالة يتم تعيين القيمة افتراضيا إلى سلسلة فارغة.

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

بدلا من ذلك، يمكنك استخدام بناء الجملة التالي:

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

استيراد البيانات باستخدام عبارة COPY FROM

يوضح المثال التالي استيراد البيانات من كائن ثنائي كبير الحجم يسمى storage_extension_sample.parquet الموجود في حاوية <container_name> الكائن الثنائي كبير الحجم في حساب <account_name>Azure Storage ، عبر COPY الأمر :

إنشاء جدول يطابق مخطط الملف المصدر:

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

استخدم عبارة COPY لنسخ البيانات إلى الجدول الهدف. يتم استنتاج التنسيق على أنه Parquet من ملحق الملف.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.parquet';
```
استخدم عبارة COPY لنسخ البيانات إلى الجدول الهدف. نظرا لأنه لا يمكن استنتاج تنسيق الترميز من ملحق الملف، يتم تحديده بشكل صريح عبر FORMAT الخيار .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
استخدم عبارة COPY لنسخ البيانات إلى الجدول الهدف. يمكن استنتاج تنسيق الترميز من ملحق الملف. ومع ذلك، يجب تكوين وجود رؤوس الأعمدة في الصف الأول بشكل صريح عبر HEADERS الخيار .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
نفذ العبارة التالية SELECT للتأكد من تحميل البيانات في الجدول.
```
SELECT *
FROM sample_data
LIMIT 100;
```

تصدير البيانات باستخدام عبارة COPY TO

توضح الأمثلة التالية تصدير البيانات من جدول يسمى sample_data، إلى كائنات ثنائية كبيرة الحجم متعددة بأسماء مختلفة، وخصائص مثل تنسيق الترميز الخاص بها، وكلها موجودة في حاوية <container_name> blob في حساب <account_name>Azure Storage ، عبر COPY الأمر :

إنشاء جدول يطابق مخطط الملف المصدر:

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

تحميل البيانات في الجدول. إما تشغيل عبارات INSERT لملئها بعدة صفوف اصطناعية، أو استخدام مثال استيراد البيانات باستخدام عبارة COPY FROM لملئها بمحتويات عينة مجموعة البيانات.

استخدم عبارة COPY لنسخ البيانات من الجدول الهدف. حدد أن تنسيق الترميز يجب أن يكون parquet.

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

استخدم عبارة COPY لنسخ البيانات من الجدول الهدف. حدد أن تنسيق الترميز يجب أن يكون CSV ويحتوي الصف الأول من الملف الناتج على رؤوس أعمدة.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```
نفذ العبارة التالية SELECT للتأكد من وجود الكائن الثنائي كبير الحجم في حساب التخزين.
```
SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE 'storage_extension_sample_exported%';
```

قراءة المحتوى من كائن ثنائي كبير الحجم

تسترد blob_get الدالة محتويات كائن ثنائي كبير الحجم محدد واحد، في الحاوية <container_name> المشار إليها للتخزين <account_name> . لمعرفة blob_get كيفية تحليل البيانات، يمكنك تمرير قيمة في النموذج NULL::table_name، حيث table_name يشير إلى جدول يتطابق مخططه مع مخطط الكائن الثنائي كبير الحجم الذي تتم قراءته. في المثال، يشير إلى الجدول الذي sample_data أنشأناه في البداية.

<blob_name> يجب تعيين إلى المسار الكامل للكائن الثنائي كبير الحجم الذي تريد قراءة محتوياته.

في هذه الحالة، يتم استنتاج أداة فك التشفير التي يجب استخدامها لتحليل الكائن الثنائي كبير الحجم من .parquet ملحق الملف.

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

بدلا من ذلك، يمكنك تعريف مخطط النتيجة بشكل صريح باستخدام AS عبارة بعد الدالة 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;

قراءة المحتوى المقروء من كائن ثنائي كبير الحجم وتصفيته وتعديله

يوضح هذا المثال إمكانية تصفية المحتوى المستورد من الكائن الثنائي كبير الحجم وتعديله، قبل تحميله في جدول 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;

قراءة المحتوى من ملف بخيارات مخصصة (رؤوس، محددات أعمدة، أحرف إلغاء)

يوضح هذا المثال كيفية استخدام الفواصل المخصصة وأحرف الإلغاء، عن طريق تمرير نتيجة options_copy إلى الوسيطة 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')
        );

استخدام خيار أداة فك التشفير

يوضح هذا المثال استخدام decoder الخيار . عندما يكون خيار فك التشفير غير موجود، يتم استنتاجه من ملحق الملف. ولكن عندما لا يحتوي اسم الملف على ملحق، أو عندما لا يتوافق ملحق اسم الملف هذا مع الملحق المقترن بأداة فك الترميز التي يجب استخدامها لتحليل محتويات الملف بشكل صحيح، يمكنك تمرير وسيطة أداة فك الترميز بشكل صريح.

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

حساب التجميعات على محتوى كائن ثنائي كبير الحجم

يوضح هذا المثال كيف يمكنك القيام بعمليات التجميع على المعلومات المخزنة في حاوية كائن ثنائي كبير الحجم، دون الحاجة إلى استيراد محتويات الكائن الثنائي كبير الحجم إلى جداول 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;

كتابة المحتوى إلى كائن ثنائي كبير الحجم

blob_put تقوم الدالة بإنشاء محتويات كائن ثنائي كبير الحجم محدد واحد (sample_data_copy.parquetفي هذه الحالة)، وتحميله إلى الحاوية <container_name> المشار إليها للتخزين<account_name>. يستخدم blob_get هذا المثال لإنشاء مجموعة من خمسة صفوف، والتي يتم تمريرها بعد ذلك إلى الدالة blob_put التجميعية التي تقوم بتحميلها ككائن ثنائي كبير الحجم يسمى sample_data_copy.parquet.

يتم استنتاج تنسيق الترميز ك parquet، استنادا إلى ملحق .parquetالملف .

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;

يتم استنتاج تنسيق الترميز ك CSV، استنادا إلى ملحق .csvالملف .

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;

لا يمكن استنتاج تنسيق الترميز لأن الملف لا يحتوي على ملحق ملف، لذلك تم تكوينه بشكل صريح ك parquet. أيضا، يتم تعيين خوارزمية الضغط إلى 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;

سرد جميع المراجع إلى حسابات تخزين Azure

يوضح هذا المثال كيفية معرفة حسابات azure_storage تخزين Azure التي يمكن للملحق الرجوع إليها في قاعدة البيانات هذه، بالإضافة إلى نوع المصادقة المستخدمة للوصول إلى كل حساب تخزين، والمستخدمين أو الأدوار التي يتم منحها الإذن، عبر وظيفة azure_storage.account_user_add ، للوصول إلى حساب تخزين Azure هذا من خلال الوظيفة التي يوفرها الملحق.

SELECT * FROM azure_storage.account_list();

إبطال الوصول من مستخدم أو دور على مرجع تخزين Azure Blob

يوضح هذا المثال كيفية إبطال الوصول من مستخدم أو دور يسمى <regular_user>، بحيث لا يمكن لمستخدم PostgreSQL هذا استخدام azure_storage الملحق للوصول إلى الكائنات الثنائية كبيرة الحجم المخزنة في حاويات مستضافة بواسطة حساب تخزين Azure المشار إليه.