Todos os produtos
Search
Central de documentação

Object Storage Service:SDK quick start

Última atualização: Aug 03, 2026

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

  1. O OSS deve estar ativado e um bucket crie. Para mais informações, consulte Console Quick Start.

  2. É necessário ter um par de AccessKey disponível. Caso não possua um par de AccessKey, consulte Create an AccessKey pair.

    Importante

    Para 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:GetObject e oss:DeleteObject no 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

region

<region-id>

ID da região onde o bucket está localizado.

bucket

example-bucket

Nome do bucket existente.

key

example.txt

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.

Importante

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

Mais SDKs