Generate signed URLs to upload and download OSS objects - MaxCompute: 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.

Contexto

Ao usar Object Tables do MaxCompute para processar dados não estruturados no OSS, serviços downstream — como pipelines de processamento de imagens ou jobs de machine learning executados no ECS — precisam acessar esses objetos diretamente. Duas abordagens comuns existem, mas ambas apresentam desvantagens:

AccessKeys permanentes — Armazenar AccessKeys em serviços de terceiros gera riscos de segurança. Em caso de vazamento, qualquer parte não autorizada poderá acessar seus dados no OSS.
Assunção de função de serviço — A função que o MaxCompute assume para acessar o OSS difere daquela exigida pelo serviço de terceiros. Gerenciar ambas as funções aumenta a complexidade do código.

As URLs assinadas do OSS permitem que serviços externos façam download ou upload de objetos diretamente via HTTP, sem exigir credenciais no código de terceiros. Gere uma URL no MaxCompute SQL, passe-a para o serviço downstream e este a utilizará dentro da janela de validade. Essa abordagem mantém suas credenciais fora de sistemas de terceiros e simplifica o código de autenticação.

GET_SIGNED_URL_FROM_OSS

A função GET_SIGNED_URL_FROM_OSS gera uma URL assinada, livre de credenciais, para download ou upload de um objeto do OSS. Use essa URL diretamente via HTTP.

Limitações

Object Tables só podem ser criadas na rede interna do OSS.
Esta função não oferece suporte à aceleração de consultas MaxQA. Adicione SET odps.mcqa.disable=true; e execute-o junto com sua instrução SQL.
Se o Bloquear Acesso Público estiver ativado para o bucket do OSS, a função GET_SIGNED_URL_FROM_OSS não conseguirá gerar uma URL assinada publicamente acessível. Certifique-se de que as permissões do bucket permitam a geração e o uso de URLs assinadas.

Sintaxe

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 de dado	Descrição	Padrão
`full_object_table_name`	Sim	STRING	Caminho completo da Object Table no modelo de três camadas, como `project.schema.object_table`. Se a autenticação RoleARN foi selecionada durante a criação da tabela, este parâmetro aciona a geração automática de um token do Security Token Service (STS) para acessar o OSS.	Nenhum
`key`	Sim	STRING	Nome do objeto a ser acessado na Object Table. Consulte a descrição do campo `key` em Visualizar propriedades da Object Table.	Nenhum
`timeToLiveSeconds`	Não	INT	Período de validade da URL assinada em segundos. Intervalo válido: 1 a 604.800 (7 dias). Não pode ser usado em conjunto com `expiration`.	3600
`expiration`	Não	DATETIME	Tempo de expiração da URL assinada. Deve ser pelo menos 1 segundo após a hora atual e no máximo 604.800 segundos (7 dias) após a hora atual. Não pode ser usado em conjunto com `timeToLiveSeconds`.	3600 segundos após a hora atual
`httpMethod`	Não	STRING	Método HTTP para a URL assinada. `GET` faz o download do objeto (leitura do OSS). `PUT` faz o upload do objeto (gravação no OSS).	`GET`

Valor de retorno

Retorna uma STRING contendo a URL assinada gerada.

Assinaturas sobrecarregadas

A função suporta as seguintes combinações de parâmetros:

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>
);

Expiração personalizada (segundos) e método HTTP:

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>
);

Expiração personalizada (DATETIME) e método HTTP:

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

Exemplos

Os exemplos a seguir usam a região China (Hangzhou) e demonstram como gerar uma URL assinada para baixar ou enviar um objeto do OSS a partir de uma instância do Elastic Compute Service (ECS).

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 console do OSS e envie o arquivo de teste signedget.txt para o diretório object-table-test/object_table_folder. Consulte Upload de arquivos para obter instruções.

Use um cliente local (odpscmd) ou crie um nó MaxCompute SQL no DataWorks para criar uma Object Table e atualizar seu cache de metadados.

-- Object Tables in MaxCompute projects support schemas. Enable the three-layer model.
SET odps.namespace.schema=true;

-- Select the target MaxCompute project.
USE <project_name>;

-- Select the target schema.
USE SCHEMA <schema_name>;

-- Object Tables in MaxCompute projects support the 2.0 data type system.
SET odps.sql.type.system.odps2=true;

-- This feature is not currently 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
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 da Object Table.

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-04 01:36:52 | Standard      | 96D8258845DAB51BC9B****6E61A2563 | NONE         | 13****     | 13****             |
+---------------+------------+------------+---------------------+---------------+----------------------------------+--------------+------------+--------------------+

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

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  |
+----------------------------------------+

Consulte a Object Table e gere uma URL assinada.

SELECT GET_SIGNED_URL_FROM_OSS(
  '<project_name>.<schema_name>.test_get_signed_url_from_oss',
  key)
FROM test_get_signed_url_from_oss;

Resultado retornado:

+------------+
| _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

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

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

# Switch to the /opt directory.
cd /opt

# Download the OSS object using the 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=****"

A figura a seguir mostra o resultado retornado:

yuddd

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

Use a Object Table test_get_signed_url_from_oss criada na seção anterior. Consulte-a com httpMethod definido como PUT para gerar uma URL de upload.

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 o arquivo 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: Verificar o upload

Atualize o cache da tabela:

ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

Consulte os metadados da Object Table para confirmar que o objeto enviado aparece:

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 enviado para confirmar o conteúdo:

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

A função retorna um erro sobre incompatibilidade no caminho da tabela

A mensagem de erro se parece com:

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])

O nome da tabela no primeiro argumento não corresponde à tabela consultada na cláusula FROM. Use o nome da Object Table existente no formato project.schema.table e certifique-se de que ele corresponda exatamente à tabela na cláusula FROM.

O valor de timeToLiveSeconds está fora do intervalo

A mensagem de erro se parece com:

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]

Defina timeToLiveSeconds como um número inteiro entre 1 e 604.800.

O valor de httpMethod é inválido

A mensagem de erro se parece com:

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'

O parâmetro httpMethod aceita apenas GET (download) ou PUT (upload). Verifique se há erros de digitação.

O comando curl retorna "Request has expired"

A URL assinada expirou antes da execução do comando curl. Isso ocorre quando o período de validade é muito curto ou há um atraso entre a geração da URL e seu uso. Defina timeToLiveSeconds com um valor que ofereça tempo suficiente para concluir a operação, mas evite definir um período desnecessariamente longo.

A função não consegue resolver o nome da tabela em três partes

A mensagem de erro se parece com:

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}')

A opção de sintaxe de schema não está habilitada. Adicione set odps.namespace.schema=true; antes da sua instrução SQL para ativar a sintaxe do modelo de três camadas (project.schema.table).