適用於 PostgreSQL 的 Azure 資料庫中 Azure 儲存體延伸模組的快速入門範例

以下是範例清單，可協助您瞭解如何使用 Azure 記憶體擴充功能。

建立 Azure 記憶體帳戶，並填入數據

建立 Azure 記憶體帳戶。若要建立 Azure 記憶體帳戶，如果您還沒有帳戶，請自定義、<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

建立 Blob 容器。若要建立 Blob 容器，請執行下列 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
```

使用範例期間使用的數據集下載檔案，並將它上傳至您的 Blob 容器。若要使用資料集下載檔案，請執行下列 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

備註

您可以列出儲存在特定儲存體帳戶中的容器或 Blob，但只有在 PostgreSQL 使用者或角色使用 azure_storage.account_user_add 授與該記憶體帳戶參考的許可權時。角色的成員 azure_storage_admin 會針對已使用 azure_storage.account_add 新增的所有 Azure 儲存器帳戶授與此許可權。根據預設，只有的成員 azure_pg_admin 會被授與 azure_storage_admin 角色。

建立載入數據的數據表

讓我們建立一個表格，將上傳到儲存帳號的檔案內容匯入。為此，請使用 PostgreSQL for Visual Studio Code （Preview）、psql、PgAdmin 或您偏好的用戶端，連接到您的 Azure Database for PostgreSQL 彈性伺服器實例，並執行以下語句：

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

準備擴充功能以供使用

繼續之前，請確定您：

新增記憶體帳戶的存取金鑰

此範例說明如何新增儲存體帳戶的參考，以及該儲存體帳戶的存取密鑰，這些密鑰是透過適用於 PostgreSQL 的 Azure 資料庫彈性伺服器實例中擴充功能所提供的 azure_storage 功能來存取其內容所需的密鑰。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

同樣地， <access_key> 必須設定為您從記憶體帳戶擷取的值。

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

小提示

如果您想要從 Azure 入口網站擷取記憶體帳戶名稱和其中一個存取密鑰，請在資源功能表中選取 [存取金鑰]，複製 [記憶體帳戶名稱]，然後從 key1 區段複製 [金鑰] 區段（您必須先選取 [顯示金鑰] 旁的 [顯示]。

在 Azure Blob 記憶體參考上授與使用者或角色的存取權

此範例說明如何授與名為 <regular_user>之使用者或角色的存取權，讓這類 PostgreSQL 使用者可以使用 azure_storage 擴充功能來存取所參考 Azure 儲存器帳戶所裝載之容器中儲存的 Blob。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<regular_user> 必須設定為現有使用者或角色的名稱。

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

列出容器中的所有 Blob

此範例說明如何在記憶體帳戶 <container_name>容器<account_name>內列出所有現有的 Blob。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

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

列出具有特定名稱前置詞的 Blob

此範例說明如何列出記憶體帳戶<container_name>容器<account_name>內的所有現有 Blob，其 Blob 名稱開頭為 <blob_name_prefix>。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

<blob_name_prefix> 應該設定為您想要列舉 Blob 在其名稱中包含的任何前置詞。如果您想要傳回所有 Blob，您可以將此參數設定為空字串，或甚至不指定此參數的值，在此情況下，值會預設為空字串。

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> Azure 記憶體帳戶<account_name>中 Blob 容器之 Blob 容器COPY的 Blob 匯入資料：

建立符合來源檔案架構的數據表：

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的表格匯出到多個名稱不同、特徵不同的 blob，例如它們的編碼格式，這些資料都存放在 Azure Storage 帳號<account_name>中的 blob 容器<container_name>中，透過以下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 語句以確認 Blob 存在於記憶體帳戶中。

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

從 Blob 讀取內容

該blob_get函式會擷取儲存中參考容器<container_name><account_name>中某個特定 blob 的內容。為了 blob_get 知道如何剖析數據，您可以在窗體 NULL::table_name中傳遞值，其中 table_name 是指架構符合所讀取 Blob 的數據表。在此範例中，它會參考我們在一開始建立的 sample_data 數據表。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

<blob_name> 應該設定為您想要讀取其內容之 Blob 的完整路徑。

在這種情況下，解析 blob 的解碼器是從 .parquet 檔案副檔名推斷出來的。

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

或者，您可以在 AS 函式之後，使用子句明確定義結果的架構。

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;

讀取、篩選和修改從 Blob 讀取的內容

此範例說明在載入 SQL 資料表之前，篩選和修改從 Blob 匯入的內容的可能性。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

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 自變數。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

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 。當沒有解碼器選項時，則是從檔案的副檔名推斷出來的。但當檔名沒有副檔名，或該副檔名不對應解碼器必須用來正確解析檔案內容的副檔名時，你可以明確傳遞解碼器參數。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

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

計算 Blob 內容的匯總

此範例說明如何針對儲存在 Blob 容器中的資訊執行匯總作業，而不需要將 Blob 的內容匯入 PostgreSQL 數據表。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

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

函blob_put式會撰寫一個特定 Blob 的內容（sample_data_copy.parquet在此案例中），並將它上傳至記憶體的<container_name>參考容器<account_name>。此範例會使用 blob_get 建構一組五個數據列，然後傳遞至 blob_put 聚合函數，以名為 sample_data_copy.parquet的 Blob 上傳它們。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<container_name> 必須設定為 Blob 容器的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 blob_container 環境變數的任何值。

編碼格式可根據檔案副檔名 .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 記憶體帳戶 azure_storage ，以及用來存取每個記憶體帳戶的驗證類型，以及哪些使用者或角色是透過 azure_storage.account_user_add 函式授與許可權，透過擴充功能存取該 Azure 儲存器帳戶。

SELECT * FROM azure_storage.account_list();

撤銷 Azure Blob 記憶體參考上使用者或角色的存取權

此範例說明如何撤銷名為 <regular_user>的使用者或角色的存取權，讓這類 PostgreSQL 用戶無法使用 azure_storage 擴充功能來存取存放在所參考 Azure 儲存體帳戶所裝載容器中的 Blob。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

<regular_user> 必須設定為現有使用者或角色的名稱。

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

拿掉記憶體帳戶的參考

此範例說明如何移除記憶體帳戶的任何參考，讓目前資料庫中沒有任何使用者可以使用 azure_storage 擴充功能來存取該儲存器帳戶。

<account_name> 必須設定為記憶體帳戶的名稱。如果您使用先前的腳本，此值應該符合您在這些腳本中設定為 storage_account 環境變數的任何值。

SELECT azure_storage.account_remove('<account_name>');

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19

共用方式為

適用於 PostgreSQL 的 Azure 資料庫中 Azure 儲存體延伸模組的快速入門範例

建立 Azure 記憶體帳戶，並填入數據

建立載入數據的數據表

準備擴充功能以供使用

新增記憶體帳戶的存取金鑰

在 Azure Blob 記憶體參考上授與使用者或角色的存取權

列出容器中的所有 Blob

列出具有特定名稱前置詞的 Blob

使用 COPY FROM 語句匯入數據

使用 COPY TO 語句匯出數據

從 Blob 讀取內容

讀取、篩選和修改從 Blob 讀取的內容

使用自訂選項從檔案讀取內容（標頭、資料列分隔符、逸出字元）

使用譯碼器選項

計算 Blob 內容的匯總

將內容寫入 Blob

列出 Azure 記憶體帳戶的所有參考

撤銷 Azure Blob 記憶體參考上使用者或角色的存取權

拿掉記憶體帳戶的參考

相關內容

意見反應

其他資源