Object Storage Service：OSS C# SDK V2

快速接入

接入OSS C# SDK V2的流程如下：

環境準備

• 適用於.NET Framework 471及以上版本。

• 適用於.NET Standard 2.0及以上版本。

• 適用於.NET5.0及以上版本。

• 如果當前計算環境中不存在所需 .NET 環境或版本過低，請參考以下步驟：

  • 對於.NET Framework：請訪問Microsoft 官網下載並安裝.NET Framework 4.7.1 或更高版本。

  • 對於.NET Standard：通常 .NET Standard 是由其他.NET實現（如 .NET Framework 或 .NET）支援的，確保您已安裝相應的.NET實現即可。

  • 對於.NET：請訪問.NET 官網下載並安裝.NET 5.0或更高版本。

安裝SDK

推薦您使用最新的OSS C# SDK V2版本，確保本文中的程式碼範例可以正常運行。

配置訪問憑證

使用 RAM 使用者的 AccessKey 配置訪問憑證。

1. 在 RAM 控制台，建立使用永久 AccessKey 訪問的 RAM 使用者，儲存 AccessKey，然後為該使用者授予 AliyunOSSFullAccess 許可權。

2. 使用 RAM 使用者 AccessKey 配置環境變數。

   Linux

   1. 在命令列介面執行以下命令來將環境變數設定追加到~/.bashrc 檔案中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. 執行以下命令使變更生效。

         source ~/.bashrc

      2. 執行以下命令檢查環境變數是否生效。

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. 在終端中執行以下命令，查看預設Shell類型。

      echo $SHELL

      1. 根據預設Shell類型進行操作。

         Zsh

         1. 執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

         2. 執行以下命令使變更生效。

            source ~/.zshrc

         3. 執行以下命令檢查環境變數是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

         Bash

         1. 執行以下命令來將環境變數設定追加到 ~/.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

         2. 執行以下命令使變更生效。

            source ~/.bash_profile

         3. 執行以下命令檢查環境變數是否生效。

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. 在CMD中運行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. 運行以下命令，檢查環境變數是否生效。

         echo %OSS_ACCESS_KEY_ID%
         echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. 在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)

      1. 運行以下命令，檢查環境變數是否生效。

         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

初始化用戶端

使用地區和訪問網域名稱初始化 OSSClient，並運行測試代碼。

using System.Text; // 引入System.Text命名空間，用於處理字元編碼（如UTF-8編碼字串）
using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou"; // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var bucket = "your bucket name";  // 必須項，設定目標Bucket名稱
var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
var key = "your object key"; // 必須項，指定上傳的對象名稱。格式（folder/objectName）

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if(endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 待上傳的對象內容。樣本內容：簡單字串"hello oss!"，實際情境中可為檔案流、位元組數組等
var content = "hello oss!";
// 將字串轉換為UTF-8編碼的位元組數組，再封裝為MemoryStream
// MemoryStream用於在記憶體中處理資料流，適合小檔案上傳；大檔案建議使用FileStream
var bodyStream = new MemoryStream(Encoding.UTF8.GetBytes(content));

// 調用PutObjectAsync方法非同步上傳對象（需傳入包含Bucket、Key和Body的請求對象）
// 該方法會將bodyStream中的資料上傳至指定Bucket的Key路徑下
var result = await client.PutObjectAsync(new OSS.Models.PutObjectRequest()
{
    Bucket = bucket,    // 目標Bucket名稱
    Key = key,          // 對象在Bucket中的唯一Key 
    Body = bodyStream   // 要上傳的內容流（此處為記憶體中的字串資料）
});

// 列印上傳結果
Console.WriteLine("PutObject done");  // 提示操作完成
Console.WriteLine($"StatusCode: {result.StatusCode}");  // HTTP狀態代碼
Console.WriteLine($"RequestId: {result.RequestId}");  // RequestId，用於阿里雲排查問題
Console.WriteLine("Response Headers:");  // 回應標頭資訊
result.Headers.ToList().ForEach(x => Console.WriteLine(x.Key + " : " + x.Value));  // 遍曆並列印所有回應標頭

運行後將會輸出上傳檔案成功的結果：

PutObject done
StatusCode: 200
RequestId: 68808D6D6A91E53037F7AAE9
Response Headers:
Server : AliyunOSS
Date : Wed, 23 Jul 2025 07:21:17 GMT
Connection : keep-alive
x-oss-request-id : 68808D6D6A91E53037F7AAE9
Vary : Origin
ETag : "968205D07B5A124D6ADA9336826C2C90"
x-oss-hash-crc64ecma : 11833582957755287462
x-oss-version-id : CAEQpgEYgYCA3fPQ2MEZIiA2ZmI4NGZkZWQzMWY0ZDZkOTFmMjUxYzRkNGMxODdkZg--
x-oss-server-time : 90
Content-Length : 0
Content-MD5 : loIF0HtaEk1q2pM2gmwskA==

用戶端配置

使用自訂網域名

使用OSS預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過通過自訂網域名訪問OSS，不僅支援瀏覽器直接預覽檔案，還可結合CDN加速分發。

using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou"; // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = "https://www.example-***.com";  // 必須項，請填寫您的自訂網域名。例如www.example-***.com

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 請注意，設定true開啟CNAME選項，否則無法使用自訂網域名
cfg.UseCName = true;

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 使用建立好的client執行後續操作...

使用內網網域名稱

使用內網網域名稱訪問同地區的OSS資源，可以降低流量成本並提高訪問速度。

using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou"; // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = "https://oss-cn-hangzhou-internal.aliyuncs.com";  // 可選項，指定訪問OSS服務的內網網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou-internal.aliyuncs.com

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 您也可以無需指定內網endpoint，直接設定cfg.UseInternalEndpoint = true配置內網網域名稱
// cfg.UseInternalEndpoint = true;

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 使用建立好的client執行後續操作...

使用傳輸加速網域名稱

using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou"; // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = "https://oss-accelerate.aliyuncs.com";  // 可選項，填寫Bucket所在地區對應的傳輸加速Endpoint。以華東1（杭州）為例，Endpoint填寫為'https://oss-accelerate.aliyuncs.com'

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 您也可以無需指定傳輸加速endpoint，直接設定cfg.UseAccelerateEndpoint = true配置傳輸加速網域名稱
// cfg.UseAccelerateEndpoint = true;

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 使用建立好的client執行後續操作...	

使用專有域

using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou"; // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = "https://service.corp.example.com";  // 必須項，請填寫您的專有域。例如：https://service.corp.example.com

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 使用建立好的client執行後續操作...	

使用政務雲網域名稱

以下是使用政務雲網域名稱配置OSSClient的範例程式碼。

using OSS = AlibabaCloud.OSS.V2; // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-north-2-gov-1"; // 必須項，設定Bucket所在的地區（Region）。以華北2 阿里政務雲1為例，Region填寫為cn-north-2-gov-1
// 必須項，填寫Bucket所在地區對應的內網Endpoint。以華北2 阿里政務雲1為例，Endpoint填寫為'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
// 如需指定為http協議，請在指定網域名稱時填寫為'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'
var endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com";

// 載入OSS SDK的預設配置，此配置會自動從環境變數中讀取憑證資訊（如AccessKey）
var cfg = OSS.Configuration.LoadDefault();
// 顯式設定使用環境變數擷取憑證，用於身分識別驗證（格式：OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET）
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
// 設定配置的Bucket地區
cfg.Region = region;
// 若已指定了endpoint，則覆蓋預設的endpoint
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 使用建立好的client執行後續操作...	

訪問憑證配置

OSS 提供多種憑證初始化方式。請根據您的認證和授權需求選擇合適的初始化方式。

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。

using OSS = AlibabaCloud.OSS.V2;  // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou";  // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com

var cfg = OSS.Configuration.LoadDefault();

// 填寫RAM帳號AccessKey ID和AccessKey Secret。
var access_key_id = "yourAccessKeyId";
var access_key_secret = "yourAccessKeySecret";
// 建立靜態憑證提供者，顯式設定RAM帳號密鑰AccessKey ID和AccessKey Secret
cfg.CredentialsProvider = new OSS.Credentials.StaticCredentialsProvider(access_key_id,access_key_secret);

// 設定配置的Bucket地區
cfg.Region = region;   
// 若已指定了endpoint，則覆蓋預設的endpoint 
if(endpoint != null) 
{
    cfg.Endpoint = endpoint;
} 

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

使用STS臨時訪問憑證

如果您的應用程式需要臨時訪問OSS，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問OSS，您需要手動重新整理STS Token。

using OSS = AlibabaCloud.OSS.V2;  // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou";  // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com

var cfg = OSS.Configuration.LoadDefault();

// 填寫擷取的臨時存取金鑰AccessKey ID和AccessKey Secret，非阿里雲帳號AccessKey ID和AccessKey Secret。
// 請注意區分STS服務擷取的Access Key ID是以STS開頭，如下所示。
var access_key_id = "STS.****************";
var access_key_secret = "yourAccessKeySecret";
// 填寫擷取的STS安全性權杖（SecurityToken）。
var securityToken = "yourSecurityToken";
// 建立靜態憑證提供者，顯式設定臨時存取金鑰AccessKey ID和AccessKey Secret，以及STS安全性權杖
cfg.CredentialsProvider = new OSS.Credentials.StaticCredentialsProvide(access_key_id, access_key_secret, securityToken);

// 設定配置的Bucket地區
cfg.Region = region;   
// 若已指定了endpoint，則覆蓋預設的endpoint 
if(endpoint != null) 
{
    cfg.Endpoint = endpoint;
} 

// 使用配置資訊建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

使用RAMRoleARN

如果您的應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

1. 添加Aliyun.Credentials依賴。

   dotnet add package Aliyun.Credentials --source https://api.nuget.org/v3/index.json

2. 配置AK和RAMRoleARN作為訪問憑證。

   using OSS = AlibabaCloud.OSS.V2;  // 為阿里雲OSS SDK建立別名，簡化後續使用
   
   var region = "cn-hangzhou";  // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
   var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
   
   // 阿里雲憑證配置 - 使用RAM角色ARN方式
   // 更多憑證類型樣本參考：https://github.com/aliyun/credentials-csharp
   var credConfig = new Aliyun.Credentials.Models.Config()
   {
       // 指定憑證類型為RAM角色ARN
       Type = "ram_role_arn",
       // 從環境變數讀取AccessKeyId
       AccessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID"),
       // 從環境變數讀取AccessKeySecret
       AccessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET"),
       // RAM角色ARN，格式：acs:ram::USER_Id:role/ROLE_NAME
       // 也可通過環境變數ALIBABA_CLOUD_ROLE_ARN設定
       RoleArn = "acs:ram::***************:role/******",
       // 角色會話名稱，用於標識當前會話
       RoleSessionName = "<RoleSessionName>",
       // 選擇性參數，限制STS令牌的許可權範圍
       Policy = "<Policy>",
       // 選擇性參數，設定STS令牌的有效期間（秒）
       RoleSessionExpiration = 3600,
   };
   
   // 建立憑證用戶端執行個體，用於擷取臨時訪問憑證
   var credClient = new Aliyun.Credentials.Client(credConfig);
   
   // 將通用憑證轉換為OSS SDK所需的憑證提供器
   var credentialsProvider = new OSS.Credentials.CredentialsProvideFunc(() =>
   {
       // 擷取臨時憑證
       var credential = credClient.GetCredential();
   
       // 構造OSS SDK所需的憑證對象
       return new OSS.Credentials.Credentials(
           credential.AccessKeyId,      // 臨時AccessKey ID
           credential.AccessKeySecret,  // 臨時AccessKey Secret
           credential.SecurityToken);   // 安全性權杖（STS Token）
   });
   
   // 載入OSS SDK的預設配置
   // 預設從環境變數中載入憑證資訊（此處已被自訂憑證覆蓋）
   var cfg = OSS.Configuration.LoadDefault();
   // 設定OSS地區
   cfg.Region = region;
   // 設定自訂憑證提供器
   cfg.CredentialsProvider = credentialsProvider;
   
   // 如果指定了自訂endpoint，則覆蓋預設設定
   if (endpoint != null)
   {
       cfg.Endpoint = endpoint;
   }
   
   // 使用配置建立OSS用戶端執行個體
   using var client = new OSS.Client(cfg);
   
   // 建立ListBuckets操作的分頁器
   // 用於擷取當前帳號下的所有OSS儲存桶
   var paginator = client.ListBucketsPaginator(new OSS.Models.ListBucketsRequest());
   
   // 非同步迭代儲存桶分頁結果
   Console.WriteLine("Buckets:");
   await foreach (var page in paginator.IterPageAsync())
   {
       // 遍曆每個頁面中的儲存桶
       foreach (var bucket in page.Buckets ?? [])
       {
           // 輸出儲存桶資訊：名稱、儲存類型和位置
           Console.WriteLine($"Bucket:{bucket.Name}, {bucket.StorageClass}, {bucket.Location}");
       }
   }
   

使用ECSRAMRole

如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

1. 添加Aliyun.Credentials依賴。

   dotnet add package Aliyun.Credentials --source https://api.nuget.org/v3/index.json

2. 配置ECSRAMRole作為訪問憑證。

   using OSS = AlibabaCloud.OSS.V2;  // 為阿里雲OSS SDK建立別名，簡化後續使用
   using Aliyun.Credentials.Models;
   
   var region = "cn-hangzhou";  // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
   var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
   
   // 建立憑證配置，使用ECS RAM角色方式認證
   var credConfig = new Aliyun.Credentials.Models.Config()
   {
       // 憑證類型
       Type = "ecs_ram_role",
       // 賬戶RoleName，非必填，不填則自動擷取，建議設定，可以減少請求up to reduce requests
       RoleName = "<RoleName>"
   };
   
   // 建立憑證用戶端，用於擷取臨時訪問憑證
   var credClient = new Aliyun.Credentials.Client(credConfig);
   
   // 將通用憑證轉換為OSS SDK所需的憑證提供器
   var credentialsProvider = new OSS.Credentials.CredentialsProviderFunc(() =>
   {
       // 擷取臨時憑證
       var credential = credClient.GetCredential();
   
       // 構造OSS SDK所需的憑證對象
       return new OSS.Credentials.Credentials(
           credential.AccessKeyId,      // 臨時AccessKey ID
           credential.AccessKeySecret,  // 臨時AccessKey Secret
           credential.SecurityToken);   // 安全性權杖（STS Token）
   });
   
   // 載入OSS用戶端的預設配置
   var cfg = OSS.Configuration.LoadDefault();
   
   // 設定OSS地區
   cfg.Region = region;
   
   // 設定自訂憑證提供器
   cfg.CredentialsProvider = credentialsProvider;
   
   // 如果指定了自訂endpoint，則覆蓋預設設定
   if (endpoint != null)
   {
       cfg.Endpoint = endpoint;
   }
   
   // 使用配置建立OSS用戶端執行個體
   using var client = new OSS.Client(cfg);
   
   // 用於擷取當前角色帳號下的所有OSS儲存桶
   var paginator = client.ListBucketsPaginator(new OSS.Models.ListBucketsRequest());
   
   // 非同步迭代儲存桶分頁結果
   Console.WriteLine("Buckets:");
   await foreach (var page in paginator.IterPageAsync())
   {
       // 遍曆每個頁面中的儲存桶
       foreach (var bucket in page.Buckets ?? [])
       {
           // 輸出儲存桶資訊：名稱、儲存類型和位置
           Console.WriteLine($"Bucket:{bucket.Name}, {bucket.StorageClass}, {bucket.Location}");
       }
   }

使用OIDCRoleARN

在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見基於RRSA的Pod許可權隔離。

使用自訂訪問憑證

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。

通過Credentials.CredentialsProvideFunc介面

using OSS = AlibabaCloud.OSS.V2;  // 為阿里雲OSS SDK建立別名，簡化後續使用

var region = "cn-hangzhou";  // 必須項，設定Bucket所在的地區（Region）。以華東1（杭州）為例，Region填寫為cn-hangzhou
var endpoint = null as string;  // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com

// 顯式設定訪問憑證，僅作示範用例。實際專案中您可以通過擷取環境變數方式擷取
var AccessKeyId = "your AccessKeyId";  // 必須項，RAM使用者或STS臨時訪問憑證AccessKeyId
var AccessKeySecret = "your AccessKeySecret";  // 必須項，RAM使用者或STS臨時訪問憑證AccessKeySecret
// var SecurityToken = "your STS Token";  // 可選項，使用臨時訪問憑證可配置此變數

// 將通用憑證轉換為OSS SDK所需的憑證提供器
var credentialsProvider = new OSS.Credentials.CredentialsProvideFunc(() =>
{
   
    // 使用長期憑證構造OSS SDK所需的憑證對象 
    return new OSS.Credentials.Credentials(
        AccessKeyId,        // RAM使用者AccessKey ID
        AccessKeySecret);   // RAM使用者AccessKey Secret

    // 使用臨時訪問憑證構造OSS SDK所需的憑證對象 
    // return new OSS.Credentials.Credentials(
    //     AccessKeyId,      // 臨時AccessKey ID
    //     AccessKeySecret,  // 臨時AccessKey Secret
    //     SecurityToken);   // 安全性權杖（STS Token）
});

// 載入OSS用戶端的預設配置
var cfg = OSS.Configuration.LoadDefault();

// 設定OSS地區
cfg.Region = region;

// 設定自訂憑證提供器
cfg.CredentialsProvider = credentialsProvider;

// 如果指定了自訂endpoint，則覆蓋預設設定
if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

// 使用配置建立OSS用戶端執行個體
using var client = new OSS.Client(cfg);

// 用於擷取當前角色帳號下的所有OSS儲存桶
var paginator = client.ListBucketsPaginator(new OSS.Models.ListBucketsRequest());

// 非同步迭代儲存桶分頁結果
Console.WriteLine("Buckets:");
await foreach (var page in paginator.IterPageAsync())
{
    // 遍曆每個頁面中的儲存桶
    foreach (var bucket in page.Buckets ?? [])
    {
        // 輸出儲存桶資訊：名稱、儲存類型和位置
        Console.WriteLine($"Bucket:{bucket.Name}, {bucket.StorageClass}, {bucket.Location}");
    }
}

範例程式碼

OSS C# SDK V2提供豐富的範例程式碼供參考或直接使用。