使用多種方式為OSS Swift SDK配置訪問憑證-Object Storage Service-阿里雲

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

注意事項

如果您希望擷取關於OSS支援的Region與Endpoint的對應關係，請參見地區和Endpoint。
如果您希望建立RAM使用者的AccessKey，請參見建立AccessKey。

憑證提供者選型

OSS支援多種方式初始化憑證提供者，您可以根據使用情境對認證和授權的要求，選擇對應的方式初始化憑證提供者。

憑證提供者初始化方式	適用情境	是否需要提供前置的AK或STS Token	底層實現基於的憑證	憑證有效期間	憑證輪轉或重新整理方式
使用RAM使用者的AK	部署運行在安全、穩定且不易受外部攻擊的環境的應用程式，無需頻繁輪轉憑證就可以長期訪問雲端服務	是	AK	長期	手動輪轉
使用STS臨時訪問憑證	部署運行在不可信的環境的應用程式，希望能控制訪問的有效期間、許可權	是	STS Token	臨時	手動重新整理
自訂憑證提供者	如果以上憑證配置方式都不滿足要求時，您可以自訂擷取憑證的方式	自訂	自訂	自訂	自訂

常用配置樣本

使用RAM使用者的AK

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

警告

阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。
如需建立RAM使用者的AK，請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示，請及時儲存，如若遺忘請考慮建立新的AK進行輪換。

環境變數

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

Linux

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

macOS

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

echo $SHELL

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

Zsh

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

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

Windows

CMD

在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

在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、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。

使用環境變數來傳遞憑證資訊。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        let credentialsProvider = EnvironmentCredentialsProvider()

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

靜態憑證

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

警告

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

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 填寫RAM使用者的Access Key ID和Access Key Secret
        let accessKeyId = "yourAccessKeyID"
        let accessKeySecret = "yourAccessKeySecret"
        
        // 使用StaticCredentialsProvider方法直接設定accessKeyId和accessKeySecret
        let credentialsProvider = StaticCredentialsProvider(accessKeyId: accessKeyId,
                                                            accessKeySecret: accessKeySecret)

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

使用STS臨時訪問憑證

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

重要

如果您希望通過OpenAPI的方式簡單快速擷取到STS臨時訪問憑證，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。
如果您希望通過SDK的方式擷取STS臨時訪問憑證，請參見使用STS臨時訪問憑證訪問OSS。
請注意，STS Token在產生的時候需要指定到期時間，到期後自動失效不能再使用。
如果您希望擷取關於STS服務的存取點列表，請參見服務存取點。

環境變數

使用臨時身份憑證設定環境變數。
Mac OS X/Linux/Unix
警告
請注意，此處使用的是通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token），而非RAM使用者的Access Key和Access Key Secret。
請注意區分STS服務擷取的Access Key ID以STS開頭，例如“STS.****************”。
```
export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
```
Windows
警告
請注意，此處使用的是通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token），而非RAM使用者的AK（Access Key ID、Access Key Secret）。
請注意區分STS服務擷取的Access Key ID以STS開頭，例如“STS.L4aBSCSJVMuKg5U1****”。
```
set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
```

通過環境變數來傳遞憑證資訊。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        let credentialsProvider = EnvironmentCredentialsProvider()

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

靜態憑證

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

警告

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

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 填寫擷取的臨時存取金鑰AccessKey ID和AccessKey Secret，非阿里雲帳號AccessKey ID和AccessKey Secret。
        // 請注意區分STS服務擷取的Access Key ID是以STS開頭，如下所示。
        let accessKeyId = "yourAccessKeyID"
        let accessKeySecret = "yourAccessKeySecret"
        let securityToken = "yourSecurityToken"
        
        // 使用StaticCredentialsProvider方法直接設定accessKeyId、accessKeySecret和securityToken。
        let credentialsProvider = StaticCredentialsProvider(accessKeyId: accessKeyId,
                                                            accessKeySecret: accessKeySecret,
                                                            securityToken: securityToken)

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

更多情境化配置樣本

自訂憑證提供者

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。SDK 支援多種實現方式。

通過ClosureCredentialsProvider介面

您可以通過實現ClosureCredentialsProvider介面的方式，來自訂憑證的擷取方式。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil
        
        // 方式1：擷取長期訪問憑證
        let credentialsProvider = ClosureCredentialsProvider {
            // TODO
            // 您可以自訂長期訪問憑證的擷取方法...
            
            // 假設擷取得到的值如下
            let accessKeyId = "yourAccessKeyID"
            let accessKeySecret = "yourAccessKeySecret"
            
            // 返回長期訪問憑證
            return Credentials(accessKeyId: accessKeyId,
                        accessKeySecret: accessKeySecret)
        }
        
        // 方式2：擷取臨時憑證
        // let credentialsProvider = ClosureCredentialsProvider {
             // TODO
            // 您可以自訂臨時訪問憑證的擷取方法...
        
            // 假設擷取得到的值如下
            // let accessKeyId = "yourAccessKeyID"
            // let accessKeySecret = "yourAccessKeySecret"
            // let securityToken = "yourSecurityToken"
            
        // 返回臨時訪問憑證
        //  return Credentials(accessKeyId: accessKeyId,
        //               accessKeySecret: accessKeySecret,
        //                securityToken: securityToken)
        // }

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

通過RefreshCredentialsProvider介面

您可以通過RefreshCredentialsProvider介面來自訂訪問憑證的擷取和自動重新整理邏輯。該機制支援兩種模式：

不自動重新整理訪問憑證：不在憑證閉包函數中設定到期時間（expiration），此時將不會自動重新整理訪問憑證。
自動重新整理訪問憑證：在閉包函數中設定一個到期時間（expiration），此時RefreshCredentialsProvider介面將會結合refreshInterval重新整理時間和到期時間，定期調用閉包函數以更新訪問憑證。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填寫Bucket所在地區（樣本：華東1為cn-hangzhou）
        let region = "cn-hangzhou"
        // 可選項，指定訪問OSS服務的網域名稱。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 自動重新整理的訪問憑證，根據到期時間重新整理訪問憑證
        // refreshInterval：重新整理時間，預設300s。
        let credentialsProvider = RefreshCredentialsProvider(refreshInterval: 500) {
        
            // 您可以在此處自訂擷取臨時憑證的方法

            // TODO......

            // 假設擷取得到的值如下
            let accessKeyId = "yourAccessKeyID"
            let accessKeySecret = "yourAccessKeySecret"
            let securityToken = "yourSecurityToken"
            
            // 您可以選擇設定到期時間（可選）
            // 當不設定到期時間時，則不會自動重新整理訪問憑證。
            let expiration = Date() // 如果設定了到期時間，會結合refreshInterval和到期時間，定期調用該閉包，重新整理憑證
            
            // 返回訪問憑證對象
            return Credentials(accessKeyId: accessKeyId,
                               accessKeySecret: accessKeySecret,
                               securityToken: securityToken,
                               expiration: expiration)
        }

        // 配置OSS用戶端參數
        let config = Configuration.default()
            .withRegion(region)        // 設定Bucket所在地區
            .withCredentialsProvider(credentialsProvider)  // 設定訪問憑證
            
        // 設定自訂Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 建立OSS用戶端執行個體
        let client = Client(config)
        
        // 使用Client發起請求，例如執行檔案上傳、下載或管理等操作...
    }
}

常見問題

使用STS臨時身份憑證初始化憑證提供者時，誤使用RAM使用者AK

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

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

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

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

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

檢查您使用的RAM使用者的AK是否正確，請直接參考文檔查看RAM使用者的AccessKey資訊。
RAM使用者的AccessKey Secret僅在建立時顯示，之後無法查看，若您已經遺忘了的話無法找回。您可以直接存取RAM控制台選擇具體使用者，並建立新的AccessKey進行輪換。詳細請參見建立AccessKey。
登入RAM控制台選擇具體使用者，給RAM使用者添加上傳檔案到OSS的許可權。

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

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

確認Bucket所在地區：登入阿里雲控制台，找到您的Bucket，確認其所在地區。
使用正確的Endpoint：根據Bucket所在地區，使用對應的外網Endpoint。例如，如果Bucket位於華東1（杭州），則應使用oss-cn-hangzhou.aliyuncs.com。各地區的Endpoint資訊請參見地區和Endpoint。
檢查網路連接：確保您的網路環境可以正常訪問互連網，避免因網路問題導致串連失敗。

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

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

注意事項

憑證提供者選型

常用配置樣本

使用RAM使用者的AK

環境變數

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

靜態憑證

使用STS臨時訪問憑證

環境變數

Mac OS X/Linux/Unix

Windows

靜態憑證

更多情境化配置樣本

自訂憑證提供者

常見問題

使用STS臨時身份憑證初始化憑證提供者時，誤使用RAM使用者AK

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

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

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

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