カテゴリ:

ファイル関数

BUILD_STAGE_FILE_URL

ステージ名と相対ファイルパスを入力として使用して、Snowflake ファイル URL をステージングされたファイルに生成します。ファイル URL は、指定されたファイルへの長期アクセスを許可します。つまり、ファイル URL は期限切れになりません。

この SQL 関数をクエリ、ユーザー定義関数(UDF)、またはストアドプロシージャで呼び出します。

ファイルサポートのリクエストでファイル URL を REST API に送信することにより、ステージ内のファイルにアクセスします。ユーザーがファイル URL を REST API に送信してファイルにアクセスすると、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.com)で終わります。

account_locator.snowflakecomputing.com

詳細については、 アカウント識別子 をご参照ください。

注釈

Business Critical アカウントの場合は、アカウントでSnowflakeサービスへのプライベート接続が有効になっていなくても、 snowflakecomputing.comprivatelink.snowflakecomputing.com)の直前の URL に privatelink セグメントが追加されます。

重要

現在、この関数はアカウント識別子を organization_name-account_name の形式で返します。ファイル URL が GET リクエストへの入力として使用されると、 API エンドポイントはエラーを返します。

エラーを解決するには、使用するアカウントの該当するフォームにアカウント識別子を手動で変換する必要があります。

account_locator.region_id または

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 権限のみが必要です。

  • ファイル URL を REST API に送信する 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