OSS Java SDK是一個Java庫，旨在與阿里雲Object Storage Service服務（OSS）整合，為Java應用程式提供高效的儲存管理和訪問功能。本文介紹如何通過OSS Java SDK完成建立儲存空間（Bucket）、上傳檔案、下載檔案、列舉檔案以及刪除檔案和Bucket等操作。
注意事項
關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。
本文以從環境變數讀取存取憑證為例。更多配置訪問憑證的樣本，請參見配置訪問憑證。
使用Java SDK發起OSS請求，您需要初始化一個OSSClient。本文通過預設配置樣本來建立一個OSSClient。更多配置用戶端的樣本，請參見配置用戶端。
前提條件
配置憑證
-
使用RAM使用者AccessKey配置環境變數。
LinuxmacOSWindows在命令列介面執行以下命令來將環境變數設定追加到
~/.bashrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc執行以下命令使變更生效。
source ~/.bashrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
在終端中執行以下命令，查看預設Shell類型。
echo $SHELL根據預設Shell類型進行操作。
ZshBash執行以下命令來將環境變數設定追加到
~/.zshrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc執行以下命令使變更生效。
source ~/.zshrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
執行以下命令來將環境變數設定追加到
~/.bash_profile檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile執行以下命令使變更生效。
source ~/.bash_profile執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
CMDPowerShell在CMD中運行以下命令。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"運行以下命令，檢查環境變數是否生效。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
在PowerShell中運行以下命令。
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)運行以下命令，檢查環境變數是否生效。
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
參考上述方式修改系統內容變數後，請重啟或重新整理您的編譯運行環境，包括IDE、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。
安裝SDK
已安裝Java 7 及以上版本。
通過以下命令查看Java版本。
java -version如果當前計算環境沒有Java或版本低於Java 7，請下載Java。
您可以通過以下三種方式安裝OSS Java SDK。
請根據需求選擇合適的OSS Java SDK版本，推薦您使用最新的3.17.4版本，確保本文中的程式碼範例可以正常運行。
在Maven專案中加入依賴項（推薦方式）在Eclipse專案中匯入JAR包在IntelliJ IDEA專案中匯入JAR包在Maven工程中使用OSS Java SDK，只需在
pom.xml中加入相應依賴即可。以在<dependencies>中加入3.17.4版本的依賴為例：<dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>3.17.4</version> </dependency>如果使用的是Java 9及以上的版本，則需要添加以下JAXB相關依賴。
<dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>2.3.1</version> </dependency> <dependency> <groupId>javax.activation</groupId> <artifactId>activation</artifactId> <version>1.1.1</version> </dependency> <!-- no more than 2.3.3--> <dependency> <groupId>org.glassfish.jaxb</groupId> <artifactId>jaxb-runtime</artifactId> <version>2.3.3</version> </dependency>以3.17.4版本為例，步驟如下：
下載Java SDK開發包。
解壓該開發包。
將解壓後檔案夾中的檔案aliyun-sdk-oss-3.17.4.jar以及lib檔案夾下的所有檔案拷貝到您的專案中。
在Eclipse中選擇您的工程，右鍵選擇。
選中拷貝的所有JAR檔案，匯入到Libraries中。
以3.17.4版本為例，步驟如下：
解壓該開發包。
將解壓後檔案夾中的檔案aliyun-sdk-oss-3.17.4.jar以及lib檔案夾下的所有JAR檔案拷貝到您的專案中。
在IntelliJ IDEA中選擇您的工程，右鍵選擇 。
選中拷貝的所有JAR檔案，匯入到External Libraries中。
運行樣本
運行以下程式碼範例以體驗OSS的完整使用流程：建立一個Bucket、上傳檔案、下載檔案、列舉檔案以及刪除檔案和Bucket。
import java.io.*;
import java.util.Random;
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.model.OSSObject;
import com.aliyun.oss.model.ObjectListing;
import com.aliyun.oss.model.OSSObjectSummary;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
public class OssJavaSdkQuickStart {
/** 產生一個唯一的 Bucket 名稱 */
public static String generateUniqueBucketName(String prefix) {
// 擷取目前時間戳
String timestamp = String.valueOf(System.currentTimeMillis());
// 產生一個 0 到 9999 之間的隨機數
Random random = new Random();
int randomNum = random.nextInt(10000); // 產生一個 0 到 9999 之間的隨機數
// 串連以形成一個唯一的 Bucket 名稱
return prefix + "-" + timestamp + "-" + randomNum;
}
public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
// 設定 OSS Endpoint 和 Bucket 名稱
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
String bucketName = generateUniqueBucketName("demo");
// 替換為您的 Bucket 地區
String region = "cn-hangzhou";
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請先配置環境變數
EnvironmentVariableCredentialsProvider credentialsProvider =
CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 建立 OSSClient 執行個體
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 顯式聲明使用 V4 簽名演算法
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.region(region)
.build();
try {
// 1. 建立儲存空間（Bucket）
ossClient.createBucket(bucketName);
System.out.println("1. Bucket " + bucketName + " 建立成功。");
// 2. 上傳檔案
String objectName = "exampledir/exampleobject.txt";
String content = "Hello OSS";
ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
System.out.println("2. 檔案 " + objectName + " 上傳成功。");
// 3. 下載檔案
OSSObject ossObject = ossClient.getObject(bucketName, objectName);
InputStream contentStream = ossObject.getObjectContent();
BufferedReader reader = new BufferedReader(new InputStreamReader(contentStream));
String line;
System.out.println("3. 下載的檔案內容：");
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
contentStream.close();
// 4. 列出檔案
System.out.println("4. 列出 Bucket 中的檔案：");
ObjectListing objectListing = ossClient.listObjects(bucketName);
for (OSSObjectSummary objectSummary : objectListing.getObjectSummaries()) {
System.out.println(" - " + objectSummary.getKey() + " (大小 = " + objectSummary.getSize() + ")");
}
// 5. 刪除檔案
ossClient.deleteObject(bucketName, objectName);
System.out.println("5. 檔案 " + objectName + " 刪除成功。");
// 6. 刪除儲存空間（Bucket）
ossClient.deleteBucket(bucketName);
System.out.println("6. Bucket " + bucketName + " 刪除成功。");
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException | IOException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}成功的返回樣本如下：
1. Bucket demo-1731651903982-4074 建立成功。
2. 檔案 exampledir/exampleobject.txt 上傳成功。
3. 下載的檔案內容：
Hello OSS
4. 列出 Bucket 中的檔案：
- exampledir/exampleobject.txt (大小 = 9)
5. 檔案 exampledir/exampleobject.txt 刪除成功。
6. Bucket demo-1731651903982-4074 刪除成功。
