- Categorias:
BUILD_SCOPED_FILE_URL¶
Gera um URL com escopo hospedado por Snowflake para um arquivo preparado usando o nome de estágio e o caminho relativo do arquivo como entradas. Uma URL com escopo é codificada e permite o acesso a um arquivo especificado por um período limitado de tempo.
Chame esta função SQL em uma consulta, exibição, função definida pelo usuário (UDF) ou procedimento armazenado. O URL com escopo na saída é válido apenas para o chamador até que o período de resultado da consulta persistente termine (ou seja, o cache de resultados expira): atualmente 24 horas.
Acessar os arquivos em um estágio usando um dos seguintes métodos:
Recupere um URL com escopo no Snowsight. Clique no URL com escopo na tabela de resultados.
Envie o URL com escopo em uma solicitação ao REST API para suporte de arquivo. Quando os usuários enviam um URL com escopo para o REST API para acessar arquivos, o Snowflake executa as seguintes ações:
Autenticar o usuário. Verifique se foi o usuário atual que chamou a função BUILD_SCOPED_FILE_URL e gerou o URL com escopo.
Verificar se o URL com escopo não está expirado.
Redirecione o usuário para o arquivo preparado no serviço de armazenamento em nuvem.
Sintaxe¶
BUILD_SCOPED_FILE_URL( @<stage_name> , '<relative_file_path>' )
Argumentos¶
stage_name
Nome do estágio interno ou externo em que o arquivo está armazenado.
Nota
Se o nome do estágio incluir espaços ou caracteres especiais, ele deve ser colocado entre aspas simples (por exemplo,
'@"my stage"'
para um estágio chamado"my stage"
).relative_file_path
Caminho e nome do arquivo em relação ao seu local no estágio.
Retornos¶
A função retorna um URL com escopo no seguinte formato:
https://<account_identifier>/api/files/<query_id>/<encoded_file_path>
Onde:
account_identifier
Nome do host da conta Snowflake para seu estágio. O nome do host começa com um localizador de conta (fornecido pelo Snowflake) e termina com o domínio Snowflake (
snowflakecomputing.com
):account_locator.snowflakecomputing.com
Para obter mais detalhes, consulte Identificadores de conta.
Nota
Para contas Business Critical, um segmento
privatelink
é anexado ao URL logo antes desnowflakecomputing.com
(privatelink.snowflakecomputing.com
), mesmo se a conectividade privada ao serviço Snowflake são estiver habilitado para sua conta.query_id
ID da consulta da chamada BUILD_SCOPED_FILE_URL que gerou o URL com escopo.
encoded_file_path
Caminho codificado para os arquivos a serem acessados usando o URL com escopo.
Notas de uso¶
As permissões exigidas para chamar esta função SQL diferem dependendo de como ela é chamada:
Operação SQL
Permissões exigidas
Consulta
USAGE (estágio externo) ou READ (estágio interno)
Definição da coluna em uma exibição
O proprietário da exibição (ou seja, a função com o privilégio OWNERSHIP na exibição) deve ter o privilégio de estágio: USAGE (estágio externo) ou READ (estágio interno).
Uma função que consulta a exibição exige apenas o privilégio SELECT nela.
Procedimento armazenado
O proprietário do procedimento armazenado (ou seja, a função com o privilégio OWNERSHIP no procedimento armazenado) deve ter o privilégio de estágio: USAGE (estágio externo) ou READ (estágio interno).
Uma função que consulta o procedimento armazenado exige apenas o privilégio USAGE no procedimento armazenado.
UDF
O proprietário do UDF (ou seja, a função com o privilégio OWNERSHIP no UDF) deve ter o privilégio de estágio: USAGE (estágio externo) ou READ (estágio interno).
Uma função que consulta o UDF exige apenas o privilégio USAGE no UDF.
Um cliente HTTP que envia um URL com escopo para o REST API deve ser configurado para permitir redirecionamentos.
Quando um URL com escopo é acessado, o histórico da consulta mostra que a função interna GET_SCOPED_FILE foi chamada.
Se os arquivos baixados de um estágio interno estiverem corrompidos, verifique com o criador do estágio se
ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')
está definido para o estágio.
Exemplos¶
Recuperar um URL com escopo para um arquivo de imagem em formato bitmap em um estágio externo:
SELECT BUILD_SCOPED_FILE_URL(@images_stage,'/us/yosemite/half_dome.jpg');
https://my_account.snowflakecomputing.com/api/files/019260c2-00c0-f2f2-0000-4383001cf046/bXlfZGF0YWJhc2UvbXlfc2NoZW1hL215X3N0YWdlL2ZvbGRlcjEvZm9sZGVyMi9maWxlMQ
Criar uma exibição segura que filtre os resultados de uma chamada de função BUILD_SCOPED_FILE_URL para um público específico. Neste exemplo, consultar a exibição segura retorna somente aqueles arquivos no caminho do arquivo de estágio que incluem a cadeia de caracteres acct1
:
-- Create a table that stores the relative file path for each staged file along with any other related data.
CREATE TABLE acct_table (
acct_name string,
relative_file_path string
);
-- Create a secure view on the table you created.
-- A role that has the SELECT privilege on the secure view has scoped access to the filtered set of files that include the acct1 text string.
CREATE SECURE VIEW acct1_files
AS
SELECT BUILD_SCOPED_FILE_URL(@acct_files, relative_file_path) scoped_url
FROM acct_table
WHERE acct_name = 'acct1';