Swift配置客户端

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

使用Swift SDK V2发起OSS请求时,您需要初始化一个OSS Client实例,并根据需要修改默认配置项。

注意事项

  • 初始化OSS Client前,您需要配置访问凭证,本文以从环境变量读取访问凭证为例,更多配置示例请参见配置访问凭证

  • 关于OSS支持的RegionEndpoint的对应关系,请参见OSS地域和访问域名

前置条件

重要

在配置客户端前,您需要先使用RAM用户AccessKey完成配置环境变量。

  1. 创建有OSS管理权限的RAM用户AccessKey

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下,勾选确认,然后单击创建

    1.png

    创建完成后,在输出中,复制创建的AccessKey。

    image

  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)

  3. 参考上述方式修改系统环境变量后,请重启或刷新您的编译运行环境,包括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配置参数汇总

参数名

说明

示例

region

(必选)请求发送的区域, 必选

Configuration.region = "cn-hangzhou"

endpoint

访问域名

Configuration.endpoint = "oss-cn-hangzhou.aliyuncs.com"

retryMaxAttempts

失败请求的最大重试次数

Configuration.retryMaxAttempts = 5

retryer

HTTP请求时的重试实现

Configuration.retryer = customRetryer

logger

设置日志打印接口

Configuration.HttpTransport = customLogger

credentialsProvider

(必选)设置访问凭证

Configuration.credentialsProvider = EnvironmentCredentialsProvider()

usePathStyle

使用路径请求风格,即二级域名请求风格,默认为bucket托管域名

Configuration.usePathStyle = true

useCName

是否使用自定义域名访问,默认不使用

Configuration.useCName = true

timeoutIntervalForRequest

请求超时时间, 默认值为 15 秒

Configuration.timeoutIntervalForRequest = 30

timeoutIntervalForResource

资源请求允许花费的最长时间, 默认值为 24 小时

Configuration.timeoutIntervalForResource = 60 * 60

enableTLSVerify

是否跳过SSL证书校验,默认检查SSL证书

Configuration.enableTLSVerify = true

enableFollowRedirect

是否开启HTTP重定向, 默认不开启

Configuration.enableFollowRedirect = true

maxConnectionsPerHost

host最大连接数

Configuration.maxConnectionsPerHost = 5

enableBackgroundTransmitService

是否开启后台传输,默认关闭

Configuration.enableBackgroundTransmitService = true

backgroundSesseionIdentifier

后台session id

Configuration.backgroundSesseionIdentifier = "com.aliyun.oss.background.session"

signerVersion

签名版本,默认值为v4

Configuration.signerVersion = "v4"

httpProtocal

http协议,默认使用https

Configuration.httpProtocal = .https

useDualStackEndpoint

是否使用双栈域名访问,默认不使用

Configuration.useDualStackEndpoint = true

useAccelerateEndpoint

是否使用传输加速域名访问,默认不使用

Configuration.useAccelerateEndpoint = true

useInternalEndpoint

是否使用内网域名访问,默认不使用

Configuration.useInternalEndpoint = true

enableUploadCRC64Validation

上传时开启CRC64校验,默认开启CRC64校验

Configuration.enableUploadCRC64Validation = true

enableDownloadCRC64Validation

下载时开启CRC64校验,默认开启CRC64校验

Configuration.enableDownloadCRC64Validation = true

additionalHeaders

指定额外的签名请求头,V4签名下有效

Configuration.additionalHeaders = ["x-oss-meta-*"]

userAgent

指定额外的User-Agent信息

Configuration.userAgent = "MyApp/1.0"

常见问题

如果您希望通过与OSS同地域的其他阿里云产品访问OSS,如何提升传输速度?

当您的使用场景对上传速度有要求时,建议您通过与OSS同地域的其他阿里云产品(如ECS服务器)访问OSS,并且请改成使用内网Endpoint进行访问,请参见ECS实例通过OSS内网地址访问OSS资源

如何查看RAM用户的AK信息?

  1. 如需查看RAM用户的AK,请直接登录RAM控制台选择具体用户查看AK信息。

  2. RAM用户的AccessKey Secret仅在创建时显示,之后无法查看,若已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户,并创建新的AccessKey进行轮换。具体操作请参见创建AccessKey

如果遇到报错问题该如何查询具体的错误类型?

关于错误类型的查询,OSS文档提供了EC错误码供您参阅,例如关于认证方面的常见报错问题,可参见02-AUTH