README
¶
获取 SDK
go get -u github.com/tencentyun/qcloud-cos-sts-sdk
查看示例
请查看 example/sts_demo.go 文件，里面描述了如何调用SDK。
接口说明
NewClient
创建客户端。
func NewClient(secretId, secretKey string, hc *http.Client, opt ...func(*Client)) *Client
参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| secretId | String | 云 API 密钥 Id |
| secretKey | String | 云 API 密钥 key |
| hc | *http.Client | go http模块Client |
| opt | func(*Client) | Client配置项，可选, 可用于设置 Host 和 Scheme |
NewClientWithCredential
通过 CredentialIface 创建客户端。
func NewClientWithCredential(cred CredentialIface, hc *http.Client, opt ...func(*Client)) *Client
参数说明
type CredentialIface interface {
GetSecretId() string
GetSecretKey() string
GetToken() string
}
| 字段 | 类型 | 描述 |
|---|---|---|
| cred | CredentialIface | 通过用户实现的CredentialIface接口获取密钥,用户需要自行保证接口线程安全 |
| hc | *http.Client | go http模块Client |
| opt | func(*Client) | Client配置项，可选, 可用于设置 Host 和 Scheme |
GetCredential
func (c *Client) GetCredential(opt *CredentialOptions) (*CredentialResult, error)
参数说明
type CredentialPolicyStatement struct {
Action []string
Effect string
Resource []string
Condition map[string]map[string]interface{}
}
type CredentialPolicy struct {
Version string
Statement []CredentialPolicyStatement
}
type CredentialOptions struct {
Policy *CredentialPolicy
Region string
DurationSeconds int64
}
| 字段 | 类型 | 描述 | |
|---|---|---|---|
| opt | *CredentialPolicy | 授权策略 | 是 |
| Version | string | 策略语法版本，默认为2.0 | 否 |
| Action | []string | 此处是指 COS API，根据需求指定一个或者一序列操作的组合或所有操作(*) | 是 |
| Effect | string | 有 allow （允许）和 deny （显式拒绝）两种情况 | 是 |
| Resource | []string | 授权操作的具体数据，可以是任意资源、指定路径前缀的资源、指定绝对路径的资源或它们的组合 | 是 |
| Condition | map | 约束条件，可以不填，具体说明请参见 condition 说明 | 否 |
| Region | string | STS云API的地域，建议与存储桶地域保持一致 | 否 |
| DurationSeconds | int64 | 指定临时证书的有效期，单位：秒，默认1800秒，最长可设定有效期为7200秒。 | 否 |
返回值说明
type Credentials struct {
TmpSecretID string
TmpSecretKey string
SessionToken string
}
type CredentialResult struct {
Credentials *Credentials
StartTime int
ExpiredTime int
Expiration string
RequestId string
}
| 字段 | 类型 | 描述 |
|---|---|---|
| Credentials | *Credentials | 临时密钥信息 |
| TmpSecretID | string | 临时密钥 Id，可用于计算签名 |
| TmpSecretKey | string | 临时密钥 Key，可用于计算签名 |
| SessionToken | string | 请求时需要用的 token 字符串，最终请求 COS API 时，需要放在 Header 的 x-cos-security-token 字段 |
| StartTime | int | 密钥的起始时间，是 UNIX 时间戳 |
| ExpiredTime | int | 密钥的失效时间，是 UNIX 时间戳 |
使用方法
调用代码如下：
package main
import (
"fmt"
"github.com/tencentyun/qcloud-cos-sts-sdk/go"
"os"
"time"
)
func main() {
appid := "1259654469"
bucket := "test-1259654469"
region := "ap-guangzhou"
c := sts.NewClient(
// 通过环境变量获取密钥, os.Getenv 方法表示获取环境变量
os.Getenv("SECRETID"), // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
nil,
// sts.Host("sts.internal.tencentcloudapi.com"), // 设置域名, 默认域名sts.tencentcloudapi.com
// sts.Scheme("http"), // 设置协议, 默认为https，公有云sts获取临时密钥不允许走http，特殊场景才需要设置http
)
// 策略概述 https://cloud.tencent.com/document/product/436/18023
opt := &sts.CredentialOptions{
DurationSeconds: int64(time.Hour.Seconds()),
Region: "ap-guangzhou",
Policy: &sts.CredentialPolicy{
Statement: []sts.CredentialPolicyStatement{
{
Action: []string{
"name/cos:PostObject",
"name/cos:PutObject",
},
Effect: "allow",
Resource: []string{
//这里改成允许的路径前缀，可以根据自己网站的用户登录态判断允许上传的具体路径，例子： a.jpg 或者 a/* 或者 * (使用通配符*存在重大安全风险, 请谨慎评估使用)
//存储桶的命名格式为 BucketName-APPID，此处填写的 bucket 必须为此格式
"qcs::cos:" + region + ":uid/" + appid + ":" + bucket + "/exampleobject",
},
// 开始构建生效条件 condition
// 关于 condition 的详细设置规则和COS支持的condition类型可以参考https://cloud.tencent.com/document/product/436/71306
Condition: map[string]map[string]interface{}{
"ip_equal": map[string]interface{}{
"qcs:ip": []string{
"10.217.182.3/24",
"111.21.33.72/24",
},
},
},
},
},
},
}
res, err := c.GetCredential(opt)
if err != nil {
panic(err)
}
fmt.Printf("%+v\n", res)
fmt.Printf("%+v\n", res.Credentials)
}
GetRoleCredential
申请扮演角色临时密钥接口。
func (c *Client) GetRoleCredential(opt *CredentialOptions) (*CredentialResult, error)
参数说明
type CredentialPolicyStatement struct {
Action []string
Effect string
Resource []string
Condition map[string]map[string]interface{}
}
type CredentialPolicy struct {
Version string
Statement []CredentialPolicyStatement
}
type CredentialOptions struct {
Policy *CredentialPolicy
Region string
DurationSeconds int64
RoleArn string
RoleSessionName string
ExternalId string
}
| 字段 | 类型 | 描述 | 必选 |
|---|---|---|---|
| opt | *CredentialPolicy | 授权策略 | 是 |
| Version | string | 策略语法版本，默认为2.0 | 否 |
| Action | []string | 此处是指 COS API，根据需求指定一个或者一序列操作的组合或所有操作(*) | 是 |
| Effect | string | 有 allow （允许）和 deny （显式拒绝）两种情况 | 是 |
| Resource | []string | 授权操作的具体数据，可以是任意资源、指定路径前缀的资源、指定绝对路径的资源或它们的组合 | 是 |
| Condition | map | 约束条件，可以不填，具体说明请参见 condition 说明 | 否 |
| Region | string | STS云API的地域，建议与存储桶地域保持一致 | 否 |
| DurationSeconds | int64 | 指定临时证书的有效期，单位：秒，默认1800秒，最长可设定有效期为7200秒。 | 否 |
| RoleArn | String | 角色的资源描述，可在访问管理，点击角色名获取。 普通角色： qcs::cam::uin/12345678:role/4611686018427397919、qcs::cam::uin/12345678:roleName/testRoleName 服务角色： qcs::cam::uin/12345678:role/tencentcloudServiceRole/4611686018427397920、qcs::cam::uin/12345678:role/tencentcloudServiceRoleName/testServiceRoleName | 是 |
| RoleSessionName | String | 临时会话名称，由用户自定义名称。 长度在2到128之间，可包含大小写字符，数字以及特殊字符：=,.@-。 正则为：[\w+=,.@-]* | 是 |
| ExternalId | String | 角色外部ID，可在访问管理，点击角色名获取。 长度在2到128之间，可包含大小写字符，数字以及特殊字符：=,.@:/-。 正则为：[\w+=,.@:/-]* | 否 |
返回值说明
type Credentials struct {
TmpSecretID string
TmpSecretKey string
SessionToken string
}
type CredentialResult struct {
Credentials *Credentials
StartTime int
ExpiredTime int
Expiration string
RequestId string
}
| 字段 | 类型 | 描述 |
|---|---|---|
| Credentials | *Credentials | 临时密钥信息 |
| TmpSecretID | string | 临时密钥 Id，可用于计算签名 |
| TmpSecretKey | string | 临时密钥 Key，可用于计算签名 |
| SessionToken | string | 请求时需要用的 token 字符串，最终请求 COS API 时，需要放在 Header 的 x-cos-security-token 字段 |
| StartTime | int | 密钥的起始时间，是 UNIX 时间戳 |
| ExpiredTime | int | 密钥的失效时间，是 UNIX 时间戳 |
使用方法
调用代码如下：
package main
import (
"fmt"
"github.com/tencentyun/qcloud-cos-sts-sdk/go"
"os"
"time"
)
func main() {
appid := "1259654469"
bucket := "test-1259654469"
c := sts.NewClient(
// 通过环境变量获取密钥, os.Getenv 方法表示获取环境变量
os.Getenv("SECRETID"), // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
nil,
// sts.Host("sts.internal.tencentcloudapi.com"), // 设置域名, 默认域名sts.tencentcloudapi.com
// sts.Scheme("http"), // 设置协议, 默认为https，公有云sts获取临时密钥不允许走http，特殊场景才需要设置http
)
// 发起角色授权临时密钥请求, policy选填
// 策略概述 https://cloud.tencent.com/document/product/436/18023
opt := &sts.CredentialOptions{
DurationSeconds: int64(time.Hour.Seconds()),
Region: "ap-guangzhou",
Policy: &sts.CredentialPolicy{
Statement: []sts.CredentialPolicyStatement{
{
// 密钥的权限列表。简单上传和分片需要以下的权限，其他权限列表请看 https://cloud.tencent.com/document/product/436/31923
Action: []string{
// 简单上传
"name/cos:PostObject",
"name/cos:PutObject",
// 分片上传
"name/cos:InitiateMultipartUpload",
"name/cos:ListMultipartUploads",
"name/cos:ListParts",
"name/cos:UploadPart",
"name/cos:CompleteMultipartUpload",
},
Effect: "allow",
Resource: []string{
//这里改成允许的路径前缀，可以根据自己网站的用户登录态判断允许上传的具体路径，例子： a.jpg 或者 a/* 或者 * (使用通配符*存在重大安全风险, 请谨慎评估使用)
//存储桶的命名格式为 BucketName-APPID，此处填写的 bucket 必须为此格式
"qcs::cos:ap-guangzhou:uid/" + appid + ":" + bucket + "/exampleobject",
},
// 开始构建生效条件 condition
// 关于 condition 的详细设置规则和COS支持的condition类型可以参考https://cloud.tencent.com/document/product/436/71306
Condition: map[string]map[string]interface{}{
"ip_equal": map[string]interface{}{
"qcs:ip": []string{
"10.217.182.3/24",
"111.21.33.72/24",
},
},
},
},
},
},
RoleArn: "qcs::cam::uin/100010805041:roleName/COSBatch_QCSRole",
RoleSessionName: "test",
}
res, err := c.GetRoleCredential(opt)
if err != nil {
panic(err)
}
fmt.Printf("%+v\n", res)
fmt.Printf("%+v\n", res.Credentials)
}
AssumeRoleWithWebIdentity
申请OIDC角色临时密钥申请OIDC角色临时密钥。
func (c *Client) AssumeRoleWithWebIdentity(opt *WebIdentityOptions) (*CredentialResult, error)
参数说明
type WebIdentityOptions struct {
Region string
ProviderId string
WebIdentityToken string
RoleArn string
RoleSessionName string
DurationSeconds int64
}
| 字段 | 类型 | 描述 | 必选 |
|---|---|---|---|
| opt | *WebIdentityOptions | 授权策略 | 是 |
| Region | string | STS云API的地域，建议与存储桶地域保持一致 | 否 |
| ProviderId | string | 身份提供商名称 | 是 |
| WebIdentityToken | string | IdP签发的OIDC令牌 | 是 |
| RoleArn | String | 角色访问描述名 | 是 |
| RoleSessionName | string | 会话名称 | 是 |
| DurationSeconds | int64 | 指定临时证书的有效期，单位：秒，默认7200秒，最长可设定有效期为43200秒。 | 否 |
返回值说明
type Credentials struct {
TmpSecretID string
TmpSecretKey string
SessionToken string
}
type CredentialResult struct {
Credentials *Credentials
StartTime int
ExpiredTime int
Expiration string
RequestId string
}
| 字段 | 类型 | 描述 |
|---|---|---|
| Credentials | *Credentials | 临时密钥信息 |
| TmpSecretID | string | 临时密钥 Id，可用于计算签名 |
| TmpSecretKey | string | 临时密钥 Key，可用于计算签名 |
| SessionToken | string | 请求时需要用的 token 字符串，最终请求 COS API 时，需要放在 Header 的 x-cos-security-token 字段 |
| StartTime | int | 密钥的起始时间，是 UNIX 时间戳 |
| ExpiredTime | int | 密钥的失效时间，是 UNIX 时间戳 |
使用方法
调用代码如下：
package main
import (
"fmt"
"github.com/tencentyun/qcloud-cos-sts-sdk/go"
"os"
"time"
)
func main() {
appid := "1259654469"
bucket := "test-1259654469"
c := sts.NewClient(
// 通过环境变量获取密钥, os.Getenv 方法表示获取环境变量
os.Getenv("SECRETID"), // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140
nil,
// sts.Host("sts.internal.tencentcloudapi.com"), // 设置域名, 默认域名sts.tencentcloudapi.com
// sts.Scheme("http"), // 设置协议, 默认为https，公有云sts获取临时密钥不允许走http，特殊场景才需要设置http
)
opt := &sts.WebIdentityOptions{
ProviderId: "your ProviderId",
WebIdentityToken: "your WebIdentityToken",
RoleArn: "your RoleArn",
RoleSessionName: "test",
}
res, err := c.AssumeRoleWithWebIdentity(wopt)
if err != nil {
panic(err)
}
fmt.Printf("%+v\n", res)
fmt.Printf("%+v\n", res.Credentials)
}
Documentation
¶
Index ¶
- type Client
- func (c *Client) AssumeRoleWithWebIdentity(opt *WebIdentityOptions) (*CredentialResult, error)
- func (c *Client) GetCredential(opt *CredentialOptions) (*CredentialResult, error)
- func (c *Client) GetRoleCredential(opt *CredentialOptions) (*CredentialResult, error)
- func (c *Client) RequestCredential(opt *CredentialOptions) (*http.Response, error)
- func (c *Client) SetHost(host string)
- func (c *Client) SetScheme(scheme string)
- type ClientConf
- type ClientOption
- type Credential
- type CredentialCompleteResult
- type CredentialError
- type CredentialIface
- type CredentialOptions
- type CredentialPolicy
- type CredentialPolicyStatement
- type CredentialResult
- type Credentials
- type WebIdentityOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
Credential CredentialIface
// contains filtered or unexported fields
}
func NewClient ¶
func NewClient(secretId, secretKey string, hc *http.Client, opt ...ClientOption) *Client
func NewClientWithCredential ¶
func NewClientWithCredential(cred CredentialIface, hc *http.Client, opt ...ClientOption) *Client
func (*Client) AssumeRoleWithWebIdentity ¶
func (c *Client) AssumeRoleWithWebIdentity(opt *WebIdentityOptions) (*CredentialResult, error)
func (*Client) GetCredential ¶
func (c *Client) GetCredential(opt *CredentialOptions) (*CredentialResult, error)
func (*Client) GetRoleCredential ¶
func (c *Client) GetRoleCredential(opt *CredentialOptions) (*CredentialResult, error)
func (*Client) RequestCredential ¶
func (c *Client) RequestCredential(opt *CredentialOptions) (*http.Response, error)
type ClientConf ¶
type ClientOption ¶
type ClientOption = func(*Client)
func Host ¶
func Host(host string) ClientOption
func Scheme ¶
func Scheme(scheme string) ClientOption
type Credential ¶
func (*Credential) GetSecretId ¶
func (c *Credential) GetSecretId() string
func (*Credential) GetSecretKey ¶
func (c *Credential) GetSecretKey() string
func (*Credential) GetToken ¶
func (c *Credential) GetToken() string
type CredentialCompleteResult ¶
type CredentialCompleteResult struct {
Response *CredentialResult `json:"Response"`
}
type CredentialError ¶
type CredentialError struct {
Code string `json:"Code,omitempty"`
Message string `json:"Message,omitempty"`
RequestId string `json:"RequestId,omitempty"`
}
func (*CredentialError) Error ¶
func (e *CredentialError) Error() string
type CredentialIface ¶
type CredentialOptions ¶
type CredentialPolicy ¶
type CredentialPolicy struct {
Version string `json:"version,omitempty"`
Statement []CredentialPolicyStatement `json:"statement,omitempty"`
}
type CredentialResult ¶
type CredentialResult struct {
Credentials *Credentials `json:"Credentials,omitempty"`
ExpiredTime int `json:"ExpiredTime,omitempty"`
Expiration string `json:"Expiration,omitempty"`
StartTime int `json:"StartTime,omitempty"`
RequestId string `json:"RequestId,omitempty"`
Error *CredentialError `json:"Error,omitempty"`
}
type Credentials ¶
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.