Os SDKs do OSS para Java, Python, Go, PHP, C# e Node.js conectam aplicações a buckets e permitem o upload, baixe e exclusão de objetos. Utilize este guia de início rápido para configure um SDK e verifique o acesso ao OSS.
Pré-requisitos
O OSS deve estar ativado e um bucket crie. Para mais informações, consulte Console Quick Start.
-
É necessário ter um par de AccessKey disponível. Caso não possua um par de AccessKey, consulte Create an AccessKey pair.
ImportantePara reduzir o risco de exposição do par de AccessKey da sua conta Alibaba Cloud, utilize o par de AccessKey de um usuário RAM. Siga o princípio do menor privilégio e conceda ao usuário RAM as permissões
oss:PutObject,oss:GetObjecteoss:DeleteObjectno bucket de teste.
Configure credenciais de acesso
O SDK lê o par de AccessKey a partir de variáveis de ambiente. Não codifique o par de AccessKey diretamente no seu código.
macOS ou Linux
export OSS_ACCESS_KEY_ID="yourAccessKeyId"
export OSS_ACCESS_KEY_SECRET="yourAccessKeySecret"
Windows PowerShell
$env:OSS_ACCESS_KEY_ID="yourAccessKeyId"
$env:OSS_ACCESS_KEY_SECRET="yourAccessKeySecret"
Preparar os parâmetros do exemplo
Antes de execute o código, substitua os parâmetros abaixo pelos seus valores reais.
|
Parâmetro |
Valor de exemplo |
Descrição |
|
|
|
ID da região onde o bucket está localizado. |
|
|
|
Nome do bucket existente. |
|
|
|
Nome completo do objeto de exemplo. O código exclua este objeto antes de finalizar a execução. |
Os SDKs V2 para Java, Python, Go, PHP e C# utilizam o endpoint público padrão com base no ID da região. Portanto, não é necessário configure explicitamente um endpoint neste exemplo. Para o SDK do Node.js, adicione o prefixo oss- ao ID da região. Para utilizar um endpoint interno, um endpoint de aceleração ou um nome de domínio personalizado, consulte Access OSS via Endpoints and Bucket Domains.
Devido a uma alteração de política visando melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do OSS devem use a custom domain name (CNAME) para realizar operações de API de dados em buckets do OSS localizados em regiões da China continental. Os endpoints públicos padrão estão restritos para essas operações. Consulte o anúncio oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via HTTPS, é obrigatório bind a valid SSL Certificate ao seu domínio personalizado. Isso é obrigatório para acesso ao OSS Console, pois o console impõe o uso de HTTPS.
Exemplos de SDK
Selecione sua linguagem de programação. Cada aba fornece o comando de instale do SDK e o código completo para inicialização do cliente, upload, verificação de baixe, exclua e limpeza de recursos.
Java SDK V2
Adicione a seguinte dependência ao arquivo pom.xml do seu projeto Maven. O exemplo utiliza a versão 0.5.1.
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>alibabacloud-oss-v2</artifactId>
<version>0.5.1</version>
</dependency>
Código de exemplo:
package com.example.oss;
import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.DeleteObjectRequest;
import com.aliyun.sdk.service.oss2.models.GetObjectRequest;
import com.aliyun.sdk.service.oss2.models.GetObjectResult;
import com.aliyun.sdk.service.oss2.models.PutObjectRequest;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import com.aliyun.sdk.service.oss2.utils.IOUtils;
import java.nio.charset.StandardCharsets;
public class QuickStart {
public static void main(String[] args) throws Exception {
String region = "<region-id>";
String bucket = "example-bucket";
String key = "example.txt";
String content = "Hello OSS";
try (OSSClient client = OSSClient.newBuilder()
.credentialsProvider(new EnvironmentVariableCredentialsProvider())
.region(region)
.build()) {
boolean uploaded = false;
try {
client.putObject(PutObjectRequest.newBuilder()
.bucket(bucket)
.key(key)
.body(BinaryData.fromString(content))
.build());
uploaded = true;
System.out.println("Object uploaded");
String downloaded;
try (GetObjectResult result = client.getObject(GetObjectRequest.newBuilder()
.bucket(bucket)
.key(key)
.build())) {
downloaded = new String(IOUtils.toByteArray(result.body()), StandardCharsets.UTF_8);
}
if (!content.equals(downloaded)) {
throw new IllegalStateException("Downloaded content does not match uploaded content");
}
System.out.println("Downloaded content: " + downloaded);
} finally {
if (uploaded) {
client.deleteObject(DeleteObjectRequest.newBuilder()
.bucket(bucket)
.key(key)
.build());
System.out.println("Object deleted");
}
}
}
System.out.println("Quick start completed");
}
}
Para mais configurações e exemplos, consulte OSS Java SDK V2.
Python SDK V2
Instale o SDK. O exemplo utiliza a versão 1.3.2.
python3 -m pip install alibabacloud-oss-v2
Código de exemplo:
import alibabacloud_oss_v2 as oss
def main():
region = "<region-id>"
bucket = "example-bucket"
key = "example.txt"
content = "Hello OSS"
config = oss.config.load_default()
config.credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
config.region = region
client = oss.Client(config)
uploaded = False
try:
client.put_object(oss.PutObjectRequest(
bucket=bucket,
key=key,
body=content.encode("utf-8"),
))
uploaded = True
print("Object uploaded")
result = client.get_object(oss.GetObjectRequest(bucket=bucket, key=key))
with result.body as body_stream:
downloaded = body_stream.read().decode("utf-8")
if downloaded != content:
raise RuntimeError("Downloaded content does not match uploaded content")
print(f"Downloaded content: {downloaded}")
finally:
if uploaded:
client.delete_object(oss.DeleteObjectRequest(bucket=bucket, key=key))
print("Object deleted")
print("Quick start completed")
if __name__ == "__main__":
main()
Para mais configurações e exemplos, consulte OSS Python SDK V2.
Go SDK V2
Instale a versão mais recente do SDK. O exemplo utiliza a versão v1.5.3.
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2@latest
Código de exemplo:
package main
import (
"context"
"fmt"
"io"
"log"
"strings"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
func run() (err error) {
region := "<region-id>"
bucket := "example-bucket"
key := "example.txt"
content := "Hello OSS"
ctx := context.Background()
config := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion(region)
client := oss.NewClient(config)
uploaded := false
defer func() {
if !uploaded {
return
}
_, deleteErr := client.DeleteObject(ctx, &oss.DeleteObjectRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
})
if deleteErr != nil {
if err == nil {
err = fmt.Errorf("delete object: %w", deleteErr)
}
return
}
fmt.Println("Object deleted")
}()
_, err = client.PutObject(ctx, &oss.PutObjectRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
Body: strings.NewReader(content),
})
if err != nil {
return fmt.Errorf("upload object: %w", err)
}
uploaded = true
fmt.Println("Object uploaded")
result, err := client.GetObject(ctx, &oss.GetObjectRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
})
if err != nil {
return fmt.Errorf("download object: %w", err)
}
defer result.Body.Close()
data, err := io.ReadAll(result.Body)
if err != nil {
return fmt.Errorf("read downloaded object: %w", err)
}
downloaded := string(data)
if downloaded != content {
return fmt.Errorf("downloaded content does not match uploaded content")
}
fmt.Printf("Downloaded content: %s\n", downloaded)
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
fmt.Println("Quick start completed")
}
Para mais configurações e exemplos, consulte OSS Go SDK V2.
PHP SDK V2
Utilize o Composer para instale o SDK. O exemplo utiliza a versão 0.4.0.
composer require alibabacloud/oss-v2
Código de exemplo:
<?php
require_once __DIR__ . '/vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
$region = '<region-id>';
$bucket = 'example-bucket';
$key = 'example.txt';
$content = 'Hello OSS';
$config = Oss\Config::loadDefault();
$config->setCredentialsProvider(new Oss\Credentials\EnvironmentVariableCredentialsProvider());
$config->setRegion($region);
$client = new Oss\Client($config);
$uploaded = false;
try {
$putRequest = new Oss\Models\PutObjectRequest($bucket, $key);
$putRequest->body = Oss\Utils::streamFor($content);
$client->putObject($putRequest);
$uploaded = true;
echo 'Object uploaded' . PHP_EOL;
$result = $client->getObject(new Oss\Models\GetObjectRequest($bucket, $key));
$downloaded = $result->body->getContents();
if ($downloaded !== $content) {
throw new RuntimeException('Downloaded content does not match uploaded content');
}
echo 'Downloaded content: ' . $downloaded . PHP_EOL;
} finally {
if ($uploaded) {
$client->deleteObject(new Oss\Models\DeleteObjectRequest($bucket, $key));
echo 'Object deleted' . PHP_EOL;
}
}
echo 'Quick start completed' . PHP_EOL;
Para mais configurações e exemplos, consulte OSS PHP SDK V2.
C# SDK V2
Instale o SDK. O exemplo utiliza a versão 0.2.0.
dotnet add package AlibabaCloud.OSS.V2
Código de exemplo:
using System.Text;
using OSS = AlibabaCloud.OSS.V2;
var region = "<region-id>";
var bucket = "example-bucket";
var key = "example.txt";
var content = "Hello OSS";
var config = OSS.Configuration.LoadDefault();
config.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
config.Region = region;
using var client = new OSS.Client(config);
var uploaded = false;
try
{
await client.PutObjectAsync(new OSS.Models.PutObjectRequest
{
Bucket = bucket,
Key = key,
Body = new MemoryStream(Encoding.UTF8.GetBytes(content))
});
uploaded = true;
Console.WriteLine("Object uploaded");
var result = await client.GetObjectAsync(new OSS.Models.GetObjectRequest
{
Bucket = bucket,
Key = key
});
using var body = result.Body ?? throw new InvalidOperationException("The response body is empty");
using var reader = new StreamReader(body, Encoding.UTF8);
var downloaded = await reader.ReadToEndAsync();
if (downloaded != content)
{
throw new InvalidOperationException("Downloaded content does not match uploaded content");
}
Console.WriteLine($"Downloaded content: {downloaded}");
}
finally
{
if (uploaded)
{
await client.DeleteObjectAsync(new OSS.Models.DeleteObjectRequest
{
Bucket = bucket,
Key = key
});
Console.WriteLine("Object deleted");
}
}
Console.WriteLine("Quick start completed");
Para mais configurações e exemplos, consulte OSS C# SDK V2.
Node.js SDK
Instale o SDK. O exemplo utiliza a versão 6.23.0.
npm install ali-oss
Código de exemplo:
const OSS = require('ali-oss');
const region = 'oss-<region-id>';
const bucket = 'example-bucket';
const key = 'example.txt';
const content = 'Hello OSS';
const client = new OSS({
region,
bucket,
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
authorizationV4: true,
});
async function main() {
let uploaded = false;
try {
await client.put(key, Buffer.from(content, 'utf8'));
uploaded = true;
console.log('Object uploaded');
const result = await client.get(key);
const downloaded = result.content.toString('utf8');
if (downloaded !== content) {
throw new Error('Downloaded content does not match uploaded content');
}
console.log(`Downloaded content: ${downloaded}`);
} finally {
if (uploaded) {
await client.delete(key);
console.log('Object deleted');
}
}
console.log('Quick start completed');
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
Para mais configurações e exemplos, consulte OSS Node.js SDK.
Visualize o resultado
Uma execução bem-sucedida retorna a saída abaixo. Se ocorrer um erro após o upload, o exemplo ainda tentará exclua o objeto enviado para evitar consumo contínuo de armazenamento.
Object uploaded
Downloaded content: Hello OSS
Object deleted
Quick start completed