Os SDKs do OSS para Java, Python, Go, PHP, C# e Node.js conectam aplicativos a buckets e oferecem suporte a upload, download e exclusão de objetos. Use este início rápido para configurar um SDK e verificar o acesso ao OSS.
Pré-requisitos
-
O OSS está ativado e um bucket foi criado. Para mais informações, consulte Início rápido pelo console.
-
Um par de AccessKey está disponível. Se você não possui um par de AccessKey, consulte Criar um par de AccessKey.
ImportantePara reduzir o risco de expor o par de AccessKey da sua conta Alibaba Cloud, use 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.
Configurar credenciais de acesso
O SDK lê o par de AccessKey das variáveis de ambiente. Não codifique o par de AccessKey diretamente no 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 executar o código, substitua os parâmetros a seguir pelos seus valores reais.
|
Parâmetro |
Valor de exemplo |
Descrição |
region |
<region-id> |
O ID da região do bucket. |
bucket |
example-bucket |
O nome do bucket existente. |
key |
example.txt |
O nome completo do objeto de exemplo. O código exclui este objeto antes de encerrar. |
Os SDKs V2 para Java, Python, Go, PHP e C# usam o endpoint público padrão com base no ID da região. Portanto, não é necessário configurar explicitamente um endpoint neste exemplo. Para o SDK do Node.js, adicione o prefixo oss- ao ID da região. Para usar um endpoint interno, um endpoint de aceleração ou um nome de domínio personalizado, consulte Acessar o OSS por endpoints e domínios de bucket.
Devido a uma alteração de política para melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do OSS devem usar um nome de domínio personalizado (CNAME) para realizar operações de API de dados em buckets do OSS localizados nas 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, deverá vincular um certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao Console do OSS, pois o console impõe HTTPS.
Exemplos de SDK
Selecione sua linguagem de programação. Cada aba fornece o comando de instalação do SDK e o código completo para inicialização do cliente, upload, verificação de download, exclusão e limpeza de recursos.
Java SDK V2
Adicione a seguinte dependência ao arquivo pom.xml do seu projeto Maven. O exemplo usa 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 usa a versão 1.3.2.
python3 -m pip install alibabacloud-oss-v2Có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 usa a versão v1.5.3.
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2@latestCó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
Use o Composer para instalar o SDK. O exemplo usa a versão 0.4.0.
composer require alibabacloud/oss-v2Có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 usa a versão 0.2.0.
dotnet add package AlibabaCloud.OSS.V2Có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 usa a versão 6.23.0.
npm install ali-ossCó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.
Visualizar o resultado
Uma execução bem-sucedida retorna a saída a seguir. Se ocorrer um erro após o upload, o exemplo ainda tenta excluir o objeto enviado para evitar uso contínuo de armazenamento.
Object uploaded
Downloaded content: Hello OSS
Object deleted
Quick start completed