Azure 扩展

azure 扩展是一个可加载扩展，为 Goose 增加了 Azure Blob Storage 的文件系统抽象，支持读写数据。

安装与加载

azure 扩展在首次使用时会从官方扩展仓库自动按需加载。若需手动安装并加载，请执行：

INSTALL azure;
LOAD azure;

用法

完成认证配置后，可以按如下方式查询 Azure 存储：

Azure Blob Storage

支持的 URI scheme：az 或 azure

SELECT count(*)
FROM 'az://⟨my_container⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

也支持 glob：

SELECT *
FROM 'az://⟨my_container⟩/⟨path⟩/*.csv';

SELECT *
FROM 'az://⟨my_container⟩/⟨path⟩/**';

或使用完整限定路径语法：

SELECT count(*)
FROM 'az://⟨my_storage_account⟩.blob.core.windows.net/⟨my_container⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

SELECT *
FROM 'az://⟨my_storage_account⟩.blob.core.windows.net/⟨my_container⟩/⟨path⟩/*.csv';

写入 Azure Blob Storage

你可以使用 COPY 语句将数据直接写入 Azure Blob 或 ADLSv2 Storage。

-- Write query results to a Parquet file on Blob Storage
COPY (SELECT * FROM my_table)
TO 'az://⟨my_container⟩/⟨path⟩/output.parquet';

-- Write a table to a CSV file on ADLSv2 Storage
COPY my_table
TO 'abfss://⟨my_container⟩/⟨path⟩/output.csv';

也可以使用完整限定路径：

COPY my_table
TO 'az://⟨my_storage_account⟩.blob.core.windows.net/⟨my_container⟩/⟨path⟩/output.parquet';

配置

使用以下配置项控制扩展读取远程文件的行为：

名称	说明	类型	默认值
`azure_http_stats`	Include HTTP info from Azure Storage in the `EXPLAIN ANALYZE` statement.	`BOOLEAN`	`false`
`azure_read_transfer_concurrency`	Maximum number of threads the Azure client can use for a single parallel read. If `azure_read_transfer_chunk_size` is less than `azure_read_buffer_size` then setting this > 1 will allow the Azure client to do concurrent requests to fill the buffer.	`BIGINT`	`5`
`azure_read_transfer_chunk_size`	Maximum size in bytes that the Azure client will read in a single request. It is recommended that this is a factor of `azure_read_buffer_size`.	`BIGINT`	`1024*1024`
`azure_read_buffer_size`	Size of the read buffer. It is recommended that this is evenly divisible by `azure_read_transfer_chunk_size`.	`UBIGINT`	`1024*1024`
`azure_transport_option_type`	Underlying adapter to use in the Azure SDK. Valid values are: `default` or `curl`.	`VARCHAR`	`default`
`azure_context_caching`	Enable/disable the caching of the underlying Azure SDK HTTP connection in the Goose connection context when performing queries. If you suspect that this is causing some side effect, you can try to disable it by setting it to false (not recommended).	`BOOLEAN`	`true`

显式将 azure_transport_option_type 设为 curl 会产生以下影响：

在 Linux 上，这可能解决证书问题（Error: Invalid Error: Fail to get a new connection for: https://storage_account_name.blob.core.windows.net/. Problem with the SSL CA cert (path? access rights?)），因为指定后扩展会在多个路径查找 bundle 证书（默认 curl 不会这样做，且静态链接时可能路径不正确）。

在 Windows 上，这会替换默认 adapter（WinHTTP），从而可使用 curl 的全部能力（例如 socks 代理）。

在所有操作系统上，它会读取以下环境变量：

CURL_CA_INFO: Path to a PEM encoded file containing the certificate authorities sent to libcurl. Note that this option is known to only work on Linux and might throw if set on other platforms.

CURL_CA_PATH: Path to a directory which holds PEM encoded files, containing the certificate authorities sent to libcurl.

示例：

SET azure_http_stats = false;
SET azure_read_transfer_concurrency = 5;
SET azure_read_transfer_chunk_size = 1_048_576;
SET azure_read_buffer_size = 1_048_576;

认证

Azure 扩展有两种认证配置方式，推荐方式是使用 Secrets。

使用 Secret 进行认证

Azure 扩展支持多个 Secret Providers：

如果需要为不同 storage account 定义不同 secret，请使用 SCOPE 配置。注意 SCOPE 需要尾部斜杠（SCOPE 'azure://some_container/'）。
若使用完整限定路径，则 ACCOUNT_NAME 属性可选。

`CONFIG` Provider

默认 provider 为 CONFIG（即用户配置），可通过 connection string 或匿名方式访问 storage account。例如：

CREATE SECRET secret1 (
    TYPE azure,
    CONNECTION_STRING '⟨value⟩'
);

如果不使用认证，仍需指定 storage account 名称。例如：

CREATE SECRET secret2 (
    TYPE azure,
    PROVIDER config,
    ACCOUNT_NAME '⟨storage_account_name⟩'
);

默认 PROVIDER 为 CONFIG。

`credential_chain` Provider

credential_chain provider 允许通过 Azure SDK 的 credential chain 自动获取凭据后连接。默认使用 DefaultAzureCredential chain，按 Azure 文档规定顺序尝试凭据。例如：

CREATE SECRET secret3 (
    TYPE azure,
    PROVIDER credential_chain,
    ACCOUNT_NAME '⟨storage_account_name⟩'
);

Goose 也支持通过 CHAIN 指定具体链路。该值为分号分隔 provider 列表（a;b;c），会按顺序尝试。例如：

CREATE SECRET secret4 (
    TYPE azure,
    PROVIDER credential_chain,
    CHAIN 'cli;env',
    ACCOUNT_NAME '⟨storage_account_name⟩'
);

可选值如下： cli; managed_identity; workload_identity; env; default;

若未显式提供 CHAIN，默认值为 default。

Managed Identity

Managed Identity（MI）可通过 credential_chain 平滑、自动地使用。在执行环境仅有一个 MI 的典型场景下，无需额外配置。

如果执行环境有多个 Identity，请使用 MANAGED_IDENTITY provider 并显式指定使用哪一个。该 provider 支持通过 CLIENT_ID、OBJECT_ID 或 RESOURCE_ID 指定身份，例如：

CREATE SECRET secret1 (
    TYPE AZURE,
    PROVIDER MANAGED_IDENTITY,
    ACCOUNT_NAME '⟨storage account name⟩',
    CLIENT_ID '⟨used-assigned managed identity client id⟩'
);

该 provider 也可不指定 ID；若仅有一个可用 ID，其行为与 credential_chain provider 相同，会使用该唯一 ID。若存在多个 ID，行为不确定（更准确地说由 Azure SDK 决定）；因此此场景建议显式设置 Identity。

`SERVICE_PRINCIPAL` Provider

SERVICE_PRINCIPAL provider 支持使用 Azure Service Principal (SPN) 连接。

可通过 secret：

CREATE SECRET azure_spn (
    TYPE azure,
    PROVIDER service_principal,
    TENANT_ID '⟨tenant_id⟩',
    CLIENT_ID '⟨client_id⟩',
    CLIENT_SECRET '⟨client_secret⟩',
    ACCOUNT_NAME '⟨storage_account_name⟩'
);

或通过证书：

CREATE SECRET azure_spn_cert (
    TYPE azure,
    PROVIDER service_principal,
    TENANT_ID '⟨tenant_id⟩',
    CLIENT_ID '⟨client_id⟩',
    CLIENT_CERTIFICATE_PATH '⟨client_cert_path⟩',
    ACCOUNT_NAME '⟨storage_account_name⟩'
);

配置代理

使用 secrets 时，如需配置代理，可在 secret 定义中加入 HTTP_PROXY、PROXY_USER_NAME 与 PROXY_PASSWORD。例如：

CREATE SECRET secret5 (
    TYPE azure,
    CONNECTION_STRING '⟨value⟩',
    HTTP_PROXY 'http://localhost:3128',
    PROXY_USER_NAME 'john',
    PROXY_PASSWORD 'doe'
);

使用 secrets 时，除非显式设置值，否则仍会遵循 HTTP_PROXY 环境变量。

使用 secrets 时，Authentication with variables 一节中的 SET 变量会被忽略。

对 Azure credential_chain provider 而言，实际 token 在查询时获取，而不是在创建 secret 时获取。

使用变量认证（已弃用）

SET variable_name = variable_value;

其中 variable_name 可为下列之一：

名称	说明	类型	默认值
`azure_storage_connection_string`	Azure connection string, used for authenticating and configuring Azure requests.	`STRING`	-
`azure_account_name`	Azure account name, when set, the extension will attempt to automatically detect credentials (not used if you pass the connection string).	`STRING`	-
`azure_endpoint`	Override the Azure endpoint for when the Azure credential providers are used.	`STRING`	`blob.core.windows.net`
`azure_credential_chain`	Ordered list of Azure credential providers, in string format separated by `;`. For example: `'cli;managed_identity;env'`. See the list of possible values in the `credential_chain` provider section. Not used if you pass the connection string.	`STRING`	-
`azure_http_proxy`	Proxy to use when login & performing request to Azure.	`STRING`	`HTTP_PROXY` environment variable (if set).
`azure_proxy_user_name`	HTTP proxy username if needed.	`STRING`	-
`azure_proxy_password`	HTTP proxy password if needed.	`STRING`	-

其他信息

日志

Azure 扩展依赖 Azure SDK 连接 Azure Blob storage，并支持将 SDK 日志输出到控制台。要控制日志级别，请设置 AZURE_LOG_LEVEL 环境变量。

例如，在 Python 中可按如下方式启用 verbose 日志：

import os
import goose

os.environ["AZURE_LOG_LEVEL"] = "verbose"

goose.sql("CREATE SECRET myaccount (TYPE azure, PROVIDER credential_chain, SCOPE 'az://myaccount.blob.core.windows.net/')")
goose.sql("SELECT count(*) FROM 'az://myaccount.blob.core.windows.net/path/to/blob.parquet'")

安装与加载​

用法​

Azure Blob Storage​

写入 Azure Blob Storage​

配置​

认证​

使用 Secret 进行认证​

CONFIG Provider​

credential_chain Provider​

Managed Identity​

SERVICE_PRINCIPAL Provider​

配置代理​

使用变量认证（已弃用）​

其他信息​

日志​