Generate signed URLs to upload and download OSS objects - : Central de Documentação do Alibaba Cloud

Este tópico descreve como usar uma Object Table para gerar URLs assinadas para upload e download de objetos do OSS.

Informações básicas

As Object Tables do MaxCompute permitem processar dados não estruturados no OSS. Com essas tabelas e consultas SQL, você filtra objetos, como imagens, com base em metadados e os encaminha a um serviço de terceiros para processamento. No entanto, esses serviços de computação exigem permissões para baixar objetos do OSS. Os métodos comuns incluem o uso de pares de AccessKey permanentes ou a assunção de funções de serviço. Essas abordagens apresentam desvantagens:

Pares de AccessKey permanentes representam um risco de segurança, pois exigem o armazenamento das credenciais no serviço de terceiros. Em caso de vazamento, seus dados ficam altamente vulneráveis.
A assunção de função de serviço geralmente se refere à função que o MaxCompute assume para acessar o OSS. O serviço de terceiros precisa assumir outra função, o que aumenta a complexidade do código.

O OSS oferece suporte a using presigned URLs to download or preview files. Se a URL for válida, você acessa o objeto diretamente via HTTP. Essa operação é simples e permite gerar URLs tanto para downloads quanto para uploads.

GET_SIGNED_URL_FROM_OSS

A função GET_SIGNED_URL_FROM_OSS gera uma URL assinada para baixar ou enviar um objeto do OSS. Use essa URL para ler ou gravar arquivos do OSS diretamente via HTTP.

Limites

Crie Object Tables apenas com o endpoint interno do OSS.
Esta função não tem suporte para aceleração de consultas MaxQA. Inclua o comando SET odps.mcqa.disable=true; na instrução SQL.
Se um bucket do OSS tiver o recurso Block Public Access ativado, a função GET_SIGNED_URL_FROM_OSS não gera uma URL pré-assinada publicamente acessível. Verifique se as permissões do bucket permitem a geração e o uso de URLs pré-assinadas.

Definição da função

STRING GET_SIGNED_URL_FROM_OSS (
  STRING <full_object_table_name>, 
  STRING <key>
  [, INT <timeToLiveSeconds>] 
  [, DATETIME <expiration>]
  [, STRING <httpMethod>]
)

Parâmetros

Parâmetro	Obrigatório	Tipo	Descrição	Padrão
full_object_table_name	Sim	STRING	Caminho completo da Object Table no modelo de três camadas, incluindo os nomes do projeto e do schema. Exemplo: `project.schema.object_table`. Se você escolher a autenticação RoleARN ao criar a tabela, um token STS será gerado automaticamente para acessar o OSS.	Nenhum
key	Sim	STRING	Nome do objeto a ser acessado na Object Table. Para mais detalhes sobre o parâmetro key, consulte a descrição nos resultados retornados de View Object Table properties.	Nenhum
timeToLiveSeconds	Não	INT	Tempo de vida da URL pré-assinada em segundos. Mínimo: 1 segundo. Máximo: 604.800 segundos (7 dias). Este parâmetro é mutuamente exclusivo com expiration.	3.600 segundos
expiration	Não	DATETIME	Data e hora de expiração da URL pré-assinada. O valor deve ser de pelo menos 1 segundo e no máximo 604.800 segundos (7 dias) após a hora atual. Este parâmetro é mutuamente exclusivo com timeToLiveSeconds.	3.600 segundos após a hora atual
httpMethod	Não	STRING	Método HTTP da URL gerada. Define se a operação será de download (leitura) ou upload (gravação) no OSS. GET: Download PUT: Upload	GET

Valor retornado

Retorna a URL pré-assinada gerada como uma STRING.

Definições de função para outros cenários

Configuração mínima: expira em 3.600 segundos, método GET.

STRING get_signed_url_from_oss (
  STRING <fullTableName>,
  STRING <ossKey>
);

Expiração personalizada (segundos): método GET.

STRING GET_SIGNED_URL_FROM_OSS(
  STRING <fullTableName>, 
  STRING <ossKey>, 
  INT <timeToLiveSeconds>
);

Personalização do período de expiração e das permissões de leitura/gravação.

STRING GET_SIGNED_URL_FROM_OSS(
  STRING <fullTableName>, 
  STRING <ossKey>, 
  INT <timeToLiveSeconds>, 
  STRING <httpMethod>
);

Expiração personalizada (DATETIME): método GET.

STRING GET_SIGNED_URL_FROM_OSS(
  STRING <fullTableName>, 
  STRING <ossKey>, 
  DATETIME <expiration>
);

Personalização da hora de expiração e das permissões de leitura/gravação.

STRING GET_SIGNED_URL_FROM_OSS(
  STRING <fullTableName>, 
  STRING <ossKey>, 
  DATETIME <expiration>, 
  STRING <httpMethod>
);

Exemplos de uso

O exemplo a seguir gera uma URL pré-assinada para baixar um objeto do OSS a partir de uma instância do Elastic Compute Service (ECS) na região China (Hangzhou).

Antes de executar o código abaixo, substitua project_name e schema_name pelos nomes reais do seu projeto e schema.

Baixar um objeto do OSS de uma instância ECS usando uma URL assinada

Etapa 1: Gerar uma URL para baixar o objeto do OSS

Faça login no OSS console e envie o arquivo de teste signedget.txt para o diretório object-table-test/object_table_folder. Para mais informações, consulte Upload files.

Use um local client (odpscmd) ou crie um MaxCompute SQL node no DataWorks para criar uma Object Table e atualizar o cache de metadados.

-- Enable the three-layer model to support schemas in a MaxCompute project. 
SET odps.namespace.schema=true;
-- Select the MaxCompute project. 
USE <project_name>;
-- Select the schema. 
USE SCHEMA <schema_name>;
-- Enable the 2.0 data type system in the MaxCompute project. 
SET odps.sql.type.system.odps2=true;
-- This function is not supported for MaxQA query acceleration. 
SET odps.mcqa.disable=true;
-- Create an Object Table. 
CREATE OBJECT TABLE IF NOT EXISTS test_get_signed_url_from_oss 
WITH serdeproperties (
  'odps.properties.rolearn'='acs:ram::<uid>:role/<role_name>'
) 
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/object-table-test/object_table_folder/';
-- Refresh the table cache. 
ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

Consulte os metadados na Object Table.

SET odps.namespace.schema=true;
SELECT * FROM test_get_signed_url_from_oss;

Saída esperada:

+---------------+------------+------------+---------------------+---------------+----------------------------------+--------------+------------+--------------------+
| key           | size       | type       | last_modified       | storage_class | etag                             | restore_info | owner_id   | owner_display_name |
+---------------+------------+------------+---------------------+---------------+----------------------------------+--------------+------------+--------------------+
| signedget.txt | 38         | Normal     | 2025-06-04 01:36:52 | Standard      | 96D8258845DAB51BC9B****6E61A2563 | NONE         | 13****     | 13****             |
+---------------+------------+------------+---------------------+---------------+----------------------------------+--------------+------------+--------------------+

Leia os dados do objeto utilizando a função GET_DATA_FROM_OSS.

SET odps.namespace.schema=true;
SELECT 
  STRING(   
    GET_DATA_FROM_OSS(
      '<project_name>.<schema_name>.test_get_signed_url_from_oss',
      key
    )
  )
FROM test_get_signed_url_from_oss;

Saída esperada:

+----------------------------------------+
| _c0                                    |
+----------------------------------------+
| test maxcompute download files by url  |
+----------------------------------------+

Consulte a Object Table e gere uma URL pré-assinada.

SET odps.namespace.schema=true;
SELECT GET_SIGNED_URL_FROM_OSS(  
  '<project_name>.<schema_name>.test_get_signed_url_from_oss',    
  key) 
FROM test_get_signed_url_from_oss;

Saída esperada:

+------------+
| _c0        |
+------------+
| http://object-table-test.oss-cn-hangzhou-internal.aliyuncs.com/object_table_folder%2Fsignedget.txt?Expires=17490****&OSSAccessKeyId=STS.****&Signature=****&security-token=**** |
+------------+

Etapa 2: Baixar o objeto de uma instância ECS

Acesse o ECS console. No painel de navegação à esquerda, escolha Instances & Images > Instances.
Na região China (Hangzhou), selecione a instância desejada, clique em Remote Connection e conecte-se à instância usando o Workbench.

No terminal, execute os comandos a seguir para baixar o objeto do OSS:

-- Change the directory to /opt.
cd /opt
-- Download the OSS object by using the pre-signed URL.
curl -o /opt/ecs_signed.txt "http://object-table-test.oss-cn-hangzhou-internal.aliyuncs.com/object_table_folder%2Fsignedget.txt?Expires=17490****&OSSAccessKeyId=STS.****&Signature=****&security-token=****"

Saída:

[xxx] opt]# curl -o /opt/ecs_signed.txt "http://object-table-test.oss-cn-hangzhou-inxxx&SAccessKeyId=STS.xxx&Signature=xxx&security-token=CAIS3gJxxx
xxx
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    38  100    38    0     0    263      0 --:--:-- --:--:-- --:--:--   265
opt]# ls
aliyun-security  ecs_signed.txt
[root@iZbp1al9u5z0axrqx50mptZ opt]# cat ecs_signed.txt
test maxcompute download files by url
xxx opt]#

Enviar um objeto do OSS de uma instância ECS usando uma URL assinada

Etapa 1: Gerar uma URL para enviar o objeto do OSS

Consulte a Object Table test_get_signed_url_from_oss criada anteriormente para gerar uma URL assinada. O código abaixo serve como exemplo:

SET odps.namespace.schema=true;
SELECT get_signed_url_from_oss(
  '<project_name>.<schema_name>.test_get_signed_url_from_oss', 
  key,
  3600,
  'PUT'
) 
FROM test_get_signed_url_from_oss;

Resultado retornado:

+------------+
| _c0        |
+------------+
| http://object-table-test.oss-cn-hangzhou-internal.aliyuncs.com/object_table_folder%2Fsinged_put?Expires=17490****&OSSAccessKeyId=****&Signature=****&security-token=**** |
+------------+

Etapa 2: Enviar o objeto de uma instância ECS

Prepare o arquivo de teste signedput.txt e envie-o para o diretório /opt na instância ECS.

No terminal do Workbench, execute o comando a seguir para enviar os dados ao OSS.

# Switch to the /opt directory.
cd /opt

# Upload signedput.txt to OSS using the signed URL.
curl -X PUT -T /opt/signedput.txt -i "http://object-table-test.oss-cn-hangzhou-internal.aliyuncs.com/object_table_folder%2Fsinged_put?Expires=17490****&OSSAccessKeyId=****&Signature=****&security-token=****"

A figura a seguir mostra o resultado:

opopopo

Etapa 3: Consultar os metadados da Object Table

Atualize o cache da tabela:

SET odps.namespace.schema=true;
ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

Consulte os metadados da Object Table:

SET odps.namespace.schema=true;
SELECT * FROM test_get_signed_url_from_oss;

Resultado retornado:

+------------+------------+------------+---------------+---------------+------------+--------------+------------+--------------------+
| key        | size       | type       | last_modified | storage_class | etag       | restore_info | owner_id   | owner_display_name |
+------------+------------+------------+---------------+---------------+------------+--------------+------------+--------------------+
| signedget.txt | 38         | Normal     | 2025-06-03 01:36:52 | Standard      | 96D8258845DAB51BC****546E61A2563 | NONE         | 13**** | 13****   |
| singed_put | 44         | Normal     | 2025-06-03 19:31:23 | Standard      | F5EA64DF895CF08C3****7D3FD09F12 | NONE         | 13**** | 13****   |
+------------+------------+------------+---------------+---------------+------------+--------------+------------+--------------------+

Leia os dados do objeto do OSS usando GET_DATA_FROM_OSS.

SET odps.namespace.schema=true;
SELECT
  string(   
    get_data_from_oss(
      '<project_name>.<schema_name>.test_get_signed_url_from_oss',
      key
    )
  )
FROM test_get_signed_url_from_oss;

Resultado retornado:

+------------+
| _c0        |
+------------+
| test maxcompute download files by url  |
| test  Object Table upload file to oss by url |
+------------+

Perguntas frequentes

Problema 1: O caminho da tabela na função difere do caminho da tabela subjacente consultada

Mensagem de erro

ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed: Can't do ObjectTableTwoPhasesSplitting process (Caused by: java.lang.IllegalArgumentException: The first arg[xxx.default.test_get_signed_url_from_ossxxxxxx] of function GET_SIGNED_URL_FROM_OSS({object_table_full_name}, {object_key}, ...) can't be found in the underlying object table scans[xxx.default.test_get_signed_url_from_oss]).
Descrição do problema

O nome da tabela test_get_signed_url_from_ossxxxxxx não existe ou difere do nome especificado na instrução SQL.
Solução

Especifique o nome de uma Object Table existente no formato project.schema.table.

O valor do parâmetro `timeToLiveSeconds` é inválido

Mensagem de erro

ODPS-0121095:[1,8] Invalid argument - The parameter <timeToLiveSeconds> of the function GET_SIGNED_URL_FROM_OSS() you specified (0) is invalid, it should be in the range [1, 604800].
Descrição do problema

O valor do parâmetro timeToLiveSeconds é inválido. Ele deve estar no intervalo [1, 604800].
Solução

Defina um valor válido para o tempo de vida (TTL).

O valor do parâmetro `HttpMethod` é inválido

Mensagem de erro

ODPS-0121095:[1,8] Invalid argument - The parameter <httpMethod> of the function GET_SIGNED_URL_FROM_OSS() you specified 'PU' is invalid, it can only be 'GET' or 'PUT'.
Descrição do problema

O valor do parâmetro HttpMethod é inválido.
Solução

Defina o parâmetro HttpMethod como GET ou PUT.

O link expirou porque o período de validade é muito curto

Mensagem de erro

O erro Request has expired é relatado ao executar o comando curl.
Descrição do problema

A URL assinada expirou antes de ser utilizada.
Solução

Defina um valor razoável para o parâmetro expiration. Evite valores excessivamente longos ou curtos.

A sintaxe do modelo de três camadas não está ativada

Mensagem de erro

ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed: Can't do ObjectTableTwoPhasesSplitting process (Caused by: java.lang.IllegalArgumentException: Invalid parameter of object table full name[str=xxx.test_get_signed_url_from_oss], which should be split up into 3 parts by '.' like '${project}.${schema}.${table}').
Descrição do problema

A sintaxe de schema não está ativada. Por isso, o formato project.schema.table não pode ser analisado.
Solução

Adicione o comando set odps.namespace.schema=true; antes da instrução SQL para ativar a sintaxe de schema.

Informações básicas

GET_SIGNED_URL_FROM_OSS

Limites

Definição da função

Parâmetros

Valor retornado

Definições de função para outros cenários

Exemplos de uso

Baixar um objeto do OSS de uma instância ECS usando uma URL assinada

Etapa 1: Gerar uma URL para baixar o objeto do OSS

Etapa 2: Baixar o objeto de uma instância ECS

Enviar um objeto do OSS de uma instância ECS usando uma URL assinada

Etapa 1: Gerar uma URL para enviar o objeto do OSS

Etapa 2: Enviar o objeto de uma instância ECS

Etapa 3: Consultar os metadados da Object Table

Perguntas frequentes

Problema 1: O caminho da tabela na função difere do caminho da tabela subjacente consultada

O valor do parâmetro timeToLiveSeconds é inválido

O valor do parâmetro HttpMethod é inválido

O link expirou porque o período de validade é muito curto

A sintaxe do modelo de três camadas não está ativada

O valor do parâmetro `timeToLiveSeconds` é inválido

O valor do parâmetro `HttpMethod` é inválido