类别：

文件函数

BUILD_STAGE_FILE_URL

使用暂存区名称和相对文件路径作为输入，生成指向暂存文件的 Snowflake 文件 URL。文件 URL 允许长时间访问指定文件。也就是说，文件 URL 不会过期。

在查询、用户定义函数 (UDF) 或存储过程中调用此 SQL 函数。

通过向支持文件的 REST API 请求发送文件 URL 来访问暂存区中的文件。当用户向 REST API 发送文件 URL 以访问文件时，Snowflake 会执行以下操作：

  1. 对用户进行身份验证。

  2. 验证角色在包含该文件的暂存区上是否具有足够的权限。

  3. 将用户重定向到云存储服务中的暂存文件。

语法

BUILD_STAGE_FILE_URL( @<stage_name> , '<relative_file_path>' )
Copy

实参

stage_name

用于存储文件的内部或外部暂存区的名称。

备注

如果暂存区名称包含空格或特殊字符，则必须将其放在单引号内（例如，对于名为 "my stage" 的暂存区，格式为 '@"my stage"'）。

relative_file_path

文件相对于其在暂存区中的位置的路径和文件名。

返回

该函数返回一个采用以下格式的文件 URL ：

https://<account_identifier>/api/files/<db_name>/<schema_name>/<stage_name>/<relative_path>
Copy

其中：

account_identifier

暂存区的 Snowflake 账户主机名。主机名以账户定位器（由 Snowflake 提供）开头，以 Snowflake 域 (snowflakecomputing.cn) 结尾：

account_locator.snowflakecomputing.cn

有关更多详细信息，请参阅 账户标识符。

备注

对于 业务关键 账户，即使您的账户未启用与 Snowflake 服务的专用连接，也会在 URL 中的 snowflakecomputing.cn (privatelink.snowflakecomputing.cn) 之前附加 privatelink 段。

重要

目前，该函数以 organization_name-account_name 的形式返回账户标识符。当文件 URL 用作 GET 请求的输入时，API 端点会返回错误。

要解决该错误，您必须手动将账户标识符转换为适合您账户的形式：

account_locator.region_id :emph:` 或 `

account_locator.region_id.cloud

有关这些形式的更多信息，请参阅 格式 2：区域中的账户定位器。

在即将发布的版本中，该函数将以正确的形式返回文件 URLs。

db_name

包含文件所在暂存区的数据库名称。

schema_name

包含文件所在暂存区的架构名称。

stage_name

文件所在暂存区的名称。

relative_path

要使用文件 URL 访问的文件的路径。

使用说明

  • 调用此 SQL 函数所需的权限因调用方式而异：

    SQL 操作

    所需权限

    查询

    USAGE （外部暂存区）或 READ （内部暂存区）

    存储过程

    存储过程所有者（即对存储过程具有 OWNERSHIP 权限的角色）必须具有暂存区权限：USAGE （外部暂存区）或 READ （内部暂存区）。

    查询存储过程的角色只需要存储过程的 USAGE 权限。

    UDF

    UDF 所有者（即拥有 UDF 的 OWNERSHIP 权限的角色）必须拥有暂存区权限：USAGE （外部暂存区）或 READ （内部暂存区）。

    查询 UDF 的角色只需要 UDF 的 USAGE 权限。

  • 向 REST API 发送文件 URL 的 HTTP 客户端必须配置为允许重定向。

  • 当一个文件 URL 被访问后，查询历史显示内部 GET_STAGE_FILE 函数被调用。

  • 如果从内部暂存区下载的文件已损坏，请与暂存区创建者核实是否为该暂存区设置了 ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')。

示例

检索外部暂存区中的位图格式图像文件的文件 URL：

SELECT BUILD_STAGE_FILE_URL(@images_stage,'/us/yosemite/half_dome.jpg');
Copy
https://my_account.snowflakecomputing.com/api/files/MY_DB/PUBLIC/IMAGES_STAGE/us/yosemite/half_dome.jpg
Copy
语言: 中文