Hasilkan URL Bertanda untuk Mengunggah dan Mengunduh Objek OSS - MaxCompute - Alibaba Cloud - MaxCompute

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

Latar Belakang

Anda dapat menggunakan Object Table MaxCompute untuk memproses data tidak terstruktur di OSS. Dengan memadukan Object Table dan SQL, Anda dapat memfilter daftar objek—seperti gambar—berdasarkan kriteria seperti waktu modifikasi, nama, atau ukuran, lalu meneruskan daftar tersebut ke layanan pihak ketiga untuk diproses. Namun, layanan tersebut memerlukan izin untuk mengunduh objek dari OSS. Pendekatan tradisional seperti penggunaan kredensial akses permanen atau asumsi peran layanan memiliki kelemahan:

Menyimpan kredensial akses di layanan pihak ketiga menimbulkan risiko keamanan tinggi jika kredensial tersebut dikompromikan.
Asumsi peran layanan biasanya merujuk pada peran yang diasumsikan oleh MaxCompute untuk mengakses OSS. Layanan pihak ketiga perlu mengasumsikan peran terpisah, yang menambah kompleksitas pada kode Anda.

OSS mendukung penggunaan URL yang ditandatangani untuk mengunduh atau melihat pratinjau file. URL dengan periode validitas yang mencukupi memungkinkan pengguna mengakses objek secara langsung melalui HTTP, sehingga menyederhanakan proses tersebut. Selain untuk pengunduhan, Anda juga dapat menghasilkan URL yang ditandatangani untuk pengunggahan data.

GET_SIGNED_URL_FROM_OSS

Fungsi ini menghasilkan URL yang ditandatangani tanpa kredensial untuk mengunduh atau mengunggah objek OSS, memungkinkan pengguna membaca atau menulis objek secara langsung melalui HTTP.

Batasan

Saat ini hanya mendukung pembuatan Object Table melalui jaringan internal OSS.
Saat ini tidak didukung untuk akselerasi kueri MaxQA. Anda perlu menambahkan parameter SET odps.mcqa.disable=true; dan menjalankannya bersama pernyataan SQL.
Jika Bucket OSS telah mengaktifkan fitur Block public access, maka tidak dimungkinkan menghasilkan alamat signature yang dapat diakses melalui internet publik menggunakan fungsi GET_SIGNED_URL_FROM_OSS. Pastikan konfigurasi izin Bucket memungkinkan pembuatan dan penggunaan alamat signature.

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 Data	Keterangan	Nilai Default
full_object_table_name	Ya	STRING	Dalam model tiga lapis, jalur lengkap OBJECT TABLE, termasuk nama Project dan Schema, contohnya: `project.schema.object_table`. Jika metode autentikasi RoleARN dipilih saat membuat tabel, parameter ini akan membantu menghasilkan STS Token untuk mengakses OSS secara otomatis.	Tidak ada
key	Ya	STRING	Nama objek yang diakses dalam Object Table tersebut. Untuk detail selengkapnya, lihat penjelasan parameter key dalam hasil definisi OBJECT TABLE.	Tidak ada
timeToLiveSeconds	Tidak	INT	Durasi periode validitas URL yang ditandatangani, minimal 1 detik dan maksimal 7 hari (604.800 detik). Tidak dapat digunakan bersamaan dengan parameter expiration.	Default 3.600 detik.
expiration	Tidak	DATETIME	Waktu kedaluwarsa URL yang ditandatangani. Minimal 1 detik lebih besar dari waktu saat ini, dan maksimal 7 hari (604.800 detik) lebih besar dari waktu saat ini. Tidak dapat digunakan bersamaan dengan parameter timeToLiveSeconds.	Default 3.600 detik lebih besar dari waktu saat ini.
httpMethod	Tidak	STRING	Cara penggunaan URL setelah dihasilkan, yaitu untuk mengunduh (membaca data OSS) atau mengunggah (menulis data ke OSS). GET berarti mengunduh. PUT berarti mengunggah.	Nilai default adalah GET.

Nilai kembalian

Mengembalikan tipe STRING, yaitu URL yang telah ditandatangani.

Definisi fungsi lainnya

Sintaks minimal: URL kedaluwarsa dalam 3.600 detik dan menggunakan metode GET.

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

Periode kedaluwarsa kustom: Menggunakan metode GET.

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

Periode kedaluwarsa dan metode HTTP kustom.

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

Waktu kedaluwarsa kustom: Menggunakan metode GET.

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

Waktu kedaluwarsa dan metode HTTP kustom.

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

Contoh

Contoh berikut menggunakan wilayah Hangzhou untuk menunjukkan cara mengunduh objek OSS melalui URL yang ditandatangani dari Instance ECS.

Saat menjalankan kode berikut, ganti project_name dan schema_name dengan nama project dan schema yang sebenarnya.

Mengunduh objek OSS dengan URL yang ditandatangani

Langkah 1: Hasilkan URL unduhan

Masuk ke Konsol OSS, unggah data uji signedget.txt ke direktori object-table-test/object_table_folder. Untuk langkah-langkahnya, lihat Upload objects.

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

-- Object Table di project MaxCompute mendukung fitur Schema, aktifkan model tiga lapis. 
SET odps.namespace.schema=true;
-- Pilih project MaxCompute yang sesuai. 
USE <project_name>;
-- Pilih schema yang sesuai. 
USE SCHEMA <schema_name>;
-- Object Table di project MaxCompute mendukung sistem tipe data 2.0. 
SET odps.sql.type.system.odps2=true;
-- Saat ini belum didukung dalam 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/';
-- Segarkan cache tabel. 
ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

Kueri informasi metadata dari tabel Object Table.

SELECT * FROM test_get_signed_url_from_oss;

Hasil yang dikembalikan:

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

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 yang dikembalikan:

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

Kueri Object Table dan hasilkan URL yang ditandatangani.

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

Hasil yang dikembalikan:

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

Masuk ke Konsol ECS, klik Instances & Images > 实例 di panel navigasi kiri.
Alihkan ke wilayah Hangzhou, pilih instance target, klik koneksi jarak jauh, dan sambungkan ke instance ECS melalui Workbench.

Jalankan perintah berikut di terminal untuk mengunduh objek OSS:

-- Alihkan ke direktori opt
cd /opt
-- Unduh objek OSS yang sesuai melalui URL yang ditandatangani.
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=****"

Hasil yang dikembalikan:

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

Mengunggah objek OSS dengan URL yang ditandatangani

Langkah 1: Hasilkan URL unggah

Gunakan Object Table yang telah dibuat bernama test_get_signed_url_from_oss. Kueri Object Table dan hasilkan URL yang ditandatangani untuk mengunggah. Contoh kodenya sebagai berikut:

SELECT get_signed_url_from_oss(
  '<project_name>.<schema_name>.test_get_signed_url_from_oss', 
  'singed_put',
  3600,
  'PUT'
) 
FROM test_get_signed_url_from_oss;

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

Di instance ECS Anda, siapkan file data uji signedput.txt dan letakkan di direktori /opt.

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

-- Alihkan 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=****"

Langkah 3: Verifikasi unggahan

Segarkan cache tabel:

ALTER TABLE test_get_signed_url_from_oss REFRESH METADATA;

SELECT * FROM test_get_signed_url_from_oss;

+------------+------------+------------+---------------+---------------+------------+--------------+------------+--------------------+
| 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 dari objek yang diunggah untuk memverifikasi isinya:

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

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

FAQ

Error: Jalur tabel tidak cocok dalam fungsi

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]).
Penyebab
Nama tabel test_get_signed_url_from_ossxxxxxx yang ditentukan dalam argumen pertama fungsi tidak ada atau tidak sesuai dengan nama tabel yang ditentukan dalam klausa FROM pernyataan SQL.
Solusi
Pastikan nama Object Table yang ditentukan dalam fungsi ada dan identik dengan nama tabel dalam klausa FROM. Gunakan format project.schema.table.

Error: Parameter timeToLiveSeconds di luar rentang

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].
Penyebab
Nilai parameter timeToLiveSeconds tidak valid. Nilai tersebut harus berupa bilangan bulat antara 1 hingga 604.800.
Solusi
Tentukan periode kedaluwarsa dalam rentang yang valid.

Error: Parameter httpMethod tidak valid

Pesan error
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'.
Penyebab
Nilai parameter httpMethod tidak valid.
Solusi
Nilai parameter httpMethod harus berupa GET atau PUT.

Error: URL yang ditandatangani telah kedaluwarsa

Pesan error
Perintah curl mengembalikan error Request has expired.
Penyebab
Periode validitas URL yang ditandatangani terlalu singkat, sehingga URL kedaluwarsa sebelum digunakan.
Solusi
Tingkatkan periode validitas dengan menetapkan nilai yang lebih besar untuk parameter expiration atau timeToLiveSeconds.

Error: Sintaks 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}').
Penyebab
Sintaks schema tidak diaktifkan, sehingga format sintaks project.schema.table tidak dikenali.
Solusi
Tambahkan perintah set odps.namespace.schema=true; sebelum pernyataan SQL Anda untuk mengaktifkan sintaks schema.