当前位置：文江博客 Node Package Readme @adobe/fastly-native-promises 中文文档教程

@adobe/fastly-native-promises 中文文档教程

发布于 2 年前浏览 10 项目主页更新于 2 年前

fastly-native-promises

用于 Node.js

Problem

基于回调的fastly 包仍然是最常用的客户端在 NPM 上。但是，我需要一个客户端，它允许我按顺序和并行地执行请求，而不会陷入难以驾驭的回调地狱。 Philipp Schulte 的 fastly-native-promises 客户端看起来几乎是完美的，除了：

it uses Axios, which is an additional dependency we'd like to avoid, especially when running inside Adobe I/O Runtime
it has been missing features and pull requests were merged only slowly

这个分支解决了上述问题但破坏了与浏览器，使其只能在 Node JS 环境中使用。

Solution

fastly-native-promises 包使用基于 promise 的 HTTP 客户端 Request-Promise-Native 执行对 Fastly API 的请求。 Request-Promise-Native 支持原生 JavaScript Promise API 并自动将数据转换为 JSON。每个 fastly-native-promises API 方法都会返回一个 Promise 表示请求完成或失败。

Security
Install
Usage
API
Tests
Contribute
License

Security

您需要一个 Fastly API Token 才能使用 fastly-native-promises 库. 我建议使用 global scope 的令牌，以便能够使用所有 fastly-native-promises API 方法。

Install

这是一个 Node.js 模块，可通过 npm 注册中心。使用 npm install 命令完成安装：

$ npm install @adobe/fastly-native-promises

Changes

参见变更日志。

Usage

const fastly = require('@adobe/fastly-native-promises');

// create one or more instances
const service_1 = fastly('token', 'service_id_1');
const serivce_2 = fastly('token', 'service_id_2');

// make changes

service_1.transact(async () => {
  return this.writeS3('test-s3', {
    name: 'test-s3',
    bucket_name: 'my_corporate_bucket',
    access_key: 'AKIAIOSFODNN7EXAMPLE',
    secret_key: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  });
});


service_2.transact(async () => {
  return this.writeBigquery('test-bq', {
    name: 'test-bq',
    format: '{\n "timestamp":"%{begin:%Y-%m-%dT%H:%M:%S}t",\n  "time_elapsed":%{time.elapsed.usec}V,\n  "is_tls":%{if(req.is_ssl, "true", "false")}V,\n  "client_ip":"%{req.http.Fastly-Client-IP}V",\n  "geo_city":"%{client.geo.city}V",\n  "geo_country_code":"%{client.geo.country_code}V",\n  "request":"%{req.request}V",\n  "host":"%{req.http.Fastly-Orig-Host}V",\n  "url":"%{json.escape(req.url)}V",\n  "request_referer":"%{json.escape(req.http.Referer)}V",\n  "request_user_agent":"%{json.escape(req.http.User-Agent)}V",\n  "request_accept_language":"%{json.escape(req.http.Accept-Language)}V",\n  "request_accept_charset":"%{json.escape(req.http.Accept-Charset)}V",\n  "cache_status":"%{regsub(fastly_info.state, "^(HIT-(SYNTH)|(HITPASS|HIT|MISS|PASS|ERROR|PIPE)).*", "\\\\2\\\\3") }V"\n}',
    user: 'fastly-bigquery-log@example-fastly-log.iam.gserviceaccount.com',
    project_id: 'example-fastly-log',
    dataset: 'fastly_log_test',
    table: 'fastly_logs',
    template_suffix: null,
    secret_key: '-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC7bPG9yaIYd5AL\nmvOaYvNozFJB/VWS53KWBll769kJvlmgMks6r6Xrv8w6rjxWKjZeDrnXVf7UDa0F\nckPPIFvXRxahftWFMGArw0lIvQzgT4/BlndXU5RNxfah/8m7q/GIF6oNYWzfJwvv\nzodxDUqIRH2e2JWidNRjElHuogYHLhV4O/od5pAkfDwak/ihuuh/2VA3Auwb3nph\ndX2F0JBs14oPKZUTYUUSzUQY5IMxSxYUA4Q7W4v21x1EnJt+biXOrERk1rm4ieEE\nU3WkjR5c5gvG8xcWyYod87RNFELmIhCCytI1+t5C3Em/jPsQFtLzwHpbNhdW4oEm\nn7d06n75AgMBAAECggEAWRh26lNZfOwJS5sDRlbXgu/uAnSdI1JmxC6Mhz4cVGdq\nT57Y6DLrWuA4A4UkJYm3gorZiSXWF5PQthAVb/bf8bxXY7nZYpEWhnc09SD5aAAq\nREp0vMx8aWQ709K2YUJg+zDUo7u2d3YmVH8HH5TD43c7iDFJIIsNE3N4A0p+NxZ+\nw06FFW+fz/etrWiNyhrlTsbkMbSgU+GpFFBq1pCd0ni5d1YM1rsaAaUpmkwdjgjL\noDs+M/L/HtqfEhyZNdw8JF7EJXVE1bIl7/NL0rBInhyO28FcB56t/AG5nzXKFI/c\nc+IO7d6MOOqiGRLRWZItEpnyzuV8DZo461wy1hSvqQKBgQDhSsg2cHkTrtBW8x0A\n3BwB/ygdkkxm1OIvfioT+JBneRufUPvVIM2aPZBBGKEedDAmIGn/8f9XAHhKjs8B\nEsPRgE206s4+hnrTcK7AeWWPvM9FDkrkQCoJFuJrNy9mJt8gs7AnnoBa9u/J4naW\ne1tfC8fUfsa7kdzblDhcRQ8FhwKBgQDU+N4kPzIdUuJDadd6TkBbjUNPEfZzU5+t\nIike2VSRhApxAxviUnTDsTROwJRzKik9w7gIMka8Ek+nmLNMEtds77ttcGQRdu16\n+vT1iualiCJe+/iMbl+PiJtFwhEHECLU9QfgBVS6r2lDAlZA+w6nwCRiidlrObzO\nCXqVOzN3fwKBgAsrOuu//bClHP0ChnCReO38aU+1/gWnDiOOnKVq0DXhAiaOzD1P\nqAG6hZlEkFBDMPWzq62doKv+gPgpRkfmV0DenHuYnGrrHdG3p2IxYoCSuq/QupPA\nPpU+xjDMhpQI30zuu4/rQq+/yDl4+aoSKYB3xAtb0Zxg6dMU8QpZ/hmnAoGBAIFu\nIesbcQR7O8FGkMrmxZweNNrYCtQ57R/WU/FImWm6OnJGNmsMO6Q2jJiT12RKKjg8\nOxrYGz7vTfOIDOddyAiPhXPUSyyF/3uvCrIzUUsmeeUJ8xq9dVwQ5HS3pYuKVfDg\nXYHbG4w9UJaF1A+3xEdUsYglSLouo7z/67zH9tZXAoGBAKpsdjSd3R+llaAv2HQ8\nGMlN92UTr5i9w++QMXq4qspH5NEYqz3NHbKuYthZqxEsRUZbRP50eDWU4jvxFVJl\nLBFINp6B+3AsIme0YCyOaleB/Cy0347miSinSv2I6QiH6dQxHdHzrG+x1evS/76f\nKT0KS+ySjCAEWgg4v+mjUDUV\n-----END PRIVATE KEY-----\n',
    response_condition: '',
  });

  // optional, but speeds up end of process
  await service_1.discard();
  await service_2.discard();
});

Promises

清除活动版本的所有域：

Get all the versions.
Filter out the active version.
Get all the domains for the active version.
Purge all the domains.
Log the status text for each purge request.

const fastly = require('fastly-native-promises');

const service = fastly('token', 'service_id');

function handler() {
  service.readVersions()
    .then(versions => {
      const active = versions.data.filter(version => version.active)[0];
      return service.readDomains(active.number);
    })
    .then(domains => {
      return Promise.all(domains.data.map(domain => service.purgeIndividual(domain.name)));
    })
    .then(purges => {
      purges.forEach(purge => console.log(purge.statusText));
    })
    .catch(e => {
      console.log('Shoot!');
    });
}

Async/Await

如果值小于 5000 毫秒，则更新每个后端和服务的 first_byte_timeout 属性：

Get all the services associated with the Fastly API token.
Filter out the service IDs.
Iterate over all services synchronously.
Get all the versions.
Filter out the active version.
Get all the backends for the active version.
Filter out the affected backends.
Continue with the next service if there are no affected backends.
Clone the active version.
Update all the affected backends parallelly.
Activate the cloned version.

const fastly = require('fastly-native-promises');

const account = fastly('token');

async function handler() {
  try {
    const services = await account.readServices();
    const ids = services.data.map(service => service.id);

    for (const id of ids) {
      const service = fastly('token', id);
      const versions = await service.readVersions();
      const active = versions.data.filter(version => version.active)[0];
      const backends = await service.readBackends(active.number);
      const affected = backends.data.filter(backend => backend.first_byte_timeout < 5000);

      if (!affected.length) continue;

      const clone = await service.cloneVersion(active.number);
      await Promise.all(affected.map(backend => service.updateBackend(clone.data.number, backend.name, { first_byte_timeout: 5000 })));
      await service.activateVersion(clone.data.number);
    }
  } catch (e) {
    console.log('Shoot!');
  }
}

Response Schema

每个 fastly-native-promises API 方法返回以下内容响应对象：

{
  // the HTTP status code from the server response
  status: 200,

  // the HTTP status message from the server response
  statusText: 'OK',

  // the headers that the server responded with
  headers: {},

  // the options that were provided to request for the request
  config: {},

  // the request that generated the response
  request: {},

  // the response that was provided by the server
  data: {}
}

Retrieving Request Statistics

Fastly 实例有一个 requestmonitor 属性，可用于检索请求统计信息：

requestmonitor.count for the total number of requests.
requestmonitor.remaining for the number of requests remaining according to Fastly's API Rate limit for the hour or undefined (if no modifying requests have been made yet).
requestmonitor.edgedurations for an array of API processing durations (in milliseconds, measured from the edge).
requestmonitor.durations for an array of request durations (in milliseconds, measured from the client, i.e. including network latency).

使用 requestmonitor.stats 您可以获得所有这些在一个对象中，包括所有请求的最小、最大和平均持续时间。

Guarding against Rate Limits

使用 requestmonitor.remaining 属性，您可以确保在达到速率限制之前仍有足够的请求。

使用 instance.transact 方法时，您可以进一步提供必要的可用请求限制的最小值，以便在初始克隆版本后，如果超过 API 速率限制，则不会发出其他请求. 这允许您在出现速率限制问题时快速失败。

High-Level Helpers

虽然大多数功能是 Fastly API 的低级包装器，但我们在 Fastly 实例的属性中提供了几个高级辅助函数。

Conditions Helper in `fastly.conditions`

条件助手简化了条件的创建和管理。

const fastly = require('fastly-native-promises');

const instance = fastly('mykey', 'service-config');

const update = fastly.conditions.update(1, 'REQUEST', 'Created as an Example', 'example');

const conditions = await update('req.url.basename == "new.html"', 'req.url.basename == "index.html"');

console.log('Created a condition matching index.html with following name', conditions['req.url.basename == "index.html"'].name);

fastly.conditions.update 可以通过参数version（服务配置版本）、type（条件类型，REQUEST< /code>、RESPONSE 或 CACHE）、comment（将在 Fastly UI 中显示的注释）、nameprefix< /code>（条件名称的通用前缀）以获取执行更新的新函数 update。

当使用 VCL 条件语言中的 statements 列表调用 update 时，它将把传入的条件列表与 Fastly 服务配置中已经存在的条件同步。共享相同 nameprefix 但不再使用的所有条件将被删除，将创建尚不存在的新条件（不触及未更改的条件，减少更新时发出的请求数).

update 的返回值是一个将条件语句映射到条件对象的对象。这允许在其他 Fastly API 调用中重用条件。

Header Helper in `fastly.headers`

标头助手简化了条件标头的创建和管理。

const fastly = require('fastly-native-promises');

const instance = fastly('mykey', 'service-config');

const update = fastly.headers.update(
  1,
  'REQUEST', // apply a request condition
  'Created as an Example', // use following comment for conditions
  'example', // name-prefix for all generated conditions and headers
  'set', // set the header
  'http.Location' // which header (Location)
  'request' // in the request handling
  );

await update(
    {
      condition: 'req.url.basename == "new.html"',
      expression: '"https://new.example.com"',
    },
    {
      condition: 'req.url.basename == "index.html"',
      expression: 'https://www.example.com',
    });

fastly.headers.update 可以通过参数version（服务配置版本），type（条件类型，REQUEST< /code>、RESPONSE 或 CACHE）、comment（将在 Fastly UI 中显示的注释）、nameprefix< /code>（条件名称的通用前缀）、action（对标头做什么，可以是set、append，或者delete), header (header 的名称——记得在值中包含 http.), sub （应用header的子程序，可以是request，fetch，cache，或者response）得到执行更新的新函数 update。

当 update 被一个 objects 列表调用时，看起来像 { condition: 'req.url ~ "foo/(.*)/bar"', expression : '"bar/" + re.group.1 + "/foo"'}，即 condition（在 VCL 条件语言中）和 expression 对code>（也是有效的 VCL），它将同步传入的标头列表（和结果条件）与 Fastly 服务配置中已经存在的标头和条件。共享相同 nameprefix 但不再使用的所有条件和标头将被删除，将创建尚不存在的新条件和标头（不会触及未更改的条件和标头，从而减少更新时发出的请求数）。

API

Classes

AccountAPI : AccountAPI: Fastly 账户 API。
AuthAPI : AuthAPI: 快速验证 API。
DomainAPI : DomainAPI: Fastly 域 API。
HealthcheckAPI : HealthcheckAPI: 快速健康检查 API。
PurgeAPI : PurgeAPI: 快速清除 API。
Conditions: 具有状态管理高级操作的助手类。
Headers: 具有状态管理高级操作的助手类。
Fastly

Functions

repeat(responseOrError) ⇒ boolean: 确定响应或错误是否表明响应是可重复的。

Typedefs

CreateFunction ⇒ Promise

创建特定类型资源的函数。如果那个资源 name 已经存在，它将拒绝返回的错误承诺。

UpdateFunction ⇒ Promise

更新特定类型的现有资源的函数。如果不存在该名称的资源，它将拒绝返回的承诺并出错。

ReadFunction ⇒ Promise

检索特定类型资源表示的函数。如果不存在该名称的资源，它将拒绝返回的承诺并出错。

ListFunction ⇒ Promise

检索特定类型资源列表的函数。

FastlyError : object

FastlyError 类描述了可能发生的最常见的错误使用 Fastly API 时。使用 error.status，底层可以检索 HTTP 状态代码。已知的错误状态代码包括：

400: attempting to activate invalid VCL
401: invalid credentials
404: resource not found
409: confict when trying to POST a resource that already exists
422: attempting to modify a service config that is not checked out
429: rate limit exceeded, try again later

Response : object

Versions : object

描述最相关的服务版本。

DictUpdate : object

指定字典更新操作。在大多数情况下，upsert 是最好的方法更新值，因为它适用于现有和不存在的项目。

Snippet : object

VCL : object

AccountAPI : `AccountAPI`

Fastly 账户 API。

种类：全局类
参见：https:

AccountAPI : AccountAPI
- .readCurrentUser() ⇒ Promise
- .readUsers() ⇒ Promise
- .readUser(id) ⇒ Promise
- .createUser(name, login) ⇒ Promise
- .readInvitations() ⇒ Promise
- .createInvitation(email, role) ⇒ Promise
- .acceptInvitation(acceptCode, name, password) ⇒ Promise
- .deleteInvitation(id) ⇒ Promise

//docs.fastly.com/api/account#top

accountAPI.readCurrentUser() ⇒ `Promise`

获取当前登录的用户。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https://docs.fastly.com/api/account#user_91db9d9178f3f4c7597899942bd3f941

accountAPI.readUsers() ⇒ `Promise`

获取当前客户的所有用户列表。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https://docs.fastly.com/api/account#customer_12f4a69627ba3bbb1c8668aae03a60ad

accountAPI.readUser(id) ⇒ `Promise`

获取指定id的用户。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
id	`string`	The User ID.

//docs.fastly.com/api/account#user_15a6c72980b9434ebb8253c7e882c26c

accountAPI.createUser(name, login) ⇒ `Promise`

创建一个用户。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
name	`string`	The user name.
login	`string`	The user login.

//docs.fastly.com/api/account#user_00b606002596bac1c652614de98bd260

accountAPI.readInvitations() ⇒ `Promise`

列出所有邀请。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https://docs.fastly.com/api/account#invitations_6d8623de97ed7e50b7b6498e374bb657

accountAPI.createInvitation(email, role) ⇒ `Promise`

创建邀请。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Default	Description
email	`string`		The email address for the invitation.
role	`string`	`"engineer"`	The user role. Defaults to {@code engineer}.

//docs.fastly.com/api/account#invitations_8c4da3ca11c75facd36cfaad024bd891

accountAPI.acceptInvitation(acceptCode, name, password) ⇒ `Promise`

接受邀请。

种类：AccountAPI
的实例方法 Returns：Promise - 表示完成或失败的响应对象。

Param	Type	Description
acceptCode	`string`	The accept code retrieved in the email.
name	`string`	Name for the new user.
password	`string`	Password for the new user.

accountAPI.deleteInvitation(id) ⇒ `Promise`

删除邀请。

种类：AccountAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
id	`string`	The invitation id.

//docs.fastly.com/api/account#invitations_d70a7460c7e1bd8dd660c6f5b3558c2e

AuthAPI : `AuthAPI`

Fastly Auth API。

种类：全局类
参见：https:

AuthAPI : AuthAPI
- .readTokens([customerId]) ⇒ Promise
- .readToken([id]) ⇒ Promise
- .deleteToken([id]) ⇒ Promise
- .createToken(options) ⇒ Promise

//docs.fastly.com/api/auth#top

authAPI.readTokens([customerId]) ⇒ `Promise`

列出客户的所有令牌。

种类：AuthAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
[customerId]	`string`	The id of the customer.

//docs.fastly.com/api/auth#tokens_d59ff8612bae27a2317278abb048db0c

authAPI.readToken([id]) ⇒ `Promise`

获取指定id的token。如果缺少 Id，则返回自身令牌。

种类：AuthAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
[id]	`string`	The token id.

//docs.fastly.com/api/auth#tokens_bb00e7ed542cbcd7f32b5c908b8ce244

authAPI.deleteToken([id]) ⇒ `Promise`

删除具有指定 id 的令牌。

种类：AuthAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
[id]	`string`	The token id.

//docs.fastly.com/api/auth#tokens_4a958ba69402500937f0d8570f7ce86f

authAPI.createToken(options) ⇒ `Promise`

创建 API 令牌。

种类：AuthAPI
的实例方法返回：Promise - 表示完成或失败的响应对象。
参见：https:

Param	Type	Description
options	`object`	The token options.

//docs.fastly.com/api/auth#tokens_db4655a45a0107448eb0676577446e40

DomainAPI : `DomainAPI`

Fastly Domain API。

种类：全局类
参见：https:

DomainAPI : DomainAPI
- .domainCheck(version, name) ⇒ Promise
- .domainCheckAll(version) ⇒ Promise
- .readDomains(version) ⇒ Promise
- .readDomain(version, name) ⇒ Promise
- .readServiceDomains([serviceId]) ⇒ Promise
- .createDomain(version, name, comment) ⇒ Promise
- .updateDomain(version, oldName, name, comment) ⇒ Promise
- .deleteDomain(version, name) ⇒ Promise

//docs.fastly.com/api/config#domain