本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
使用 Swift SDK发起OSS请求,您需要配置访问凭证。阿里云服务会通过 访问凭证验证您的身份信息和访问权限。您可以根据使用场景对认证和授权的要求,选择不同类型的访问凭证。
注意事项
如果您希望获取关于OSS支持的Region与Endpoint的对应关系,请参见OSS地域和访问域名。
如果您希望创建RAM用户的AccessKey,请参见创建AccessKey。
凭证提供者选型
OSS支持多种方式初始化凭证提供者,您可以根据使用场景对认证和授权的要求,选择对应的方式初始化凭证提供者。
凭证提供者初始化方式 | 适用场景 | 是否需要提供前置的AK或STS Token | 底层实现基于的凭证 | 凭证有效期 | 凭证轮转或刷新方式 |
部署运行在安全、稳定且不易受外部攻击的环境的应用程序,无需频繁轮转凭证就可以长期访问云服务 | 是 | AK | 长期 | 手动轮转 | |
部署运行在不可信的环境的应用程序,希望能控制访问的有效期、权限 | 是 | 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发起请求,例如执行文件上传、下载或管理等操作...
}
}