pg_azure_storage 延伸模組

發行項
08/15/2024

適用於： Azure Cosmos DB for PostgreSQL (由 PostgreSQL 的超大規模 (Citus) 資料庫延伸模組提供)

pg_azure_storage延伸模組可讓您將多個檔格式的數據直接從 Azure Blob 記憶體載入至適用於 PostgreSQL 的 Azure Cosmos DB 叢集。啟用擴充功能也會解除鎖定 COPY 命令的新功能。具有存取層級「私人」或「Blob」的容器需要新增私鑰。

您可以執行下列命令來建立擴充功能：

SELECT create_extension('azure_storage');

azure_storage.account_add

函式允許新增對記憶體帳戶的存取權。

azure_storage.account_add
        (account_name_p text
        ,account_key_p text);

引數

account_name_p

Azure Blob 記憶體（ABS）帳戶包含您所有的 ABS 物件：Blob、檔案、佇列和數據表。記憶體帳戶會為您的 ABS 提供唯一的命名空間，可從世界各地透過 HTTPS 存取。

account_key_p

您的 Azure Blob 記憶體（ABS）存取金鑰類似於記憶體帳戶的根密碼。請務必小心保護您的存取金鑰。使用 Azure Key Vault，以安全的方式管理及輪替金鑰。帳戶金鑰會儲存在 postgres 超級使用者存取的數據表中，azure_storage_admin以及授與這些系統管理員許可權的所有角色。若要查看哪些記憶體帳戶存在，請使用函式account_list。

azure_storage.account_remove

函式允許撤銷記憶體帳戶的帳戶存取權。

azure_storage.account_remove
        (account_name_p text);

引數

account_name_p

azure_storage.account_user_add

函式允許將角色的存取權新增至記憶體帳戶。

azure_storage.account_user_add
        ( account_name_p text
        , user_p regrole);

引數

account_name_p

user_p

使用者所建立的角色會顯示在叢集上。

注意

account_user_add、account_add、account_remove、account_user_remove 函式需要設定叢集中每個個別節點的許可權。

azure_storage.account_user_remove

函式允許移除記憶體帳戶角色的存取權。

azure_storage.account_user_remove
        (account_name_p text
        ,user_p regrole);

引數

account_name_p

user_p

使用者所建立的角色會顯示在叢集上。

azure_storage.account_list

函式會列出可存取 Azure Blob 記憶體的帳戶和角色。

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

引數

account_name

allowed_users

列出可存取 Azure Blob 記憶體的使用者。

傳回類型

TABLE

azure_storage.blob_list

函式會列出使用者容器內可用的 Blob 檔案及其屬性。

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;

引數

account_name

提供 storage account name 您 Azure 記憶體資料的唯一命名空間，可從世界各地透過 HTTPS 存取。

container_name

容器會組織一組 Blob，類似於檔案系統中的目錄。儲存體帳戶可以包含無限數量的容器，而一個容器則可儲存無限數量的 Blob。容器名稱必須是有效的 DNS 名稱，因為它會形成用來定址容器或其 blob 的唯一 URI 的一部分。命名容器時，請遵循下列規則：

容器名稱長度可介於 3 到 63 個字元之間。
容器名稱必須以字母或數字開頭，而且只能包含小寫字母、數字和虛線 (-) 字元。
容器名稱中不允許兩個或多個連續虛線字元。

容器的 URI 類似於： https://myaccount.blob.core.windows.net/mycontainer

prefix

從具有相符字串縮寫的 Blob 容器傳回檔案。

path

Azure Blob 目錄的完整路徑。

bytes

以位元組為單位的檔案物件大小。

last_modified

上次修改檔案內容的時間。

etag

ETag 屬性用於更新期間的開放式並行存取。它不是時間戳，因為有另一個稱為 Timestamp 的屬性會儲存上次更新記錄的時間。例如，如果您載入實體並想要更新它，ETag 必須符合目前儲存的內容。設定適當的 ETag 很重要，因為如果您有多個使用者編輯相同的專案，則不希望他們覆寫彼此的變更。

content_type

Blob 物件代表 Blob，這是不可變原始數據的類似檔案的物件。它們可以讀取為文字或二進位數據，或轉換成 ReadableStream，以便將其方法用於處理數據。 Blob 可以代表不一定是 JavaScript 原生格式的數據。

content_encoding

Azure 儲存體可讓您在 Blob 上定義 Content-Encoding 屬性。針對壓縮的內容，您可以將屬性設定為 GZIP。當瀏覽器存取內容時，它會自動解壓縮內容。

content_hash

此哈希是用來驗證傳輸期間 Blob 的完整性。指定此標頭時，記憶體服務會檢查已隨已傳送的哈希一起抵達。如果兩個哈希不相符，作業會失敗，錯誤碼為 400 （不正確的要求）。

傳回類型

SETOF 記錄

注意

許可權 現在，您可以將容器設定為該記憶體的 [私人] 和 [Blob 存取層級]，但只能作為 citus user，而該容器已 azure_storage_admin 授與該記憶體的角色。如果您建立名為 support 的新使用者，則預設不允許存取容器內容。

azure_storage.blob_get

函式允許在匯入之前，從容器內載入檔案 \ 檔案的內容，並新增了篩選或操作數據的支援。

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;

函式的多載版本包含 rec 參數，可讓您方便定義輸出格式記錄。

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;

引數

account

儲存體帳戶會為您的 Azure 儲存體數據提供唯一的命名空間，可從世界各地透過 HTTPS 存取。

容器

容器會組織一組 Blob，類似於檔案系統中的目錄。儲存體帳戶可以包含無限數量的容器，而一個容器則可儲存無限數量的 Blob。容器名稱必須是有效的 DNS 名稱，因為它會形成用來定址容器或其 blob 的唯一 URI 的一部分。

path

容器中現有的 Blob 名稱。

娛樂

定義記錄輸出結構。

解碼器

指定 Blob 格式譯碼器可以設定為 auto （預設值）或任何下列任何值

譯碼器描述

格式	說明
csv	PostgreSQL COPY 使用的逗號分隔值格式
tsv	定位字元分隔值，預設的 PostgreSQL COPY 格式
binary	二進位 PostgreSQL COPY 格式
text	包含單一文字值的檔案 (例如，大型 JSON 或 XML)

壓縮

定義壓縮格式。可用的選項為 auto、 gzip 與 none。選項 auto 的使用（預設值），會根據擴展名猜測壓縮（.gz == gzip）。選項 none 會強制忽略延伸模組，而不會嘗試譯碼。當 gzip 強制使用 gzip 譯碼器時（當您有具有非標準擴展名的 gzipped 檔案時）。我們目前不支援延伸模組的任何其他壓縮格式。

電子商務選項中

若要處理自定義標頭、自定義分隔符、逸出字元等， options 其運作方式 COPY 與 PostgreSQL 中的命令類似，參數會利用來blob_get函式。

傳回類型

SETOF 記錄 / anyelement

注意

blob_get內有四個公用程式函式，稱為參數，可協助為其建置值。每個公用程式函式都會指定用於符合其名稱的解碼器。

azure_storage.options_csv_get

函式會做為公用程式函式，稱為 blob_get 內的參數，這對於譯碼 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;

引數

delimiter

指定分隔檔案中每個資料列（行）內數據行的字元。預設值為文字格式的製表符，以 CSV 格式為逗號。它必須是單一位元組字元。

null_string

指定表示 Null 值的字串。預設值為文字格式的 \N （反斜杠-N），並以 CSV 格式加上未標記的空字串。即使您不想區分 Null 與空字串的情況，您仍可能偏好使用文字格式的空字串。

指定檔案包含標題列，其中包含檔案中每個數據行的名稱。在輸出中，第一行包含數據表中的數據行名稱。

引用

指定引用資料值時要使用的引號字元。預設值為雙引號。它必須是單一位元組字元。

escape

指定應該出現在符合 QUOTE 值之數據字元之前的字元。默認值與 QUOTE 值相同（因此，如果引號字元出現在數據中，則會加倍）。它必須是單一位元組字元。

force_not_null

請勿比對指定的數據行值與 Null 字串。在 Null 字串是空的預設值中，這表示空值會讀取為零長度字串，而不是 Null，即使未加上引號也一樣。

force_null

比對指定的數據行值與 Null 字串，即使它已加上引號，而且找到相符專案時，也會將值設定為 NULL。在 Null 字串是空的預設值中，它會將引號空字串轉換成 NULL。

content_encoding

指定檔案在encoding_name中編碼。如果省略選項，則會使用目前的用戶端編碼。

傳回類型

jsonb

azure_storage.options_copy

函式會作為稱為的公用程式函式，做為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;

引數

delimiter

指定分隔檔案中每個資料列（行）內數據行的字元。預設值為文字格式的製表符，以 CSV 格式為逗號。它必須是單一位元組字元。

null_string

標頭

指定檔案包含標題列，其中包含檔案中每個數據行的名稱。在輸出中，第一行包含數據表中的數據行名稱。

引用

指定引用資料值時要使用的引號字元。預設值為雙引號。它必須是單一位元組字元。

escape

force_quote

強制將引號用於每個指定數據行中的所有非 NULL 值。 NULL 輸出絕不會加上引號。如果指定 * ，則所有資料行都會加上非 NULL 值引號。

force_not_null

請勿比對指定的數據行值與 Null 字串。在 Null 字串是空的預設值中，這表示空值會讀取為零長度字串，而不是 Null，即使未加上引號也一樣。

force_null

content_encoding

指定檔案在encoding_name中編碼。如果省略選項，則會使用目前的用戶端編碼。

傳回類型

jsonb

azure_storage.options_tsv

函式會作為稱為的公用程式函式，做為blob_get內的參數。它適用於譯碼 tsv 內容。

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

引數

delimiter

指定分隔檔案中每個資料列（行）內數據行的字元。預設值為文字格式的製表符，以 CSV 格式為逗號。它必須是單一位元組字元。

null_string

content_encoding

指定檔案在encoding_name中編碼。如果省略選項，則會使用目前的用戶端編碼。

傳回類型

jsonb

azure_storage.options_binary

函式會作為稱為的公用程式函式，做為blob_get內的參數。它適用於譯碼二進位內容。

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

引數

content_encoding

指定檔案在encoding_name中編碼。如果省略此選項，則會使用目前的用戶端編碼。

傳回類型

jsonb

注意

許可權 現在，您可以將容器設定為該記憶體的 [私人] 和 [Blob 存取層級]，但只能作為 citus user，而該容器已 azure_storage_admin 授與該記憶體的角色。如果您建立名為 support 的新使用者，則預設不允許它存取容器內容。

範例

使用的範例會利用範例 Azure 記憶體帳戶 (pgquickstart) 與上傳的自定義檔案，以新增至不同使用案例的涵蓋範圍。我們可以從建立用於一組範例的數據表開始。

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

新增記憶體帳戶的存取金鑰（存取層級的必要 = 私用）

此範例說明如何新增記憶體帳戶的存取密鑰，以從適用於 Postgres 叢集的 Azure Cosmos DB 工作話取得查詢的存取權。

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

提示

在您的儲存體帳戶中，開啟 [存取金鑰]。複製儲存體帳戶名稱，並從 [key1] 區段中複製金鑰 (您必須先選取金鑰旁的 [顯示])。

Azure 入口網站中 Azure Blob 儲存體頁面的安全性 + 網路>存取金鑰區段螢幕快照。

拿掉記憶體帳戶的存取金鑰

此範例說明如何移除記憶體帳戶的存取金鑰。此動作會導致移除容器中私人貯體中裝載之檔案的存取權。

SELECT azure_storage.account_remove('pgquickstart');

將角色的存取權新增至 Azure Blob 記憶體

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

列出 Azure Blob 記憶體上具有存取權的擁有角色

SELECT * FROM azure_storage.account_list();

拿掉具有 Azure Blob 記憶體存取權的角色

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

列出容器內的 `public` 物件

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

列出容器內的 `private` 物件

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

注意

新增存取金鑰是必要的。

列出具有公用容器內特定字串縮寫的物件

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

或者

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

從容器中的物件讀取內容

函 blob_get 式會從 Blob 記憶體擷取檔案。為了讓blob_get知道如何剖析數據，您可以傳遞值（NULL：：table_name），其格式與檔案相同。

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

或者，我們可以明確地定義子句中的數據 FROM 行。

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;

使用譯碼器選項

此範例說明選項的使用 decoder 。通常格式是從檔案的擴展名推斷，但是當檔案內容沒有相符的擴展名時，您可以傳遞譯碼器自變數。

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

搭配譯碼器選項使用壓縮

此範例示範如何在沒有標準.gz擴展名的情況下，在 gzip 壓縮檔案上使用 gzip 壓縮。

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

從 csv 格式物件載入之前，先匯入篩選的內容和修改

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

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

使用標頭、自定義分隔符、逸出字元從檔案查詢內容

您可以將的結果 azure_storage.options_copy 傳遞至 options 自變數，以使用自定義分隔符和逸出字元。

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

容器中對象內容的匯總查詢

如此一來，您可以查詢數據而不匯入數據。

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;

下一步

如何搭配 COPY 命令使用 Azure Blob 儲存體

如何使用pg_azure_storage內嵌數據

共用方式為

pg_azure_storage 延伸模組

azure_storage.account_add

引數

account_name_p

account_key_p

azure_storage.account_remove

引數

account_name_p

azure_storage.account_user_add

引數

account_name_p

user_p

azure_storage.account_user_remove

引數

account_name_p

user_p

azure_storage.account_list

引數

account_name

allowed_users

傳回類型

azure_storage.blob_list

引數

account_name

container_name

prefix

path

bytes

last_modified

etag

content_type

content_encoding

content_hash

傳回類型

azure_storage.blob_get

引數

account

容器

path

娛樂

解碼器

譯碼器描述

壓縮

電子商務選項中

傳回類型

azure_storage.options_csv_get

引數

delimiter

null_string

標頭

引用

escape

force_not_null

force_null

content_encoding

傳回類型

azure_storage.options_copy

引數

delimiter

null_string

標頭

引用

escape

force_quote

force_not_null

force_null

content_encoding

傳回類型

azure_storage.options_tsv

引數

delimiter

null_string

content_encoding

傳回類型

azure_storage.options_binary

引數

content_encoding

傳回類型

範例

新增記憶體帳戶的存取金鑰（存取層級的必要 = 私用）

列出容器內的 `public` 物件

列出容器內的 `private` 物件