本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
使用Swift SDK V2发起OSS请求时,您需要初始化一个OSS Client实例,并根据需要修改默认配置项。
注意事项
初始化OSS Client前,您需要配置访问凭证,本文以从环境变量读取访问凭证为例,更多配置示例请参见配置访问凭证。
关于OSS支持的Region与Endpoint的对应关系,请参见OSS地域和访问域名。
前置条件
在配置客户端前,您需要先使用RAM用户AccessKey完成配置环境变量。
使用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、命令行界面、其他桌面应用程序及后台服务,以确保最新的系统环境变量成功加载。
默认配置示例
Swift SDK V2默认使用V4签名,在初始化Client时,您需要指定阿里云通用Region ID作为发起请求地域的标识,本示例代码使用华东1(杭州)Region ID:cn-hangzhou。如需查询其它Region ID请参见OSS地域和访问域名。
Swift SDK V2可以通过Endpoint参数,自定义服务请求的访问域名。当不指定时,SDK默认根据Region信息,构造公网访问域名。例如当Region为'cn-hangzhou'时,构造出来的访问域名为'https://oss-cn-hangzhou.aliyuncs.com'。
Swift SDK V2构造访问域名时默认采用https协议,如需采用http协议,请在指定域名时指定为http,例如'http://oss-cn-hangzhou.aliyuncs.com'。
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)
}
}
常见场景配置示例
内网域名配置示例
当您的应用部署在阿里云的ECS实例上,并且需要频繁访问同地域的OSS资源时,使用内网域名可以降低流量成本并提高访问速度。
以下是使用OSS内网域名配置OSSClient的示例代码。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域(示例:华东1为cn-hangzhou)
let region = "cn-hangzhou"
let endpoint: String? = "https://oss-cn-hangzhou-internal.aliyuncs.com" // 可选项,指定访问OSS服务的内网域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou-internal.aliyuncs.com
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
let credentialsProvider = EnvironmentCredentialsProvider()
// 配置OSS客户端参数
let config = Configuration.default()
.withRegion(region) // 设置Bucket所在地域
.withCredentialsProvider(credentialsProvider) // 设置访问凭证
// 您也可以无需指定内网endpoint,直接设置useInternalEndpoint = true配置内网域名
// .withUseInternalEndpoint(true)
// 设置自定义Endpoint
if let endpoint = endpoint {
config.withEndpoint(endpoint)
}
// 创建OSS客户端实例
let client = Client(config)
}
}
自定义域名配置示例
当您有多个不同的OSS Bucket用于不同的目的时,可以通过为每个Bucket设置不同的子域名来更好地管理和组织资源。
以下是使用自定义域名配置OSSClient的示例代码。
您需要先将自定义域名绑定至Bucket默认域名,否则将引发报错!关于绑定自定义域名的详细操作,请参见绑定自定义域名至Bucket默认域名。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域(示例:华东1为cn-hangzhou)
let region = "cn-hangzhou"
let endpoint: String? = "https://www.example-***.com" // 必须项,请填写您的自定义域名。例如www.example-***.com
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
let credentialsProvider = EnvironmentCredentialsProvider()
// 配置OSS客户端参数
let config = Configuration.default()
.withRegion(region) // 设置Bucket所在地域
.withCredentialsProvider(credentialsProvider) // 设置访问凭证
.withUseCname(true) // 请注意,设置true开启CNAME选项,否则无法使用自定义域名
// 设置自定义Endpoint
if let endpoint = endpoint {
config.withEndpoint(endpoint)
}
// 创建OSS客户端实例
let client = Client(config)
}
}
传输加速域名配置示例
以下是使用传输加速域名配置OSSClient的示例代码。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域(示例:华东1为cn-hangzhou)
let region = "cn-hangzhou"
let endpoint: String? = "https://oss-cn-hangzhou-accelerate.aliyuncs.com" // 可选项,填写Bucket所在地域对应的传输加速Endpoint。以华东1(杭州)为例,Endpoint填写为'https://oss-accelerate.aliyuncs.com'
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
let credentialsProvider = EnvironmentCredentialsProvider()
// 配置OSS客户端参数
let config = Configuration.default()
.withRegion(region) // 设置Bucket所在地域
.withCredentialsProvider(credentialsProvider) // 设置访问凭证
// 您也可以无需指定传输加速endpoint,直接设置useAccelerateEndpoint = true配置传输加速域名
// .withUseAccelerateEndpoint(true)
// 设置自定义Endpoint
if let endpoint = endpoint {
config.withEndpoint(endpoint)
}
// 创建OSS客户端实例
let client = Client(config)
}
}
专有域配置示例
以下是使用专有域配置OSSClient的示例代码。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域(示例:华东1为cn-hangzhou)
let region = "cn-hangzhou"
let endpoint: String? = "https://service.corp.example.com" // 必须项,请填写您的专有域。例如:https://service.corp.example.com
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量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)
}
}
金融云配置示例
以下是使用金融云域名配置OSSClient的示例代码。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域。以华东1 金融云为例,Region填写为cn-hangzhou-finance
let region = "cn-hangzhou-finance"
let endpoint: String? = "https://oss-cn-hzjbp-a-internal.aliyuncs.com" // 必须项, 填写Bucket所在地域对应的内网Endpoint。以华东1 金融云为例,Endpoint填写为'https://oss-cn-hzjbp-a-internal.aliyuncs.com'
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量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)
}
}
政务云配置示例
以下是使用政务云域名配置OSSClient的示例代码。
import AlibabaCloudOSS
import Foundation
@main
struct Main {
static func main() async {
// 填写Bucket所在地域。以华北2 阿里政务云1为例,Region填写为cn-north-2-gov-1
let region = "cn-north-2-gov-1"
// 必须项, 填写Bucket所在地域对应的内网Endpoint。以华北2 阿里政务云1为例,Endpoint填写为'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'
let endpoint: String? = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com"
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量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)
}
}
OSSClient配置参数汇总
参数名 | 说明 | 示例 |
| (必选)请求发送的区域, 必选 | Configuration.region = "cn-hangzhou" |
| 访问域名 | Configuration.endpoint = "oss-cn-hangzhou.aliyuncs.com" |
| 失败请求的最大重试次数 | Configuration.retryMaxAttempts = 5 |
| HTTP请求时的重试实现 | Configuration.retryer = customRetryer |
| 设置日志打印接口 | Configuration.HttpTransport = customLogger |
| (必选)设置访问凭证 | Configuration.credentialsProvider = EnvironmentCredentialsProvider() |
| 使用路径请求风格,即二级域名请求风格,默认为bucket托管域名 | Configuration.usePathStyle = true |
| 是否使用自定义域名访问,默认不使用 | Configuration.useCName = true |
| 请求超时时间, 默认值为 15 秒 | Configuration.timeoutIntervalForRequest = 30 |
| 资源请求允许花费的最长时间, 默认值为 24 小时 | Configuration.timeoutIntervalForResource = 60 * 60 |
| 是否跳过SSL证书校验,默认检查SSL证书 | Configuration.enableTLSVerify = true |
| 是否开启HTTP重定向, 默认不开启 | Configuration.enableFollowRedirect = true |
| 单host最大连接数 | Configuration.maxConnectionsPerHost = 5 |
| 是否开启后台传输,默认关闭 | Configuration.enableBackgroundTransmitService = true |
| 后台session id | Configuration.backgroundSesseionIdentifier = "com.aliyun.oss.background.session" |
| 签名版本,默认值为v4 | Configuration.signerVersion = "v4" |
| http协议,默认使用https | Configuration.httpProtocal = .https |
| 是否使用双栈域名访问,默认不使用 | Configuration.useDualStackEndpoint = true |
| 是否使用传输加速域名访问,默认不使用 | Configuration.useAccelerateEndpoint = true |
| 是否使用内网域名访问,默认不使用 | Configuration.useInternalEndpoint = true |
| 上传时开启CRC64校验,默认开启CRC64校验 | Configuration.enableUploadCRC64Validation = true |
| 下载时开启CRC64校验,默认开启CRC64校验 | Configuration.enableDownloadCRC64Validation = true |
| 指定额外的签名请求头,V4签名下有效 | Configuration.additionalHeaders = ["x-oss-meta-*"] |
| 指定额外的User-Agent信息 | Configuration.userAgent = "MyApp/1.0" |