Azure Database for PostgreSQL の Azure Storage 拡張機能のクイックスタート例

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

BLOB コンテナーを作成します。 BLOB コンテナーを作成するには、次の Azure CLI を実行します。
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
ストレージアカウントに割り当てられている 2 つのアクセスキーのいずれかをフェッチします。後の手順で azure_storage.account_add の引数として渡す必要があるため、必ずaccess_keyの値をコピーしてください。 2 つのアクセスキーの 1 つ目をフェッチするには、次の 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 Storage アカウントに対して、この特権が付与されます。既定では、 azure_pg_admin のメンバーにのみ azure_storage_admin ロールが付与されます。

データが読み込まれるテーブルを作成する

ストレージアカウントにアップロードしたファイルの内容をインポートするテーブルを作成しましょう。これを行うには、 PostgreSQL for Visual Studio Code (プレビュー)、 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
);

拡張機能を使用できるように準備する

続行する前に、次の点を確認してください。

ストレージアカウントのアクセスキーを追加する

この例では、ストレージアカウントへの参照と、そのストレージアカウントのアクセスキーを追加する方法を示します。このキーは、Azure Database for PostgreSQL フレキシブルサーバーのインスタンスで azure_storage 拡張機能によって提供される機能を介してそのコンテンツにアクセスするために必要です。

<account_name> は、ストレージアカウントの名前に設定する必要があります。前のスクリプトを使用した場合、この値は、これらのスクリプトでstorage_account環境変数に設定した値と一致する必要があります。

同様に、 <access_key> は、ストレージアカウントからフェッチした値に設定する必要があります。

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

ヒント

Azure portal からストレージアカウント名とそのアクセスキーの 1 つを取得する場合は、ストレージアカウントを検索し、リソースメニューで [アクセスキー] を選択し、ストレージアカウント名をコピーして key1 セクションからキーをコピーします (最初にキーの横にある [表示] を選択する必要があります)。

Azure Blob Storage リファレンスでユーザーまたはロールへのアクセスを許可する

この例では、 <regular_user>という名前のユーザーまたはロールへのアクセスを許可する方法を示します。これにより、そのような PostgreSQL ユーザーは、 azure_storage 拡張機能を使用して、参照先の Azure ストレージアカウントによってホストされているコンテナーに格納されている BLOB にアクセスできます。

<regular_user> は、既存のユーザーまたはロールの名前に設定する必要があります。

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

コンテナー内のすべての BLOB を一覧表示する

この例では、ストレージアカウント <container_name>のコンテナー <account_name>内のすべての既存の BLOB を一覧表示する方法を示します。

<container_name> は、BLOB コンテナーの名前に設定する必要があります。前のスクリプトを使用した場合、この値は、これらのスクリプトでblob_container環境変数に設定した値と一致する必要があります。

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

特定の名前プレフィックスを持つ BLOB を一覧表示する

この例では、<container_name>で始まるストレージアカウント <account_name>のコンテナー <blob_name_prefix>内のすべての既存の BLOB を一覧表示する方法を示します。

<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 コマンドを使用して、Azure Storage アカウント <container_name>の BLOB コンテナー <account_name>に存在する 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 ステートメントを使用してデータをエクスポートする

次の例は、COPY コマンドを使用して、sample_dataと呼ばれるテーブルから、異なる名前を持つ複数の BLOB にデータをエクスポートし、エンコード形式などの特性を示しています。これらはすべて、azure Storage アカウント <account_name>の BLOB コンテナー <container_name>に存在します。

ソースファイルのスキーマに一致するテーブルを作成します。

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関数は、<account_name> ストレージの参照コンテナー <container_name>内の 1 つの特定の BLOB の内容を取得します。 blob_getがデータを解析する方法を知るために、NULL::table_name形式で値を渡すことができます。ここで、table_nameは、読み取られる BLOB のスキーマと一致するテーブルを参照します。この例では、最初に作成した sample_data テーブルを参照しています。

<blob_name> は、読み取る内容を持つ BLOB の完全なパスに設定する必要があります。

この場合、BLOB の解析に使用する必要があるデコーダーは、 .parquet ファイル拡張子から推論されます。

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

または、blob_get関数の後に 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 からインポートされたコンテンツをフィルター処理して変更する可能性を示します。

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;

BLOB のコンテンツに対するコンピューティング集計

この例では、BLOB コンテナーに格納されている情報に対して集計操作を実行する方法を示します。BLOB の内容を 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 にコンテンツを書き込む

blob_put関数は、1 つの特定の BLOB (この場合sample_data_copy.parquet) の内容を構成し、<container_name> ストレージの参照されるコンテナー <account_name>にアップロードします。この例では、 blob_get を使用して 5 行のセットを作成し、 blob_put 集計関数に渡し、 sample_data_copy.parquetという名前の BLOB としてアップロードします。

エンコード形式は、ファイル拡張子 .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 Storage リファレンスのユーザーまたはロールからのアクセスを取り消す

この例では、 <regular_user>という名前のユーザーまたはロールからのアクセスを取り消して、そのような PostgreSQL ユーザーが azure_storage 拡張機能を使用して、参照先の Azure ストレージアカウントによってホストされているコンテナーに格納されている BLOB にアクセスできないようにする方法を示します。

<regular_user> は、既存のユーザーまたはロールの名前に設定する必要があります。

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

ストレージアカウントへの参照を削除する

この例では、ストレージアカウントへの参照を削除して、現在のデータベースのユーザーが azure_storage 拡張機能機能を使用してそのストレージアカウントにアクセスできないようにする方法を示します。

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-19