@accedo/accedo-one-express 中文文档教程

Question

The Accedo One Express middleware

   _                    _           ___
  /_\   ___ ___ ___  __| | ___     /___\_ __   ___
 //_\\ / __/ __/ _ \/ _` |/ _ \   //  // '_ \ / _ \
/  _  \ (_| (_|  __/ (_| | (_) | / \_//| | | |  __/
\_/ \_/\___\___\___|\__,_|\___/  \___/ |_| |_|\___|

Summary

这是 Express 的官方 Accedo One 中间件。

[Accedo One SDK] for Javascript(https://github.com/Accedo-Products/accedo-one-sdk-js/) 提供了一种使用 Accedo One API 的简单方法。 这个中间件提供了额外的好处，并在 Express 应用程序的上下文中使事情变得更加容易。

我们遵循语义版本控制，您可以在此处。

Compatibility

这个中间件是用 ES6 编写的（使用 CommonJS 模块而不是 ES6 模块）。

这应该从版本 4 开始工作，但我们测试并建议使用最新的 LTS 版本的 Node（目前是 Node 6，很快是 Node 8）。

对于较早的 Node 版本，您可以尝试向 ES5 引入编译步骤（例如通过 Babel 或 Buble）。 请注意，我们没有对此进行测试，并且强烈建议不要使用已弃用的 Node 版本，因为它们可能缺少重要的安全修复程序。

关于 Express，我们支持版本 4 并对其进行测试。

Features

继承自 Accedo One SDK for Javascript 的功能：

• easy access to Accedo One APIs
• automatic deviceId creation when none was provided
• automatic session creation when none was provided (lazy - only when needed)
• automatic session re-creation when the existing one has expired (lazy)
• ensures only one session will be created at a time, even if a request triggers concurrent Accedo One calls

此 Express 中间件提供的额外功能：

• automatic creation of Accedo One client instances for each request, attached to the response object for further use
• automatically passes the requester's IP onto Accedo One calls for analytics and geolocated services
• automatic reuse of the deviceId through cookies (can be customized to use anything else based on requests)
• automatic reuse of the sessionKey through cookies (can be customized to use anything else based on requests)

注意当您使用中间件时，您还应该 配置 Express 以正确处理代理，因为我们依赖它提供给我们的 IP。 请务必阅读 Express 文档，以及下面的注释。

例如：app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])

Documentation

What	Link
The Accedo One Express middleware (this project)	https://accedo-products.github.io/accedo-one-sdk-express/
The Accedo One JS SDK	https://accedo-products.github.io/accedo-one-sdk-js/
The Accedo One REST APIs	https://developer.one.accedo.tv

每个 Express 响应都关联到一个 Accedo One 客户端实例，在 中找到res.locals.accedoOneClient（当 res 是响应变量名时）。

要查找这些实例上可用的方法，请参阅上面列出的 Accedo One JS SDK 的 API 文档。

REST API 的文档也列为 Accedo One，其中定义了特定术语。

Installation

Your preferred CLI tool	Command
Yarn	yarn add @accedo/accedo-one @accedo/accedo-one-express
NPM	npm install --save @accedo/accedo-one @accedo/accedo-one-express

然后您可以获得默认导出以使用中间件：

Method	Code
CommonJS	const accedoOne = require('@accedo/accedo-one-express')
ES6 Module	import accedoOne from '@accedo/accedo-one-express'

Examples

Use the middleware to persist deviceId and sessionKey via cookies

const accedoOne = require('@accedo/accedo-one-express');
const express = require('express');

const PORT = 3000;

express()
// handle proxy servers if needed, to pass the user's IP instead of the proxy's. Read more about this further.
.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])
// place the accedoOne middleware before your request handlers
.use(accedoOne({ appKey: '56ea6a370db1bf032c9df5cb' }))
.get('/test', (req, res) => {
   // access your client instance, it's already linked to the deviceId and sessionKey via cookies
   res.locals.accedoOneClient.getEntryById('56ea7bd6935f75032a2fd431')
   .then(entry => res.send(entry))
   .catch(err => res.status(500).send('Failed to get the result'));
})
.listen(PORT, () => console.log(`Server is on ! Try http://localhost:${PORT}/test`));

另请参阅上面链接的文档中的示例。

SDK development

• Clone/fork this repo
• Run yarn (install it first if needed)
• Develop !
• Before pushing, remember to:
  • add tests and check they all pass (npm test)
  • document any public API with JSDoc comments and generate the new doc (npm run doc)

More information & Links

• Accedo One homepage
• Accedo One API documentation

On the Express trust proxy setting, and propagating the right IP

当向 Accedo One 发送请求时，此中间件将在 x-forwarded-for (XFF) 标头中设置传入请求 IP（我们称之为 ∑）。 ∑的值就是Express决定的用户IP。

1/ Express 在未设置信任代理时使用传入连接 IP 正常运行。 因此，它将 ∑ 设置为用户直接访问时的正确 IP，以及用户访问时代理（或 CDN 等）的 IP。

您希望避免报告任何代理的 IP，因为这会阻止 Accedo One 的分析和地理定位功能可靠地工作。

2/ 将信任代理设置为 true（或启用它，做同样的事情）时，行为会发生变化。 现在，∑ 的值将是传入请求的 XFF 标头中给出的第一个值。 “第一个值”是最左边的值。 所以我们要说的是，我们信任每一个代理，并且 XFF 中的任何内容都是可信的，所以我们选择第一个设置的值（当每个人都表现得很好并尊重该顺序时，这是用户的 IP）。 另请注意，如果没有 XFF 标头，则连接的 IP 用作后备（这很好！这意味着我们可以处理 CDN 和直接连接）。

3/ 将信任代理设置为 CSV 或 IP 数组时，这些 IP 是我们信任的代理。 所以 Express 查看 XFF 最右边的 IP，它与任何受信任的代理都不匹配：这将是第一个“不受信任”的 IP，我们认为在这之前出现的任何东西都是垃圾。 在这种情况下，最右边的不受信任 IP 用作 ∑ 的值。 同样，如果没有 XFF，则使用连接 IP。

总之，我们建议将 trust proxy 值设置为信任 loopback、linklocal、uniquelocal、AND 在运行 accedo-one-express 的服务器之前，属于代理/CDN 网络一部分的所有 IP。 根据您的基础架构，有时将信任代理设置设置为 true 或使用自定义函数通过自定义策略恢复正确的 IP 可能更合适。

Unit Tests

Mocha（与 Chai）单元测试已被编写以涵盖从该模块导出的所有 API。 请按照以下步骤运行它们：

• Follow the Getting Started steps above.
• Run npm test

License

请参阅LICENSE 文件以了解许可权利和限制 (Apache 2.0)