类型 吉特拉布语Name 浏览器的SDK, Node.js, and Deno.
目录
特征
- 完成 - GitLab所有被曝光的API的特性都覆盖到版本上 16.5 (中文(简体) )。见 这里 完整名单.
- 通用 - 在所有现代浏览器中工作, 节点.js,以及 德诺。 。 。 .
- 已测试 所有图书馆的测试覆盖率都大于80%.
- 类型 - 所有库都有广泛的TypeScript声明.
使用量
| 浏览器 |
装入 @gitbeaker/rest 直接从 esm.sh (英语)
|
|---|---|
| 德诺 |
装入 @gitbeaker/rest 直接从 esm.sh (英语)
|
| 节点18+ |
安装方式
|
API 客户端
使用您创建的基本符号来证明图书馆 GitLab 简介
const api = new Gitlab({
token: 'personaltoken',
});
可用的即时选择 :
| 名称 | 可选 | 默认 | 说明 |
|---|---|---|---|
host | 对 | https://gitlab.com | Gitlab 实例主机 URL |
token | 对* | 不详 | 个人托肯. 建议(建议3个标志之一) |
oauthToken | 对* | 不详 | (原始内容存档于2018-03-27). OAuth Token. 建议(建议3个标志之一) |
jobToken | 对* | 不详 | CI乔布·托肯. 建议(建议3个标志之一) |
rejectUnauthorized | 对 | true | Http 证书设置, 仅适用于非浏览器发布和 HTTPS 主机 urls |
sudo | 对 | false | 须藤 查询参数 |
camelize | 对 | false | 凸起所有响应体键 |
requesterFn | 没有 | @gitbeaker/ rest & @gitbeaker/cli:基于抓取的,该 @gitbeaker/核心包 没有 存在默认,因此必须明确设定 | 请求图书馆收发器 |
queryTimeout | 对 | 300000 | 查询超时( ms) |
profileToken | 对 | 不详 | 请求配置文件 |
profileMode | 对 | execution | 请求配置文件 |
rateLimits | 没有 | 国防 战争 战斗 | 全球和终点特定可调整费率限额 |
rateLimitDuration | 没有 | 60 | 达到费率限制时的暂停时间 |
* 应提供其中之一,因为大多数API请求需要认证.
扩大的有效载荷
为了简单起见,只有反应体从API方法返回. 然而,看到额外的响应领域,如状态,标题等,可能是有益的. 为此,增加一个可选参数, showExpanded 可以通过大多数 API 方法.
对于返回未粘贴结果的方法,有效载荷具有这种结构:
type ResponseBodyTypes =
| Record<string, unknown>
| Record<string, unknown>[]
| ReadableStream
| Blob
| string
| string[]
| number
| void
| null;
interface FormattedResponse<T extends ResponseBodyTypes = ResponseBodyTypes> {
body: T;
headers: Record<string, string>;
status: number;
}
对于返回被粉碎后结果的方法,有效载荷还包括载于 铺设文件
倾斜
可用的页码选项 :
| 名称 | 密钥集 | 折减 | 类型 | 默认 | 说明 |
|---|---|---|---|---|---|
pagination | 页:1 | 页:1 | "抵消"或"键盘" | "抵消" | 定义应当使用的页形类型 |
perPage | 页:1 | 页:1 | 数目 | 20国 | 每个请求的结果数额 |
orderBy | 页:1 | 字符串 | 哪些领域的结果应该由 | ||
sort | 页:1 | “ asc” 或“ desc” | 亚士克 | 结果的排序方向 | |
maxPages | 页:1 | 数目 | 不详 | 最多应提出请求的数量 | |
page | 页:1 | 数目 | 不详 | 要检索的特定页面 | |
showExpanded | 页:1 | 布尔 | 虚假 | 除数据外随页标信息返回 |
偏移倾斜
对于资源上的任何.all () 函数,它将返回 全部 gitLab提供的物品。 如果有许多项目,这可能会很麻烦,因为请求本身需要一段时间才能完成。 因此,可以通过最大Pages选项来限制所有函数的范围.
import { Gitlab } from '@gitbeaker/rest';
const api = new Gitlab({
host: 'http://example.com',
token: 'personaltoken',
});
let projects = await api.Projects.all({ maxPages: 2 });
您也可以结合 perPage 参数使用此参数, 该参数将取代 Gitlab 设定的每页 30 的默认值 :
import { Gitlab } from '@gitbeaker/rest';
const api = new Gitlab({
host: 'http://example.com',
token: 'personaltoken',
});
let projects = await api.Projects.all({ maxPages: 2, perPage: 40 });
此外,如果您想要获取页码信息, 需要了解总页有多少页, 例如, 通过选项 showExpanded。如果有多种结果,则将包含标记属性如下:
...
const { data, paginationInfo } = await api.Projects.all({
perPage:40,
maxPages:2,
showExpanded: true
});
...
这将导致以这种形式作出反应:
data: [
...
],
paginationInfo: {
next: 4,
current: 2,
previous: 1,
perPage: 3,
}
注:提供任何帕吉化限制都称为密集。 一些资源需要许多要求,这些要求可以给GitLab服务器带来大量负荷。 一般最佳做法是,在不需要所有结果的情况下,规定只返回第一页的页面请求选项.
键集缓存
同样,支持 密钥集映射 可以通过 pagination 参数作为查询选项来切换
const { data } = await api.Projects.all({
pagination: 'keyset',
sort: 'asc',
orderBy: 'created_at',
});
费率限制
速率限制是完全自定义的,用于限制库内连续API请求之间的请求速率. 默认情况下,所有未指定的端点都使用3000 rps的速率限制,而一些端点的速率则要小得多,因为 GitLab 文档。关于默认值,见下文:
const DEFAULT_RATE_LIMITS = Object.freeze({
// Default rate limit
'**': 3000,
// Import/Export
'projects/import': 6,
'projects/*/export': 6,
'projects/*/download': 1,
'groups/import': 6,
'groups/*/export': 6,
'groups/*/download': 1,
// Note creation
'projects/*/issues/*/notes': {
method: 'post',
limit: 300,
},
'projects/*/snippets/*/notes': {
method: 'post',
limit: 300,
},
'projects/*/merge_requests/*/notes': {
method: 'post',
limit: 300,
},
'groups/*/epics/*/notes': {
method: 'post',
limit: 300,
},
// Repositories - get file archive
'projects/*/repository/archive*': 5,
// Project Jobs
'projects/*/jobs': 600,
// Member deletion
'projects/*/members': 60,
'groups/*/members': 60,
});
速率限制可以在即时API包装时被推翻. 为了便于使用,这些限制是使用 glob 模式来配置的,可以有两种格式.
- 带有相应每秒速率的终点缩放
- 结束点的缩写, 指定结束点的具体方法和相应的速率限制的对象
您也可以覆盖 rateLimitDuration 默认值为 60 秒。 这是特定终点在达到速率限制时的超时时间.
const api = new Gitlab({
token: 'token',
rateLimits: {
'**': 30,
'projects/import/*': 40,
'projects/*/issues/*/notes': {
method: 'post',
limit: 300,
},
},
rateLimitDuration: 30,
});
处理错误
请求出错会在纯错误实例中返回, 使用原因来持有原始响应, 以及从 JSON 的响应出错或信件字段中提取的对出错的文本描述, 或其纯文本值 :
class GitbeakerError extends Error {
constructor(
message: string,
options?: {
cause: {
description: string;
request: Request;
response: Response;
};
},
) {
super(message, options);
this.name = 'GitbeakerError';
}
}
注意,信息被分配到反应 statusText,则 请求 财务报告和审定财务报表 回应 类型来自节点JS API.
实例
一旦您的库被即时化, 您可以使用许多 API 的功能 :
使用等待/同步方法
import { Gitlab } from '@gitbeaker/rest';
const api = new Gitlab({
host: 'http://example.com',
token: 'personaltoken',
});
// Listing users
let users = await api.Users.all();
// Or using Promise-Then notation
api.Projects.all().then((projects) => {
console.log(projects);
});
关于所有函数参数的通则 :
- 如果它是一个必需的参数, 它就是函数中的一个命名的参数
- 如果它是一个可选参数,则按照命名参数在选项对象中定义
没错.
import { Projects } from '@gitbeaker/rest';
const projectsAPI = new Projects({
host: 'http://example.com',
token: 'personaltoken',
});
projectsAPI.create({
//options defined in the GitLab API documentation
});
贡献者
这是从一个叉子开始的 节点- gitlab- 遗留 但我最后重写了大部分代码 这是原作的 捐助者。 。 。 .