JavaScript REST 客户端和用于智能云 API的 utils
🚧 新客户端文档可用:关于新的命令模式客户端(β),参见 新城区 (MD)
这是什么?
这个项目包含一个RIST客户端,用于Clever Cloud的API和一些utils.
我怎么用这个?
首先,需要安装Node.js模块:
pnpm install @clevercloud/client
我们建议使用 爱 以确保您依赖与我们相同的节点.js & pnpm 版本(定义于 mise.toml) (中文(简体) ).
所有API REST路径都可以作为"服务"中组织的"功能"访问. 一个服务功能的调用将只是准备 HTTP 请求,并通过承诺返回对象中的请求参数. 它不会认证请求,也不会发送.
您需要链接一些助手到函数调用:
- 指定 API 主机( prod, preprod...)
- 添加正确的认证头( oAuth v1 或其他...)
- 用您最喜欢的 lib/ code 发送 HTTP 请求
- 用您最喜欢的 lib/ code 处理响应
这些帮助者已准备好用于浏览器或节点.js和oAuth v1签名认证. 推荐的方法是把这些帮助者包裹在您的应用程序的一个位置,并在需要发送API呼叫的地方重新使用.
以下是使用带有 oAuth v1 签名的 ECMAScript 模块并使用 fetch API 发送请求 .
在文件中,显示此函数 :
import { addOauthHeader } from '@clevercloud/client/esm/oauth.js';
import { prefixUrl } from '@clevercloud/client/esm/prefix-url.js';
import { request } from '@clevercloud/client/esm/request.fetch.js';
export function sendToApi (requestParams) {
// load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com'
const tokens = {
OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
}
return Promise.resolve(requestParams)
.then(prefixUrl(API_HOST))
.then(addOauthHeader(tokens))
.then(request);
// chain a .catch() call here if you need to handle some errors or maybe redirect to login
}
注:如果您的工程依赖于特定的 REST 库( xios, jQuery...) , 您必须写出自己的请求功能, 将参数插入到您的 lib 中, 而不是使用 request.fetch.js。 。 。 .
然后,在您的应用程序的任何文件中,直接导入您需要的 API 函数( 它有助于树摇动), 调用它并添加一个 .then(sendToApi) 像这样:
import { getAllEnvVars } from '@clevercloud/client/esm/api/v2/application.js';
import { sendToApi } from '../send-to-api.js';
const envVars = await getAllEnvVars({ id: oid, appId }).then(sendToApi);
注意: 它返回承诺, 您可能想要使用 await 带着它.
我怎么才能得到OAuth配置?
建议在下列日期编写一般性文件: 我们的网站。 。 。 . 如文件所指出:
你需要在聪明的云层控制台上创建一个OAuth消费者代币. 点击"创造...",然后点击组织名称下的"Oauth消费者". 所有创建的消费者都将出现在应用程序和附加物的列表下.
一旦你得到消费者,你仍然需要生成 AAuth 代币。 你可以在浏览器里跳整个Auth舞.
如果你使用 聪明的工具 CLI,您也可以使用以下命令生成符号 :
clever login
一旦成功登入,您将获得一个标志/秘密夫妇.
日志流和事件 API 流 (v2)
从智能云获取日志
此流以 SSE 内源曝光 component-emitter一个很小的lib 执行一个API 紧密匹配两个 EventTarget 从DOM和 EventEmitter 从Node.js.
这里有一个如何使用的例子 LogsStream 从应用程序取回活日志 :
// Browser implementation or Node.js implementation
import { LogsStream } from '@clevercloud/client/esm/streams/logs.browser.js';
// import { LogsStream } from '@clevercloud/client/esm/streams/logs.node.js';
// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};
// Create a LogsStream instance (filter and deploymentId are optional)
const logsStream = new LogsStream({ apiHost: API_HOST, tokens, appId, filter, deploymentId });
// Listen to "log" events
logsStream.on('log', (rawLogLine) => console.log(rawLogLine));
// Open the stream
logsStream.open();
从智能云获取事件
此流以 WebSocket 内源 曝光 component-emitter一个很小的lib 执行一个API 紧密匹配两个 EventTarget 从DOM和 EventEmitter 从Node.js.
这里有一个如何使用的例子 EventsStream 从智能云平台检索事件:
// Browser and Node.js 21+ implementation
import { EventsStream } from '@clevercloud/client/esm/streams/events.js';
// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};
// Create an EventsStream instance (appId is optional)
const eventsStream = new EventsStream({ apiHost: API_HOST, tokens, appId });
// Listen to "event" events
eventsStream.on('event', (rawEvent) => console.log(rawEvent));
// Open the stream
eventsStream.open();
处理错误
当源流发生出错( 网络失败, 认证错误...) 时, 出错事件 :
stream.on('error', (error) => console.error(error));
- 默认情况下,当检测出网络故障时,会出错并自动关闭流.
- 如果启用自动重试行为,当检测到网络故障时,不会出错.
- 如果您启用自动重试行为并设置最大次数的重试, 它会释放出错误 .
详见"自动重试行为"部分. .
关闭溪流
你可以随时关闭溪流 这样:
stream.close();
它不会将事件听众从流实例中移除,这样你就可以轻松地重新打开.
自动重试行为
当你打电话 .open() 在溪流上,它无法抵御默认的网络故障.
我们有一个选入的自动重试行为 来处理这些, 你可以启用它 当你打开溪流 这样:
stream.open({ autoRetry: true });
使用乒乓球系统检测出网络故障. 当检测出这种故障并启用自动重试行为时,源流会被关闭并自动尝试一个新的开口.
你可能不需要,但你可以听与这种自动重试行为相关的事件:
// "close" event is emitted each time a network failure is detected (or any unknown error not related to authentication)
stream.on('close', (reason) => console.log('Stream closed because of', reason));
// "open" event is emitted on first .open() call and each time a new open is attempted
stream.on('open', () => console.log('Stream open...'));
// "ping" event is emitted each time a ping is received from the source stream
stream.on('ping', () => console.log('Received ping'));
启用后, 自动重试行为将遵循无限指数回放模式 . 您可以更改默认的计时和此类重试的最大次数 :
stream.open({
autoRetry: true,
// Factor used to compute exponential backoff delays, defaults to 1.25
backoffFactor: 1.5,
// First iteration timeout in ms, also used to compute exponential backoff delays, defaults to 1500
initRetryTimeout: 2000,
// Maximum number of consecutive iterations the auto retry behaviour can do, defaults to Infinity
maxRetryCount: 6,
});
日志流 (v4)
import { ApplicationLogStream } from '@clevercloud/client/esm/streams/application-log.js';
// Load and cache config and tokens
const API_HOST = 'https://api.clever-cloud.com';
const tokens = {
OAUTH_CONSUMER_KEY: 'your OAUTH_CONSUMER_KEY',
OAUTH_CONSUMER_SECRET: 'your OAUTH_CONSUMER_SECRET',
API_OAUTH_TOKEN: 'your API_OAUTH_TOKEN',
API_OAUTH_TOKEN_SECRET: 'your API_OAUTH_TOKEN_SECRET',
};
// Create an EventsStream instance (appId is optional)
const logsStream = new ApplicationLogStream({
apiHost: API_HOST,
tokens,
ownerId: 'YYY',
appId: 'XXX',
// optionnal auto retry config
// retryConfiguration: {
// enabled: true,
// backoffFactor: number,
// initRetryTimeout: number,
// maxRetryCount: number,
// },
// optionnal logs request params
// since: Date,
// until: Date,
// service: string[],
// limit: number,
// deploymentId: string,
// instanceId: string[],
// filter: string,
// field: string[],
// throttleElements: number,
// throttlePerInMilliseconds: number,
});
logsStream
.on('open', (event) => console.debug('stream opened!', event))
.on('error', (event) => console.error('error', event.error))
.onLog((event) => console.log(event.data.date, event.data.message));
logsStream.start();
// You can also pause the stream
logsStream.pause();
// And resume it
logsStream.resume();
许可证
本项目根据以下规定获得许可证: 阿帕奇 - 2.0。 。 。 .