Hướng dẫn generate Token để tạo Temp URL upload file trong vStorage API (HCM03)
Upload File lên vStorage sử dụng Temporary URL (HCM03)
Hướng dẫn xác thực với VNG Cloud IAM và tải tệp lên vStorage thông qua Temporary URL mà không cần xác thực trực tiếp mỗi lần gọi API.
1. Tạo Authentication Token
Trước khi gọi bất kỳ API nào của vStorage, cần lấy token xác thực từ hệ thống IAM VNG Cloud thông qua Service Account.
Bước 1: Truy cập trang quản lý Service Account tại https://iam.console.vngcloud.vn/service-accounts để tạo Service Account mới. Sau khi tạo xong, hệ thống cấp một cặp thông tin xác thực:
- Client ID — ví dụ:
ec2d4f62-6580-406e-95e3-b17xxxxxxx - Secret ID — ví dụ:
4ec7b98b-df1c-480e-bc01-38fxxxxxxx
Bước 2: Mã hóa chuỗi ClientID:SecretID sang định dạng Base64. Có hai cách thực hiện:
Cách 1 — Dùng công cụ mã hóa online:
Truy cập https://www.convertstring.com/vi/EncodeDecode/Base64Encode, nhập chuỗi theo định dạng ClientID:SecretID rồi thực hiện mã hóa.
Cách 2 — Dùng lệnh trên Linux:
echo -n ClientID:SecretID | base64 -w 0Bước 3: Gọi API lấy token, thay Base64(ClientID:SecretID) bằng chuỗi đã mã hóa ở bước trên:
curl --location 'https://iamapis.vngcloud.vn/accounts-api/v1/auth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Base64(ClientID:SecretID)' \
--data '{
"grantType": "client_credentials"
}'Phản hồi trả về chứa trường access_token — đây là Authentication Token dùng cho các bước tiếp theo.
▸ Nếu dùng Postman, vào tab Authorization, chọn kiểu Basic Auth, nhập Client ID vào trường Username và Secret ID vào trường Password — Postman sẽ tự động mã hóa Base64.
2. Upload File bằng Temporary URL
Temporary URL (Temp URL) là một URL có chữ ký và thời hạn, cho phép tải tệp lên vStorage mà không cần gắn token xác thực vào mỗi request — phù hợp để tích hợp upload từ ứng dụng bên ngoài.
Bước 4: Tạo Temp URL cho tệp cần upload bằng API sau. Thay <Project ID>, <container_name>, <file_name> và <Token> bằng giá trị thực tế của dự án:
curl -X 'POST' \
'https://hcm03-api.vstorage.vngcloud.vn/api/v1/projects/<Project ID>/containers/<container_name>/objects/<file_name>/upload_tempurls' \
-H 'accept: */*' \
-H 'Authorization: Bearer <Token>' \
-H 'Content-Type: application/json' \
-d '{
"timeExpire": 1800
}'▸ Tham số timeExpire xác định thời gian hiệu lực của Temp URL tính bằng giây.
Nếu dùng Postman, chọn Import → Paste Raw Text, dán đoạn curl trên vào rồi gửi request.
Phản hồi trả về một URL có dạng:
https://hcm03.vstorage.vngcloud.vn/v1/AUTH_<project_auth>/<container>/<filename>?temp_url_sig=<sig>&temp_url_expires=<timestamp>Bước 5: Dùng Temp URL vừa nhận được để tải tệp lên bằng phương thức PUT:
curl --location --request PUT '<temp_url_day_du>' \
--header 'Content-Type: image/jpeg' \
--data-binary '@/duong/dan/den/file/tren/may.jpg'▸ Thay <temp_url_day_du> bằng toàn bộ URL nhận được ở Bước 4, và cập nhật đường dẫn tệp cục bộ cho đúng.
timeExpire. Cần upload nhiều tệp thì tạo Temp URL riêng cho từng tệp.