Los SDK de OSS para Java, Python, Go, PHP, C# y Node.js conectan las aplicaciones con los buckets y permiten cargar, descargar y eliminar objetos. Utilice este inicio rápido para configurar un SDK y comprobar el acceso a OSS.
Requisitos previos
OSS debe estar activado y se debe haber creado un bucket. Para obtener más información, consulte Console Quick Start.
-
Debe contar con un par de AccessKey. Si no dispone de uno, consulte Create an AccessKey pair.
ImportantePara reducir el riesgo de exponer el par de AccessKey de su cuenta de Alibaba Cloud, utilice el par de AccessKey de un usuario de RAM. Siga el principio de privilegio mínimo y otorgue al usuario de RAM los permisos
oss:PutObject,oss:GetObjectyoss:DeleteObjectsobre el bucket de prueba.
Configurar las credenciales de acceso
El SDK lee el par de AccessKey desde las variables de entorno. No inserte el par de AccessKey directamente en el código.
macOS o 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 los parámetros del ejemplo
Antes de ejecutar el código, reemplace los siguientes parámetros por sus valores reales.
|
Parámetro |
Valor de ejemplo |
Descripción |
|
|
|
El ID de región del bucket. |
|
|
|
El nombre del bucket existente. |
|
|
|
El nombre completo del objeto de ejemplo. El código elimina este objeto antes de finalizar. |
Los SDK V2 de Java, Python, Go, PHP y C# utilizan el endpoint público predeterminado según el ID de región. Por lo tanto, no es necesario configurar explícitamente un endpoint en este ejemplo. Para el SDK de Node.js, anteponga oss- al ID de región. Si desea usar un endpoint interno, un endpoint de aceleración o un nombre de dominio personalizado, consulte Access OSS via Endpoints and Bucket Domains.
Debido a un cambio de directiva destinado a mejorar el cumplimiento y la seguridad, a partir del 20 de marzo de 2025, los nuevos usuarios de OSS deben use a custom domain name (CNAME) para realizar operaciones de API de datos en buckets de OSS ubicados en regiones de China continental. Los endpoints públicos predeterminados están restringidos para estas operaciones. Consulte el anuncio oficial para ver la lista completa de operaciones afectadas. Si accede a sus datos mediante HTTPS, debe bind a valid SSL Certificate a su dominio personalizado. Esto es obligatorio para el acceso a la consola de OSS, ya que la consola exige el uso de HTTPS.
Ejemplos de SDK
Seleccione su lenguaje de programación. Cada pestaña incluye el comando de instalación del SDK y el código completo para la inicialización del cliente, la carga, la verificación de descarga, la eliminación y la limpieza de recursos.
Java SDK V2
Agregue la siguiente dependencia al archivo pom.xml de su proyecto Maven. El ejemplo utiliza la versión 0.5.1.
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>alibabacloud-oss-v2</artifactId>
<version>0.5.1</version>
</dependency>
Código de ejemplo:
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 más configuraciones y ejemplos, consulte OSS Java SDK V2.
Python SDK V2
Instale el SDK. El ejemplo utiliza la versión 1.3.2.
python3 -m pip install alibabacloud-oss-v2
Código de ejemplo:
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 más configuraciones y ejemplos, consulte OSS Python SDK V2.
Go SDK V2
Instale la versión más reciente del SDK. El ejemplo utiliza la versión v1.5.3.
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2@latest
Código de ejemplo:
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 más configuraciones y ejemplos, consulte OSS Go SDK V2.
PHP SDK V2
Utilice Composer para instalar el SDK. El ejemplo utiliza la versión 0.4.0.
composer require alibabacloud/oss-v2
Código de ejemplo:
<?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 más configuraciones y ejemplos, consulte OSS PHP SDK V2.
C# SDK V2
Instale el SDK. El ejemplo utiliza la versión 0.2.0.
dotnet add package AlibabaCloud.OSS.V2
Código de ejemplo:
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 más configuraciones y ejemplos, consulte OSS C# SDK V2.
Node.js SDK
Instale el SDK. El ejemplo utiliza la versión 6.23.0.
npm install ali-oss
Código de ejemplo:
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 más configuraciones y ejemplos, consulte OSS Node.js SDK.
Consultar el resultado
Una ejecución exitosa devuelve la siguiente salida. Si ocurre un error después de la carga, el ejemplo intenta eliminar el objeto cargado para evitar un uso continuo del almacenamiento.
Object uploaded
Downloaded content: Hello OSS
Object deleted
Quick start completed