开发者指南

API 文档

SDK 文档

创建请求概述

最近更新时间:2020-04-23 12:24:37

基本概念

腾讯云对象存储 COS 是一个使用 HTTP/HTTPS 协议访问的 Web 存储服务,您可以使用 REST APICOS SDK 来访问 COS。

当您发起访问 COS 请求,需要经过 COS 认证和鉴权后,才可以对资源进行操作。因此根据身份是否可识别,访问 COS 的请求分两种类型:匿名请求和签名请求。

  • 匿名请求:请求未携带 Authorization 或相关参数,又或者相关字符无法识别出用户身份特征,此时请求就会被视为匿名请求而进行鉴权。
  • 签名请求:签名的请求需要在 HTTP 头部或者请求包中包含 Authorization 字段,该字段的内容是结合腾讯云的安全凭证 SecretID、SecretKey 和请求的一些特征值,通过加密算法生成。

如果您使用 COS SDK 访问,只需配置好您的安全凭证即可发起请求。使用 REST API 访问,则需要参见 请求签名 文档自行计算请求签名或通过 COS 签名工具 直接生成。

获取安全凭证

腾讯云访问管理(Cloud Access Management,CAM)为对象存储 COS 提供了账号和安全凭证的相关功能和服务,主要用于帮助客户安全管理腾讯云账户下的资源的访问权限。用户可以通过 CAM 创建、管理和销毁用户(组),并使用身份管理和策略管理控制其他用户使用腾讯云资源的权限。

主账号的安全凭证

在登录主账号后,可通过访问管理中的 云 API 密钥 页面管理和获取您的主账号安全凭证 SecretID 和 SecretKey 密钥。以下是一组密钥示例:

  • 36 个字符的访问密钥 ID(SecretID):AKIDHZRLB9Ibhdp7Y7gyQq6BOk1997xxxxxx
  • 32 个字符的访问密钥 Key(SecretKey):LYaWIuQmCSZ5ZMniUM6hiaLxHnxxxxxx

访问密钥可用于标识唯一的账户,使用密钥签名后发送请求,腾讯云将识别请求发起者的身份,并在认证后,对身份、资源、操作、条件等进行鉴权,来判断是否允许执行此操作。

注意:

主账号密钥具备其名下所有资源的所有操作权限,密钥的泄露可能造成您的云上资产损失,强烈建议您创建子账户并分配合理的权限,使用子账户的密钥创建请求来访问和管理资源。

子账号的安全凭证

当您需要在多个维度管理名下的用户和云资源时,您可以在主账号名下创建多个子账号,实现分管人员对资源权限的功能。有关创建子账号的说明请参阅访问管理 用户管理 的相关文档。

使用子账号发起 API 请求前,您需要为子账号创建安全凭证,随后子账号也将具备独特的密钥对,以便于识别身份。您可以对不同的子账号编写用户策略,来控制其对资源的访问权限。您也可以创建用户组,并对用户组添加统一的访问策略,便于对人员的分组和资源的统筹管理。

注意:

子账号被分配对应权限后,可以创建或修改资源,此时资源仍然属于主账号,主账号需要支付该资源产生的费用。

临时安全凭证

除了使用主账号或子账号的安全凭证访问资源外,腾讯云还支持通过创建角色,并使用临时安全凭证管理腾讯云资源。有关角色的基本概念和使用方法,请参阅访问管理 角色管理 文档。

由于角色是一个虚拟身份,因此角色不具备永久密钥,腾讯云的 CAM 提供了一套 STS API 用于生成临时安全凭证。
使用方法和示例详情请参阅 使用角色 文档,或参阅 STS API 文档查看生成临时安全凭证的方式。临时安全凭证通常只包括有限策略(操作、资源、条件)和有限时间(有效起止时间),因此生成的临时安全凭证可自行分发或直接使用。

调用生成临时安全凭证的接口,您将获得一对临时密钥(tmpSecretId/tmpSecretKey)和一个安全令牌(sessionToken),其构成了可用于访问对象存储 COS 的安全凭证,示例如下:

  • 41 个字符的安全令牌(SecurityToken):5e776c4216ff4d31a7c74fe194a978a3ff2xxxxxx
  • 36 个字符的临时访问密钥 ID(SecretID): AKIDcAZnqgar9ByWq6m7ucIn8LNEuYxxxxxx
  • 32 个字符的临时访问密钥 Key(SecretKey): VpxrX0IMCpHXWL0Wr3KQNCqJixxxxxxx

该接口还会通过 expiration 字段返回临时安全凭证的有效时间,这意味着您只能在此时间内使用这组安全凭证来发起请求。

腾讯云对象存储 COS 提供了简单的服务端 SDK 可用于生成临时密钥,可访问 COS STS SDK 获取。在得到临时安全凭证后,使用 REST API 发起请求,您需要在 HTTP 头部或 POST 请求包的 form-data 中传入x-cos-security-token字段标识该请求使用的安全令牌,再使用临时访问密钥对来计算请求签名。使用 COS SDK 发起访问请参考各 SDK 文档中的相关部分。

访问域名

REST API

我们在 地域和访问域名 文档中列出了可用于发起 REST API 访问的域名列表。

COS 推荐使用虚拟托管型域名访问存储桶,在发起 HTTP 请求时直接通过Host头部带入需要访问的存储桶,例如 <BucketName-APPID>.cos.<Region>.myqcloud.com。使用虚拟托管型的域名实现了类似虚拟服务器「根目录」的功能,可用于托管类似 favicon.ico、robots.txt、crossdomain.xml 的文件,这些文件是很多应用程序在识别托管网站时,会默认从虚拟服务器「根目录」位置检索的内容。

您也可以使用路径型请求来访问存储桶,例如使用cos.<region>.myqcloud.com/<BucketName-APPID>/的路径来访问存储桶。相应的,请求 Host 和签名需要使用cos.<region>.myqcloud.com,我们的 SDK 默认不支持此种访问方式。

静态网站域名

当您开启存储桶的静态网站功能时,我们将分配一个虚拟托管型的域名供相关功能的使用。静态网站域名的表现与 REST API 有所不同,除了特定的索引页、错误页和跳转配置外,静态网站域名只支持 GET/HEAD/OPTIONS Object 等几种操作,不支持上传或配置资源的操作。

静态网站域名例如:<BucketName-APPID>.cos-website.<Region>.myqcloud.com,您也可以通过控制台的存储桶「基础配置 - 静态网站配置」模块获取此域名。

内网与外网访问

腾讯云对象存储 COS 的访问域名使用了智能 DNS 解析,通过互联网在不同的运营商环境下,我们会检测并指向最优链路供您访问 COS。如果您在腾讯云内部署了服务用于访问 COS,则同地域范围内访问将会自动被指向到内网地址,跨地域暂不支持内网访问,默认将会解析到外网地址。

内网访问判断方法

相同地域内腾讯云产品访问,将会自动使用内网连接,产生的内网流量不计费。因此选购腾讯云不同产品时,建议尽量选择相同地域,减少您的费用。

确认是否内网访问请参考如下方法:

以腾讯 CVM 访问 COS 为例,判断是否使用内网访问 COS ,可以在 CVM 上 使用nslookup命令解析 COS 域名,若返回内网 IP,则表明 CVM 和 COS 之间是内网访问,否则为外网访问。

说明:

内网 IP 地址一般形如10.*.*.*100.*.*.* ,VPC 网络一般为169.254.*.* 等,这两种形式的 IP 都属于内网。

假设examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com为目标存储桶地址,其下方的Address: 10.148.214.13表示从内网访问。

nslookup examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com

Server:         10.138.224.65
Address:        10.138.224.65  #53

Name:   examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Address: 10.148.214.13
Name:   examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Address: 10.148.214.14

测试连通性

基本连通测试

COS 使用了 HTTP 协议对外提供服务,您可使用最基本的telnet工具来对 COS 访问域名的80端口发起访问测试。

通过外网访问的示例如下:

telnet examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com 80
Trying 14.119.113.22...
Connected to gz.file.myqcloud.com.
Escape character is '^]'.

通过同地域的腾讯云 CVM (基础网络)访问示例如下:

telnet examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com 80
Trying 10.148.214.14...
Connected to 10.148.214.14.
Escape character is '^]'.

通过同地域的腾讯云 CVM (VPC 网络)访问示例如下:

telnet examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com 80
Trying 169.254.0.47....
Connected to 169.254.0.47.
Escape character is '^]'.

无论处于何种访问环境,命令返回Escape character is '^]'.字段则说明可成功连通。

通过互联网测试的说明

由于通过互联网访问 COS 会经过运营商网络,运营商网络可能禁止您使用 ICMP 协议的pingtraceroute等工具来测试连通性,因此建议使用 TCP 协议的工具来测试连通性。

注意:

通过互联网访问可能受到多种网络环境的影响,如有访问不畅的情况,请排查本地网络链路或联系当地运营商进行反馈。

若您的运营商允许 ICMP 协议,您可以使用pingtraceroutemtr工具来检视您的链路状况。运营商不允许使用 ICMP 协议,您可以使用psping(Windows 环境,请前往微软官网下载)或tcping (跨平台软件)等工具进行时延测试。

通过内网测试的说明

如果您通过同地域的腾讯云 VPC 网络来访问对象存储 COS,则可能无法使用 ICMP 协议的pingtraceroute等工具来测试连通性。建议您使用基本连通测试中的telnet命令进行测试。

您亦可尝试使用pspingtcping等工具直接对访问域名的80端口进行时延测试,请在测试前确保已通过nslookup命令查询并确认访问域名已正确解析至内网地址。

目录