Hasilkan URL yang ditandatangani untuk mengunggah dan mengunduh objek OSS -

Topik ini menjelaskan cara menggunakan Object Table untuk menghasilkan URL yang ditandatangani guna mengunggah dan mengunduh objek OSS.

Informasi latar belakang

Anda dapat menggunakan Object Table MaxCompute untuk memproses data tidak terstruktur di OSS. Dengan Object Table dan kueri SQL, Anda dapat menyaring objek—seperti gambar—berdasarkan metadata-nya, lalu meneruskannya ke layanan pihak ketiga untuk diproses. Namun, layanan komputasi tersebut memerlukan izin untuk mengunduh objek OSS. Metode umum meliputi penggunaan pasangan AccessKey permanen atau asumsi peran layanan, yang masing-masing memiliki kelemahan:

Pasangan AccessKey permanen menimbulkan risiko keamanan karena harus disimpan di layanan pihak ketiga. Jika bocor, data Anda berada dalam risiko tinggi.
Asumsi peran layanan biasanya merujuk pada peran yang diasumsikan oleh MaxCompute untuk mengakses OSS. Layanan pihak ketiga harus mengasumsikan peran lain, sehingga meningkatkan kompleksitas kode.

OSS mendukung penggunaan URL praditandatangani (presigned URLs) untuk mengunduh atau meninjau file. Jika URL tersebut valid, Anda dapat langsung mengakses objek melalui HTTP. Pendekatan ini sederhana. Selain untuk pengunduhan, Anda juga dapat menghasilkan URL praditandatangani untuk pengunggahan.

GET_SIGNED_URL_FROM_OSS

Fungsi GET_SIGNED_URL_FROM_OSS menghasilkan URL yang ditandatangani untuk mengunduh atau mengunggah objek OSS. URL tersebut dapat digunakan untuk membaca atau menulis file OSS secara langsung melalui HTTP.

Batasan

Anda hanya dapat membuat Object Table menggunakan titik akhir internal OSS.
Fungsi ini tidak didukung untuk akselerasi kueri MaxQA. Anda harus menyertakan perintah SET odps.mcqa.disable=true; bersama pernyataan SQL Anda.
Jika bucket OSS memiliki fitur Block Public Access yang diaktifkan, fungsi GET_SIGNED_URL_FROM_OSS tidak dapat menghasilkan URL praditandatangani yang dapat diakses publik. Pastikan izin bucket Anda mengizinkan pembuatan dan penggunaan URL praditandatangani.

Definisi fungsi

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

Parameter

Parameter	Wajib	Tipe	Deskripsi	Bawaan
full_object_table_name	Ya	STRING	Jalur lengkap Object Table dalam model tiga lapis, termasuk nama project dan schema. Contoh: `project.schema.object_table`. Jika Anda memilih otentikasi RoleARN saat membuat tabel, token STS akan secara otomatis dihasilkan untuk mengakses OSS.	Tidak ada
key	Ya	STRING	Nama objek yang akan diakses dalam Object Table. Untuk informasi lebih lanjut tentang parameter key, lihat deskripsi dalam hasil yang dikembalikan oleh View Object Table properties.	Tidak ada
timeToLiveSeconds	Tidak	INT	Waktu hidup (TTL) URL praditandatangani dalam detik. Minimum: 1 detik. Maksimum: 604.800 detik (7 hari). Parameter ini saling eksklusif dengan expiration.	3.600 detik
expiration	Tidak	DATETIME	Waktu kedaluwarsa URL praditandatangani. Nilainya harus minimal 1 detik dan maksimal 604.800 detik (7 hari) setelah waktu saat ini. Parameter ini saling eksklusif dengan timeToLiveSeconds.	3.600 detik setelah waktu saat ini
httpMethod	Tidak	STRING	Metode HTTP untuk URL yang dihasilkan, yang menentukan apakah akan mengunduh (membaca) dari atau mengunggah (menulis) ke OSS. GET: Unduh PUT: Unggah	GET

Nilai kembalian

Mengembalikan URL praditandatangani yang dihasilkan sebagai STRING.

Definisi fungsi untuk skenario lain

Minimal: kedaluwarsa dalam 3600 detik, metode GET.

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

Kedaluwarsa kustom (detik): metode GET.

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

Anda dapat menyesuaikan periode kedaluwarsa dan izin baca/tulis.

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

Kedaluwarsa kustom (DATETIME): metode GET.

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

Anda dapat menyesuaikan waktu kedaluwarsa dan izin baca/tulis.

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

Contoh penggunaan

Contoh berikut menghasilkan URL praditandatangani untuk mengunduh objek OSS dari instance Elastic Compute Service (ECS) di wilayah Tiongkok (Hangzhou).

Sebelum menjalankan kode berikut, ganti project_name dan schema_name dengan nama project dan schema aktual Anda.

Unduh objek OSS dari instance ECS menggunakan URL yang ditandatangani

Langkah 1: Hasilkan URL untuk mengunduh objek OSS

Masuk ke Konsol OSS dan unggah file uji signedget.txt ke direktori object-table-test/object_table_folder. Untuk informasi selengkapnya, lihat Upload files.

Gunakan client lokal (odpscmd) atau buat node SQL MaxCompute di DataWorks untuk membuat Object Table dan refresh cache metadata.

-- Aktifkan model tiga lapis untuk mendukung schema dalam project MaxCompute. 
SET odps.namespace.schema=true;
-- Pilih project MaxCompute. 
USE <project_name>;
-- Pilih schema. 
USE SCHEMA <schema_name>;
-- Aktifkan sistem tipe data 2.0 dalam project MaxCompute. 
SET odps.sql.type.system.odps2=true;
-- Fungsi ini tidak didukung untuk akselerasi kueri MaxQA. 
SET odps.mcqa.disable=true;
-- Buat 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 cache tabel. 
ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

Kueri metadata dalam Object Table.

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

Output yang diharapkan:

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

Baca data objek menggunakan fungsi 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;

Output yang diharapkan:

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

Kueri Object Table dan hasilkan URL praditandatangani.

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;

Output yang diharapkan:

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

Langkah 2: Unduh objek dari instance ECS

Masuk ke Konsol ECS. Di panel navigasi kiri, pilih Instances & Images > Instances.
Di wilayah Tiongkok (Hangzhou), pilih instance target, klik Remote Connection, lalu sambungkan ke instance menggunakan Workbench.

Di terminal, jalankan perintah berikut untuk mengunduh objek OSS:

-- Ubah direktori ke /opt.
cd /opt
-- Unduh objek OSS menggunakan URL praditandatangani.
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=****"

Output:

[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]#

Unggah objek OSS dari instance ECS menggunakan URL yang ditandatangani

Langkah 1: Hasilkan URL untuk mengunggah objek OSS

Kueri Object Table test_get_signed_url_from_oss yang telah dibuat untuk menghasilkan URL yang ditandatangani. Kode berikut memberikan contohnya:

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;

Hasil berikut dikembalikan:

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

Langkah 2: Unggah objek dari instance ECS

Siapkan file uji signedput.txt dan unggah ke direktori /opt pada instance ECS.

Di terminal Workbench, jalankan perintah berikut untuk mengunggah data ke OSS.

# Beralih ke direktori /opt.
cd /opt

# Unggah signedput.txt ke OSS menggunakan URL yang ditandatangani.
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=****"

Gambar berikut menunjukkan hasilnya:

opopopo

Langkah 3: Kueri metadata Object Table

Refresh cache tabel:

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

Anda dapat mengkueri metadata Object Table:

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

Berikut ini hasil yang dikembalikan:

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

Baca data objek OSS menggunakan 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;

Hasil berikut dikembalikan:

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

FAQ

Masalah 1: Jalur tabel dalam fungsi berbeda dari jalur tabel dasar yang dikueri

Pesan error
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]).
Deskripsi masalah
Nama tabel test_get_signed_url_from_ossxxxxxx tidak ada atau berbeda dari nama tabel yang ditentukan dalam pernyataan SQL.
Solusi
Tentukan nama Object Table yang ada dalam format project.schema.table.

Nilai parameter `timeToLiveSeconds` tidak valid

Pesan error
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].
Deskripsi masalah
Nilai parameter `timeToLiveSeconds` tidak valid. Nilainya harus berada dalam rentang [1, 604800].
Solusi
Tentukan nilai Waktu hidup (TTL) yang valid.

Nilai parameter `HttpMethod` tidak valid

Pesan kesalahan
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'.
Deskripsi masalah
Nilai parameter `HttpMethod` tidak valid.
Solusi
Atur parameter `HttpMethod` menjadi GET atau PUT.

Tautan kedaluwarsa karena periode validitas terlalu singkat

Pesan error
Error `Request has expired` dilaporkan saat Anda menjalankan perintah curl.
Deskripsi Masalah
URL yang ditandatangani telah kedaluwarsa sebelum digunakan.
Solusi
Tentukan nilai yang wajar untuk parameter `expiration`. Hindari nilai yang terlalu panjang atau terlalu pendek.

Sintaksis model tiga lapis tidak diaktifkan

Pesan error
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}').
Deskripsi masalah
Sintaksis schema tidak diaktifkan, sehingga format project.schema.table tidak dapat diurai.
Solusi
Tambahkan perintah set odps.namespace.schema=true; sebelum pernyataan SQL untuk mengaktifkan sintaksis schema.