对象存储
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>对象存储>SDK 文档>Node.js SDK>对象操作>生成预签名 URL

生成预签名 URL

最近更新时间：2024-08-14 14:20:21

我的收藏

本页目录：

简介

Node.js SDK 提供获取对象 URL、获取请求预签名 URL 接口，详细操作请查看本文说明和示例。
关于使用预签名 URL 上传的说明请参见 预签名授权上传， 使用预签名 URL 下载的说明请参见 预签名授权下载。
说明：
建议用户使用临时密钥生成预签名，通过临时授权的方式进一步提高预签名上传、下载等请求的安全性。申请临时密钥时，请遵循 最小权限指引原则，防止泄露目标存储桶或对象之外的资源。申请临时密钥的 action 需添加 "name/cos:GetObject" 权限。
如果您一定要使用永久密钥来生成预签名，建议永久密钥的权限范围仅限于上传或下载操作，以规避风险。
使用预签名URL上传时，最大支持上传 5GB 文件。

注意事项

2024年1月1日后创建的桶 不支持使用默认域名在浏览器预览文件，建议您配置自定义域名，详情请参见 存储桶切换自定义域名。
获取签名/预签名函数，默认签入 Header Host；您也可以选择不签入 Header Host，但可能导致请求失败或安全漏洞。
生成预签名 URL 支持使用永久密钥或临时密钥。

前期准备

开始使用前，确保您已经完成了 SDK 初始化。

获取请求预签名 URL（推荐）

获取不带签名 Object Url

var url = cos.getObjectUrl({
  Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
  Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
  Key: '1.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
  Sign: false,
});

获取带签名 Object Url

var url = cos.getObjectUrl({
  Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
  Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
  Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
});

通过 callback 获取带签名 Url

说明：
如果签名过程是异步获取，例如通过 getAuthorization 获取临时密钥/签名做初始化时，需要通过 callback 获取带签名 Url。
cos.getObjectUrl(
  {
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
    Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
  },
  function (err, data) {
    console.log(err || data.Url);
  }
);

指定链接有效时间

cos.getObjectUrl(
  {
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
    Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
    Sign: true,
    Expires: 3600, // 单位秒
  },
  function (err, data) {
    console.log(err || data.Url);
  }
);

获取文件 Url 并下载文件

var request = require('axios');
var fs = require('fs');
cos.getObjectUrl(
  {
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
    Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
    Sign: true,
  },
  function (err, data) {
    if (err) return console.log(err);
    console.log(data.Url);
    
    function download(url, retryTimes) {
        axios({
          method: 'get',
          url: url,
          responseType: 'stream'
        }).then(res => {
          var writeStream = fs.createWriteStream(__dirname + '/头像.jpg');
          res.data.pipe(writeStream);
        }).catch(err => {
          // 5xx 重试一次
          if (Math.floor(err.response.status / 100) === 5 && retryTimes === 0) {
            retryTimes++;
            download(url, retryTimes);
          } else {
            console.log('下载失败');
          }
        });
    }

    download(data.Url, 0);
  }
);

生成预签名 URL，并在签名中携带 Query 和 Header

cos.getObjectUrl(
  {
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
    Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
    Sign: true,
    // 传入的请求参数需与实际请求相同，能够防止用户篡改此 HTTP 请求的参数
    Query: {
      'imageMogr2/thumbnail/200x/': '',
    },
    // 传入的请求头部需包含在实际请求中，能够防止用户篡改签入此处的 HTTP 请求头部
    Headers: {
      host: 'xxx', // 指定 host 访问，非指定的 host 访问会报错403
    },
  },
  function (err, data) {
    console.log(err || data.Url);
  }
);

获取预签名 Put Object 上传 Url

const axios = require('axios');
const fs = require('fs');


cos.getObjectUrl(
  {
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION', // 存储桶所在地域，例如 ap-beijing，必须字段
    Key: '头像.jpg', // 存储在桶里的对象键（例如1.jpg，a/b/test.txt），支持中文，必须字段
    Method: 'PUT',
    Sign: true,
  },
  function (err, data) {
    if (err) return console.log(err);
    console.log(data.Url);
    
    function upload(url, retryTimes) {
      const fileStream = fs.createReadStream(__dirname + '/1.jpg');
      axios({
        method: 'PUT',
        url: url,
        data: fileStream,
      }).then(data => {
        console.log('上传成功', data);
      }).catch(err => {
        // 5xx 重试一次
        if (Math.floor(err.response.status / 100) === 5 && retryTimes === 0) {
          retryTimes++;
          upload(url, retryTimes);
        } else {
          console.log('上传失败');
        }
      });
    }
    upload(data.Url, 0);
  }
);

参数说明

入参说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名规则为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，如果请求操作是对文件的，则为文件名，且为必须参数。如果操作是对于存储桶，则为空
String
是
Sign
是否返回带有签名的 Url，默认为 true
Boolean
否
Protocol
可选填为 http: 或 https:，默认为 http:（带冒号）
String
否
Domain
存储桶访问域名，默认为 {BucketName-APPID}.cos.{Region}.myqcloud.com
String
否
Method
操作方法，如 get，post，delete， head 等 HTTP 方法，默认为 get
String
否
Query
签名中要签入的请求参数，{key: 'val'} 的格式
Object
否
Headers
签名中要签入的请求头部，{key: 'val'} 的格式
Object
否
Expires
签名几秒后失效，默认为 900 秒
Number
否

返回值说明

返回值是一个字符串，两种情况：
1. 如果签名计算可以同步计算（如：实例化传入了 SecretId 和 SecretKey），则默认返回带签名的 url。
2. 否则返回不带签名的 url。

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码 文档
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- Url
计算得到的 Url
String

生成签名后拼接预签名 URL

COS XML API 的请求里，私有资源操作都需要鉴权凭证 Authorization，用于判断当前请求是否合法。
鉴权凭证使用方式有两种：
1. 放在 header 参数里使用，字段名：authorization。
2. 放在 url 参数里使用，字段名：sign。
COS.getAuthorization 方法用于计算鉴权凭证（Authorization），用以验证请求合法性的签名信息。
注意：
该方法推荐只在前端调试时使用，项目上线不推荐使用前端计算签名的方法，有暴露密钥的风险。

使用案例

获取文件下载的鉴权凭证：
// SECRETID 和 SECRETKEY 请登录 https://console.cloud.tencent.com/cam/capi 进行查看和管理
var COS = require('cos-nodejs-sdk-v5');
var Authorization = COS.getAuthorization({
  SecretId: process.env.SecretId, // 推荐使用环境变量获取；用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
  SecretKey: process.env.SecretKey, // 推荐使用环境变量获取；用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
  Method: 'get',
  Key: 'a.jpg',
  Expires: 60,
  Query: {},
  Headers: {},
});

参数说明

参数名
参数描述
类型
是否必填
SecretId
用户的 SecretId
String
是
SecretKey
用户的 SecretKey
String
是
Method
操作方法，如 get，post，delete， head 等 HTTP 方法
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，如果请求操作是对文件的，则为文件名，且为必须参数。如果操作是对于存储桶，则为空
String
否
Query
签名中要签入的请求参数，{key: 'val'} 的格式
Object
否
Headers
签名中要签入的请求头部，{key: 'val'} 的格式
Object
否
Expires
签名几秒后失效，默认为 900 秒
Number
否

返回值说明

返回值是计算得到的鉴权凭证字符串 authorization。
中国站
文档反馈
文档活动
message-icon联系我们
目录