全部產品
Search
文件中心

Object Storage Service:配置訪問憑證(Harmony SDK)

更新時間:Nov 29, 2025

使用Harmony SDK發起OSS請求,您需要配置訪問憑證。阿里雲服務會通過訪問憑證驗證您的身份資訊和存取權限。您可以根據使用情境對認證和授權的要求,選擇不同類型的訪問憑證。

注意事項

常用配置樣本

使用STS臨時訪問憑證(推薦)

如果您的應用程式需要臨時訪問OSS,您可以使用通過STS服務擷取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token)初始化用戶端。

重要

以下範例程式碼展示了如何對訪問憑據直接進行寫入程式碼,顯式設定要使用的臨時存取金鑰。

import Client from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為STS臨時訪問憑證的Access Key ID, 非阿里雲帳號AccessKey ID和Access
  // 請注意區分STS服務擷取的Access Key ID是以STS開頭,如下所示
  accessKeyId: 'STS.****************',
  // 請替換為STS臨時訪問憑證的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 請替換為STS臨時訪問憑證的Security Token
  securityToken: 'yourSecurityToken',
  // 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

// 使用建立的OSS用戶端執行個體client發起OSS請求

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中,需要長期訪問您的OSS,且不能頻繁輪轉憑證時,您可以使用阿里雲主帳號或RAM使用者的AK(Access Key ID、Access Key Secret)初始化用戶端。

重要
  • 如需建立RAM使用者的AK,請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示,請及時儲存,如若遺忘請考慮建立新的AK進行輪換。

  • 阿里雲帳號擁有資源的全部許可權,AK一旦泄露,會給系統帶來巨大風險,不建議使用。推薦使用最小化授權的RAM使用者的AK。

以下範例程式碼展示了如何對訪問憑據直接進行寫入程式碼,顯式設定要使用的存取金鑰。

警告

請勿將RAM使用者的訪問憑據嵌入到生產環境的應用程式中,此方法僅用於測試目的。

import Client from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為RAM使用者的Access Key ID
  accessKeyId: 'yourAccessKeyID',
  // 請替換為RAM使用者的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

// 使用建立的OSS用戶端執行個體client發起OSS請求

常見問題

在使用通過STS服務擷取的臨時身份憑證去初始化憑證提供者時,誤使用RAM使用者的AK

當您使用通過STS服務擷取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token)初始化訪問憑證時,請勿混淆STS服務返回的AK與RAM使用者的AK,STS對應的AK是以STS開頭,樣本如下:

image

如何查看RAM使用者的AK?是否可以查看舊的AccessKey Secret?

  1. 如需查看RAM使用者的AK,請直接參考文檔查看RAM使用者的AccessKey資訊

  2. RAM使用者的AccessKey Secret僅在建立時顯示,之後無法查看,若您已經遺忘了的話無法找回。您可以直接存取RAM控制台選擇具體使用者,並建立新的AccessKey進行輪換。詳細請參見建立AccessKey

使用RAM使用者的AK進行上傳檔案時,報錯AccessDenied如何排查?

上傳檔案時出現AccessDenied的問題,通常是因為使用了錯誤的AK資訊或沒有給RAM使用者添加上傳檔案的許可權,您可以按照以下步驟檢查:

  1. 檢查您使用的RAM使用者的AK是否正確,請直接參考文檔查看RAM使用者的AccessKey資訊

  2. RAM使用者的AccessKey Secret僅在建立時顯示,之後無法查看,若您已經遺忘了的話無法找回。您可以直接存取RAM控制台選擇具體使用者,並建立新的AccessKey進行輪換。詳細請參見建立AccessKey

  3. 登入RAM控制台選擇具體使用者,給RAM使用者添加上傳檔案到OSS的許可權。

在使用外網Endpoint訪問OSS時,報錯無法串連該如何排查?

出現外網Endpoint無法串連的問題,通常是因為使用了錯誤的Endpoint地址或Bucket所在地區與請求的Endpoint不匹配。請您按照以下步驟檢查:

  1. 確認Bucket所在地區:登入阿里雲控制台,找到您的Bucket,確認其所在地區。

  2. 使用正確的Endpoint:根據Bucket所在地區,使用對應的外網Endpoint。例如,如果Bucket位於華東1(杭州),則應使用oss-cn-hangzhou.aliyuncs.com。各地區的Endpoint資訊請參見地區和Endpoint

  3. 檢查網路連接:確保您的網路環境可以正常訪問互連網,避免因網路問題導致串連失敗。

如果遇到報錯問題該如何查詢具體的錯誤類型?

關於錯誤類型的查詢,OSS文檔提供了EC錯誤碼供您參閱,例如關於認證方面的常見報錯問題,請參見02-AUTH