aws4fetch

一个紧凑的（压缩后6.4kb，gzip压缩后2.5kb）AWS客户端，适用于支持fetch和SubtleCrypto的环境 - 即现代Web浏览器和像Cloudflare Workers这样的JS平台。默认情况下，还使用带完全抖动的指数退避策略重试请求。

示例

import { AwsClient } from 'aws4fetch'

const aws = new AwsClient({ accessKeyId: MY_ACCESS_KEY, secretAccessKey: MY_SECRET_KEY })

// https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html
const LAMBDA_FN_API = 'https://lambda.us-east-1.amazonaws.com/2015-03-31/functions'

async function invokeMyLambda(event) {
  const res = await aws.fetch(`${LAMBDA_FN_API}/my-lambda/invocations`, { body: JSON.stringify(event) })

  // `res`是一个标准的Response对象：https://developer.mozilla.org/en-US/docs/Web/API/Response
  return res.json()
}

invokeMyLambda({my: 'event'}).then(json => console.log(json))

你可以在example目录中看到一个更详细的示例，这是一个可以用作API Gateway替代品的Cloudflare Worker脚本。

API

aws4fetch导出两个类：AwsClient和AwsV4Signer

`new AwsClient(options)`

你可以为所有服务调用使用同一个AwsClient实例，因为服务和区域将在获取时确定 - 或者如果你有不同的需求，可以创建单独的实例，例如某些服务不需要重试。

import { AwsClient } from 'aws4fetch'

const aws = new AwsClient({
  accessKeyId,     // 必需，相当于AWS_ACCESS_KEY_ID
  secretAccessKey, // 必需，相当于AWS_SECRET_ACCESS_KEY
  sessionToken,    // 使用临时凭证时相当于AWS_SESSION_TOKEN
  service,         // AWS服务，默认在获取时解析
  region,          // AWS区域，默认在获取时解析
  cache,           // 凭证缓存，默认为`new Map()`
  retries,         // 放弃前的重试次数，默认为10，设置为0表示不重试
  initRetryMs,     // 默认为50 - 超时时间每次重试翻倍
})

`Promise<Response> aws.fetch(input[, init])`

与全局fetch函数具有相同的签名

import { AwsClient } from 'aws4fetch'

const aws = new AwsClient(opts)

async function doFetch() {

  const response = await aws.fetch(url, {

    method,  // 如果未提供，有body时默认为'POST'，否则为'GET'
    headers, // 标准JS对象字面量或Headers实例
    body,    // 可选，字符串或ArrayBuffer/ArrayBufferView - 即，记得将JSON字符串化

    // 以及任何其他标准fetch选项，如keepalive等

    // 可选，主要用于覆盖AwsClient实例中的选项
    aws: {
      signQuery,          // 设置为true以签名查询字符串而不是Authorization头
      accessKeyId,        // 与上面AwsClient构造函数中相同
      secretAccessKey,    // 与上面AwsClient构造函数中相同
      sessionToken,       // 与上面AwsClient构造函数中相同
      service,            // 与上面AwsClient构造函数中相同
      region,             // 与上面AwsClient构造函数中相同
      cache,              // 与上面AwsClient构造函数中相同
      datetime,           // 默认为现在，覆盖时使用'20150830T123600Z'格式
      appendSessionToken, // 设置为true以在签名后添加X-Amz-Security-Token，iot默认为true
      allHeaders,         // 设置为true以强制签名所有头部而不是默认头部
      singleEncode,       // 设置为true以仅对%2F编码一次（通常仅用于测试）
    },
  })

  console.log(await response.json())
}

注意：由于Request实例处理body的方式，使用上述方法调用函数 - 将URL作为input参数，并在init参数中传递body - 比直接使用Request对象作为input的调用形式更快。

如果你不知道要调用的AWS服务的URL，可以在这里找到完整的AWS端点列表： https://docs.aws.amazon.com/general/latest/gr/rande.html

API文档在这里：https://docs.aws.amazon.com/（每个服务的REST API通常记录在"API参考"下）

`Promise<Request> aws.sign(input[, init])`

返回一个Promise，解析为一个AWS4签名的Request - 与fetch具有相同的签名。使用此方法创建一个可以使用fetch()自行发送的Request。

import { AwsClient } from 'aws4fetch'

const aws = new AwsClient(opts)

async function doFetch() {

  const request = await aws.sign(url, {
method, // 如果未提供，当有body时默认为'POST'，否则为'GET'
headers, // 标准JS对象字面量，或Headers实例
body, // 可选，字符串或ArrayBuffer/ArrayBufferView – 即，记得对JSON进行字符串化

// 以及任何其他标准fetch选项，如keepalive等

// 可选，主要用于覆盖AwsClient实例中的选项
aws: {
  signQuery,          // 设为true以签名查询字符串而不是Authorization头
  accessKeyId,        // 与上面AwsClient构造函数中的相同
  secretAccessKey,    // 与上面AwsClient构造函数中的相同
  sessionToken,       // 与上面AwsClient构造函数中的相同
  service,            // 与上面AwsClient构造函数中的相同
  region,             // 与上面AwsClient构造函数中的相同
  cache,              // 与上面AwsClient构造函数中的相同
  datetime,           // 默认为现在，要覆盖请使用'20150830T123600Z'格式
  appendSessionToken, // 设为true以在签名后添加X-Amz-Security-Token，对iot默认为true
  allHeaders,         // 设为true以强制签名所有头部而不是默认头部
  singleEncode,       // 设为true以仅对%2F进行一次编码（通常仅用于测试）
},
})

const response = await fetch(request)

console.log(await response.json())
}

`new AwsV4Signer(options)`

请求的底层签名类 – 如果你只想处理原始AWS4签名的方法/url/头部/body，请使用此类。

import { AwsV4Signer } from 'aws4fetch'

const signer = new AwsV4Signer({
  url,                // 必需，要签名的AWS端点
  accessKeyId,        // 必需，类似于AWS_ACCESS_KEY_ID
  secretAccessKey,    // 必需，类似于AWS_SECRET_ACCESS_KEY
  sessionToken,       // 类似于使用临时凭证时的AWS_SESSION_TOKEN
  method,             // 如果未提供，当有body时默认为'POST'，否则为'GET'
  headers,            // 标准JS对象字面量，或Headers实例
  body,               // 可选，字符串或ArrayBuffer/ArrayBufferView – 即，记得对JSON进行字符串化
  signQuery,          // 设为true以签名查询字符串而不是Authorization头
  service,            // AWS服务，默认在fetch时解析
  region,             // AWS区域，默认在fetch时解析
  cache,              // 凭证缓存，默认为`new Map()`
  datetime,           // 默认为现在，要覆盖请使用'20150830T123600Z'格式
  appendSessionToken, // 设为true以在签名后添加X-Amz-Security-Token，对iot默认为true
  allHeaders,         // 设为true以强制签名所有头部而不是默认头部
  singleEncode,       // 设为true以仅对%2F进行一次编码（通常仅用于测试）
})

`Promise<{ method, url, headers, body }> signer.sign()`

实际执行请求的签名，并返回一个Promise，解析为包含已签名的方法、url、头部和body的对象。

method将是一个String，url将是URL的实例， headers将是Headers的实例， body将保持与您提供给构造函数的参数相同。

import { AwsV4Signer } from 'aws4fetch'

const signer = new AwsV4Signer(opts)

async function sign() {
  const { method, url, headers, body } = await signer.sign()

  console.log(method, url, [...headers], body)
}