Tham chiếu SDK

FPT Object Storage tương thích với AWS S3 API, nên ứng dụng có thể dùng AWS SDK chính thức để đọc và ghi dữ liệu. Mỗi mục dưới đây hướng dẫn cài đặt SDK, tạo client và thực hiện các thao tác cơ bản với bucket và object.

mẹo

Để quản lý dữ liệu mà không cần viết code, hãy dùng S3 client. Xem Kết nối bằng S3 client.

Trước khi bắt đầu

Mọi ví dụ đều dùng các placeholder sau. Thay bằng giá trị thực tế lấy từ Portal. Xem Quản lý Access Key.

Placeholder	Giá trị
`YOUR_ACCESS_KEY`	Access Key.
`YOUR_SECRET_KEY`	Secret Key.
`YOUR_ENDPOINT`	Endpoint của Region, dạng URL đầy đủ gồm cả `https://`, ví dụ `https://s3-hcm04.fptcloud.com`.
`YOUR_REGION`	Region của bucket.

cảnh báo

Không bao giờ hard-code Admin Access Key trong source code được chia sẻ hoặc triển khai. Dùng key của SubUser hoặc IAM User chỉ với các quyền ứng dụng cần, và nạp key từ biến môi trường hoặc secret store.

mẹo

Các phiên bản SDK phát hành từ năm 2025 mặc định thêm checksum kiểm tra toàn vẹn dữ liệu vào request upload. Nếu upload lỗi với các thông báo như XAmzContentSHA256Mismatch hoặc MissingContentLength, đặt tùy chọn tính checksum cho request của SDK thành when_required. Xem Khắc phục sự cố.

Python

Dùng boto3, AWS SDK chính thức cho Python.

Cài đặt

pip install boto3

Khởi tạo client

import boto3

s3_endpoint = "YOUR_ENDPOINT"
s3_access_key_id = "YOUR_ACCESS_KEY"
s3_secret_access_key = "YOUR_SECRET_KEY"

s3client = boto3.client(
    "s3",
    endpoint_url=s3_endpoint,
    aws_access_key_id=s3_access_key_id,
    aws_secret_access_key=s3_secret_access_key,
)

s3 = boto3.resource(
    "s3",
    endpoint_url=s3_endpoint,
    aws_access_key_id=s3_access_key_id,
    aws_secret_access_key=s3_secret_access_key,
)

Ví dụ cơ bản

bucket_name = "my-unique-bucket-name"
object_key = "my-object-key"

s3client.create_bucket(Bucket=bucket_name)

s3client.put_object(Bucket=bucket_name, Key=object_key, Body="Hello, world!")

response = s3client.get_object(Bucket=bucket_name, Key=object_key)
print(response["Body"].read().decode("utf-8"))

s3client.delete_object(Bucket=bucket_name, Key=object_key)
s3client.delete_bucket(Bucket=bucket_name)

Tài liệu đầy đủ: Tài liệu boto3.

Java

Dùng AWS SDK for Java 2.x.

Cài đặt

Thêm dependency vào file pom.xml của project Maven.

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.17.42</version> <!-- Use the latest 2.x version -->
</dependency>

Khởi tạo client

String accessKey = "YOUR_ACCESS_KEY";
String secretKey = "YOUR_SECRET_KEY";
String endpoint = "YOUR_ENDPOINT";
String region = "YOUR_REGION";

S3Client s3Client = S3Client.builder()
    .endpointOverride(URI.create(endpoint))
    .region(Region.of(region))
    .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey)))
    .serviceConfiguration(S3Configuration.builder().pathStyleAccessEnabled(true).build())
    .build();

Ví dụ cơ bản

import java.net.URI;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;
import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Object;

public class S3Example {
    public static void main(String[] args) {
        String bucketName = "my-unique-bucket-name";
        String objectKey = "my-object-key";

        S3Client s3Client = S3Client.builder()
            .endpointOverride(URI.create("YOUR_ENDPOINT"))
            .region(Region.of("YOUR_REGION"))
            .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")))
            .serviceConfiguration(S3Configuration.builder().pathStyleAccessEnabled(true).build())
            .build();

        // Create a bucket
        s3Client.createBucket(CreateBucketRequest.builder().bucket(bucketName).build());

        // Upload an object
        s3Client.putObject(
            PutObjectRequest.builder().bucket(bucketName).key(objectKey).build(),
            RequestBody.fromString("Hello, world!"));

        // List objects
        for (S3Object object : s3Client.listObjectsV2(
                ListObjectsV2Request.builder().bucket(bucketName).build()).contents()) {
            System.out.println("Object Key: " + object.key());
        }

        // Read an object
        String content = s3Client.getObjectAsBytes(
            GetObjectRequest.builder().bucket(bucketName).key(objectKey).build()).asUtf8String();
        System.out.println(content);

        // Delete the object, then the empty bucket
        s3Client.deleteObject(DeleteObjectRequest.builder().bucket(bucketName).key(objectKey).build());
        s3Client.deleteBucket(DeleteBucketRequest.builder().bucket(bucketName).build());

        s3Client.close();
    }
}

Tài liệu đầy đủ: AWS SDK for Java.

C#

Dùng AWS SDK for .NET.

Cài đặt

dotnet add package AWSSDK.S3

Khởi tạo client

var config = new AmazonS3Config
{
    ServiceURL = "YOUR_ENDPOINT",
    ForcePathStyle = true
};
var client = new AmazonS3Client("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", config);

Ví dụ cơ bản

using System;
using System.IO;
using System.Threading.Tasks;
using Amazon.S3;
using Amazon.S3.Model;

class Program
{
    static async Task Main()
    {
        var config = new AmazonS3Config
        {
            ServiceURL = "YOUR_ENDPOINT",
            ForcePathStyle = true
        };
        using var client = new AmazonS3Client("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", config);

        string bucketName = "my-unique-bucket-name";
        string objectKey = "my-object-key";

        // Create a bucket
        await client.PutBucketAsync(new PutBucketRequest { BucketName = bucketName });

        // Upload an object
        await client.PutObjectAsync(new PutObjectRequest
        {
            BucketName = bucketName,
            Key = objectKey,
            ContentBody = "Hello, world!"
        });

        // Read an object
        using (GetObjectResponse response = await client.GetObjectAsync(bucketName, objectKey))
        using (var reader = new StreamReader(response.ResponseStream))
        {
            Console.WriteLine(await reader.ReadToEndAsync());
        }

        // Delete the object, then the empty bucket
        await client.DeleteObjectAsync(bucketName, objectKey);
        await client.DeleteBucketAsync(bucketName);
    }
}

Tài liệu đầy đủ: AWS SDK for .NET.

PHP

Dùng AWS SDK for PHP.

Cài đặt

composer require aws/aws-sdk-php

Khởi tạo client

<?php
require 'vendor/autoload.php';

use Aws\S3\S3Client;

$s3Client = new S3Client([
    'version' => 'latest',
    'region' => 'YOUR_REGION',
    'endpoint' => 'YOUR_ENDPOINT',
    'use_path_style_endpoint' => true,
    'credentials' => [
        'key' => 'YOUR_ACCESS_KEY',
        'secret' => 'YOUR_SECRET_KEY',
    ],
]);

Ví dụ cơ bản

<?php
require 'vendor/autoload.php';

use Aws\S3\S3Client;

$s3Client = new S3Client([
    'version' => 'latest',
    'region' => 'YOUR_REGION',
    'endpoint' => 'YOUR_ENDPOINT',
    'use_path_style_endpoint' => true,
    'credentials' => [
        'key' => 'YOUR_ACCESS_KEY',
        'secret' => 'YOUR_SECRET_KEY',
    ],
]);

$bucketName = 'my-unique-bucket-name';
$objectKey = 'my-object-key';

// Create a bucket
$s3Client->createBucket(['Bucket' => $bucketName]);

// Upload an object
$s3Client->putObject([
    'Bucket' => $bucketName,
    'Key' => $objectKey,
    'Body' => 'Hello, world!',
]);

// Read an object
$result = $s3Client->getObject(['Bucket' => $bucketName, 'Key' => $objectKey]);
echo $result['Body']->getContents();

// Delete the object, then the empty bucket
$s3Client->deleteObject(['Bucket' => $bucketName, 'Key' => $objectKey]);
$s3Client->deleteBucket(['Bucket' => $bucketName]);

Tài liệu đầy đủ: AWS SDK for PHP.

JavaScript trên trình duyệt

Trên trình duyệt, không tạo S3 client bằng Access Key, vì bất kỳ ai mở trang đều đọc được key. Thay vào đó, để backend tạo presigned URL có thời hạn ngắn, rồi upload hoặc download trực tiếp từ trình duyệt bằng URL đó. Cấu hình Bucket CORS để cho phép origin của website.

Cài đặt

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Khởi tạo client

// Backend (Node.js, ES module)
import { S3Client } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  region: 'YOUR_REGION',
  endpoint: 'YOUR_ENDPOINT',
  forcePathStyle: true,
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
  },
});

Ví dụ cơ bản

// Backend: create a presigned upload URL that is valid for 15 minutes
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const uploadUrl = await getSignedUrl(
  s3,
  new PutObjectCommand({ Bucket: 'my-unique-bucket-name', Key: 'uploads/photo.jpg' }),
  { expiresIn: 900 },
);

// Browser: upload the selected file with the presigned URL
const file = document.querySelector('input[type="file"]').files[0];
await fetch(uploadUrl, { method: 'PUT', body: file });

Tài liệu đầy đủ: AWS SDK for JavaScript v3.

Node.js

Dùng AWS SDK for JavaScript v3. Phiên bản 2 (aws-sdk) đã hết hỗ trợ.

Cài đặt

npm install @aws-sdk/client-s3

Khởi tạo client

const { S3Client } = require('@aws-sdk/client-s3');

const s3 = new S3Client({
  region: 'YOUR_REGION',
  endpoint: 'YOUR_ENDPOINT',
  forcePathStyle: true,
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
  },
});

Ví dụ cơ bản

const {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  GetObjectCommand,
  DeleteObjectCommand,
  DeleteBucketCommand,
} = require('@aws-sdk/client-s3');

const s3 = new S3Client({
  region: 'YOUR_REGION',
  endpoint: 'YOUR_ENDPOINT',
  forcePathStyle: true,
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
  },
});

async function main() {
  const Bucket = 'my-unique-bucket-name';
  const Key = 'my-object-key';

  // Create a bucket
  await s3.send(new CreateBucketCommand({ Bucket }));

  // Upload an object
  await s3.send(new PutObjectCommand({ Bucket, Key, Body: 'Hello, world!' }));

  // Read an object
  const response = await s3.send(new GetObjectCommand({ Bucket, Key }));
  console.log('Object content:', await response.Body.transformToString());

  // Delete the object, then the empty bucket
  await s3.send(new DeleteObjectCommand({ Bucket, Key }));
  await s3.send(new DeleteBucketCommand({ Bucket }));
}

main().catch(console.error);

Tài liệu đầy đủ: AWS SDK for JavaScript v3.

Go

Dùng AWS SDK for Go v2. Phiên bản 1 (aws-sdk-go) đã hết hỗ trợ.

Cài đặt

go get github.com/aws/aws-sdk-go-v2/aws github.com/aws/aws-sdk-go-v2/credentials github.com/aws/aws-sdk-go-v2/service/s3

Khởi tạo client

client := s3.New(s3.Options{
    Region:       "YOUR_REGION",
    BaseEndpoint: aws.String("YOUR_ENDPOINT"),
    UsePathStyle: true,
    Credentials:  credentials.NewStaticCredentialsProvider("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", ""),
})

Ví dụ cơ bản

package main

import (
    "context"
    "io"
    "log"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    ctx := context.Background()
    client := s3.New(s3.Options{
        Region:       "YOUR_REGION",
        BaseEndpoint: aws.String("YOUR_ENDPOINT"),
        UsePathStyle: true,
        Credentials:  credentials.NewStaticCredentialsProvider("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", ""),
    })

    bucketName := "my-unique-bucket-name"
    objectKey := "my-object-key"

    // Create a bucket
    if _, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucketName)}); err != nil {
        log.Fatal(err)
    }

    // Upload an object
    if _, err := client.PutObject(ctx, &s3.PutObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectKey),
        Body:   strings.NewReader("Hello, world!"),
    }); err != nil {
        log.Fatal(err)
    }

    // Read an object
    out, err := client.GetObject(ctx, &s3.GetObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectKey),
    })
    if err != nil {
        log.Fatal(err)
    }
    data, err := io.ReadAll(out.Body)
    out.Body.Close()
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Object content:", string(data))

    // Delete the object, then the empty bucket
    if _, err := client.DeleteObject(ctx, &s3.DeleteObjectInput{
        Bucket: aws.String(bucketName),
        Key:    aws.String(objectKey),
    }); err != nil {
        log.Fatal(err)
    }
    if _, err := client.DeleteBucket(ctx, &s3.DeleteBucketInput{Bucket: aws.String(bucketName)}); err != nil {
        log.Fatal(err)
    }
}

Tài liệu đầy đủ: AWS SDK for Go v2.

Trước khi bắt đầu​

Python​

Java​

C#​

PHP​

JavaScript trên trình duyệt​

Node.js​

Go​

Trước khi bắt đầu

Python

Java

C#

PHP

JavaScript trên trình duyệt

Node.js

Go