# tgit-api [![NPM Version](https://img.shields.io/npm/v/tgit-api)](https://www.npmjs.com/package/tgit-api) 腾讯工蜂 RESTful API 的 NodeJS 封装，以简化调用方式和提供 Typescript 类型系统。 其中请求库是使用的 [`axios`](https://github.com/axios/axios)，重试库使用 [`async-retry`](https://github.com/zeit/async-retry)。 ## Install ```shell npm install --save tgit-api ``` ## Usage ```javascript const tgitApi = require('tgit-api'); const api = tgitApi(token, requestOptions, { retries: 5, onRetry: (e, attemptNo) => { console.log(` Tgit API retry: this is the ${attempt} time. Error message: ${e.message} API url: ${e.config.url} `); } }, { baseURL: "https://git.code.tencent.com/api/v3" }) tgitApi.catch = async (err) => { const status = err.response && err.response.status; if (status === 401) { // Unauthorized // Fetch a new token and retry tgitApi.token = await getTGitToken(); } throw err; }; ;(async () => { const res = await api.projects({ page: 1, per_page: 10, order_by: 'create_at', sort: 'asc' }) })() // 可以运行时改变 token 的值 api.token = "another_token"; ``` - `token` **必填参数**，是工蜂提供的票据，可以是 `private token`，也可以是 OAuth2 的 `access_token`。 - `requestOptions` **可选参数**，是会透传给 `axios` 请求库的，[相关参数 API 可以在这里查询](https://github.com/axios/axios)。其中 `url`、`method`、`data` 参数请不要传，仓库内已经适配好，只需按需修改其他参数即可，如 `timeout` 等。 - `retryOptions` **可选参数**，如果不传则默认不重试。 - `retries`：最大重试次数。默认值为 `10`。 - `factor`：指数因子。默认值为 `2`。 - `minTimeout`：距第一次重试间隔（毫秒）。默认值为 `1000`。 - `maxTimeout`：两次重试间最大时长。默认值为 `Infinity`。 - `randomize`：是否在 1 到 2 间随机选择指数因子。默认值为 `true`。 - `onRetry`：重试实施后的回调函数，可选。回调函数的第一个参数是上一次尝试失败抛出的错误信息。 ## 0.15.3 升级 0.16.0 及以上 需要在初始化的时候，加上 `baseURL` 参数： ### 0.15.3 调用方式 ```js tgitApi(token) ``` ### 0.16.0 调用方式 ```js tgitApi(token, undefined, undefined, { baseURL: "path_to_api" }) ``` ## 0.65.0 及以上 支持在初始化的时候，传入 axios 实例： ```js import axios, { AxiosInstance, AxiosRequestConfig } from 'axios'; // 创建 axios 实例，配置太湖网关信息 const axiosInstance: AxiosInstance = axios.create({ baseURL: 'https://api-s-idc.sgw.woa.com/ebus/gitcode/git_code_api/api/v3', // 请求超时时间 timeout: 10000, }); // 配置拦截器 axiosInstance.interceptors.request.use((config: AxiosRequestConfig) => { const timestamp = Math.ceil(Date.now() / 1000); const nonce = String(Math.ceil(Math.random() * 99999999)); // 添加请求头 config.headers.common['x-rio-paasid'] = 'your paasid'; config.headers.common['x-rio-timestamp'] = timestamp; config.headers.common['x-rio-nonce'] = nonce; config.headers.common['x-rio-signature'] = 'sha256 signature'; return config; }); const api = tgitApi(token, null, null, { // 优先使用 axiosInstance 配置的 baseURL，所以这里可以传空或者不传 baseURL: '', axiosInstance }); ``` ## API | 方法 | 说明 | |-----|-----| namespaces|获取命名空间列表 groups|获取项目组列表 groups.add|新建项目组 groups.get|获取项目组的详细信息以及项目组下所有项目 groups.delete|删除项目组 groups.members|获取项目组成员列表 groups.members.add|增加项目组成员 groups.members.modify|修改项目组成员 groups.members.delete|移除一个项目组成员 users|获取用户信息列表 users.add|新增用户 users.get|获取某个用户的账号信息 users.fromEmail|通过邮箱获取用户信息 users.modify|修改用户 users.delete|删除用户 users.keys|获取某个用户的SSH key users.keys.add|给指定用户创建一个 SSH key users.keys.delete|删除指定用户的 SSH key users.emails|获取指定用户邮箱列表 users.emails.add|给指定用户添加邮箱 users.emails.delete|删除指定用户的邮箱 users.block|锁住用户 users.unblock|取消锁住用户 users.identity|创建认证方式 self|当前认证用户 owned|获取用户拥有的项目列表 watched|获用户关注项目列表 keys|获取当前用户的SSH key keys.add|给当前用户创建一个SSH key keys.get|获取某个指定的 SSH key keys.delete|删除当前用户的 SSH key emails|获取用户邮箱列表 email.add|添加邮箱 emails.get|获取邮箱信息 emails.delete|删除当前用户的邮箱 issues|用户创建缺陷列表 projects|获取项目列表 projects.owned|获取用户拥有的项目列表 projects.public|获取所有公有项目列表 projects.innerSource|获取内源项目列表 projects.add|创建项目 projects.addTo|创建属于某个指定用户的项目 projects.get|获取项目详细信息 projects.modify|编辑项目 projects.delete|删除项目 projects.issues|项目缺陷列表 projects.issues.add|新建缺陷 projects.issues.get|查看指定缺陷 projects.issues.modify|修改缺陷 projects.issues.subscribe|订阅给定项目的某个缺陷 projects.issues.unsubscribe|取消订阅给定项目的某个缺陷 projects.issues.isSubscribe|判断是否订阅给定项目的某个缺陷 projects.issues.notes|获取缺陷评论列表 projects.issues.notes.add|在项目的新增缺陷评论 projects.issues.notes.get|查询单个缺陷的评论 projects.issues.notes.modify|修改项目的缺陷评论 projects.labels|获取标签列表 projects.labels.add|新增标签 projects.labels.modify|修改标签 projects.labels.delete|删除标签 projects.milestones|返回里程碑列表 projects.milestones.add|新增里程碑 projects.milestones.get|返回指定里程碑 projects.milestones.modify|编辑里程碑 projects.milestones.delete|删除里程碑 projects.milestones.issues|返回某个里程碑下的所有缺陷 projects.watchers|关注者列表 projects.watch|关注项目 projects.unwatch|取消关注项目 projects.isWatch|是否关注给定项目 projects.stars|获取标星项目列表 projects.star|对指定项目标星 projects.unstar|取消对指定项目标星 projects.isStar|查看对指定项目是否标星 projects.archive|下载存档的项目版本库 projects.archive.add|将项目归档 projects.archive.delete|将项目取消归档 projects.contributors|获取贡献者列表 projects.raw|获取原始文件内容 projects.blob|获取 blob 原始内容 projects.compare|获取差异内容 projects.files|获取版本库文件和目录列表 projects.files.add|新增文件 projects.files.get|获取单个文件内容和信息 projects.files.modify|编辑文件 projects.files.delete|删除文件 projects.branches|分支列表 projects.branches.add|创建项目分支 projects.branches.get|获取分支详情 projects.branches.delete|删除分支 projects.branches.protect|将分支变为保护分支 projects.branches.protected_branch_rules|将分支变为保护分支(新)-必须指定所在的规则组 projects.branches.unprotect|取消保护分支 projects.branches.lifecycle|查看分支生命周期 projects.branches.merge_base|获取2个分支的Base Commit点 projects.protected.members|获取保护分支的成员 projects.protected.members.all|获取项目有权限的成员列表 projects.protected.members.add|为保护分支添加成员 projects.protected.members.modify|编辑保护分支的成员 projects.protected.members.delete|删除保护分支的指定用户 projects.tags|TAG列表 projects.tags.add|创建TAG projects.tags.get|获取指定TAG projects.tags.delete|删除TAG projects.commits.statuses|新建检测结果 projects.commits.statuses.get|查询检测结果 projects.commits.status|通过Ref查询组合的检测结果 projects.commits|列出项目版本库所有的提交 projects.commits.get|取的一个提交 projects.commits.diff|取得提交的差异 projects.commits.refs|获取某个提交对应的分支和tag projects.commits.comments|取得一个提交的评论 projects.commits.comments.add|对一个提交发表评论 projects.members|获取项目成员列表 projects.members.add|增加项目成员 projects.members.get|获取项目内的某个指定成员信息 projects.members.modify|修改项目成员 projects.members.delete|删除项目成员 projects.events|查询项目的事件列表 projects.fork|Fork 项目 projects.forkFrom|将项目 Fork 到另外一个命名空间 projects.fork.delete|删除 Fork 关系 projects.hooks|查询项目回调钩子列表 projects.hooks.add|给项目增加回调钩子 projects.hooks.get|查询项目单个回调钩子 projects.hooks.modify|编辑项目回调钩子 projects.hooks.delete|删除项目回调钩子 projects.merge_requests|获取合并请求列表 projects.merge_requests.add|新增合并请求 projects.merge_requests.get|查询项目合并请求 projects.merge_requests.getByIid|根据iid查询项目合并请求 projects.merge_requests.changes|查询合并请求详情 projects.merge_requests.merge|合并合并请求 projects.merge_requests.modify|更新合并请求 projects.merge_requests.subscribe|订阅请求合并 projects.merge_requests.unsubscribe|取消订阅合并请求 projects.merge_requests.isSubscribe|查询是否有订阅请求合并 projects.merge_requests.comments|获取合并请求评论列表 projects.merge_requests.comments.add|添加合并请求的评论 projects.merge_requests.commits|获取项目中某个指定合并请求的提交列表 projects.merge_requests.conflict.merge|查询合并请求是否存在冲突 projects.merge_requests.notes|查询合并请求的评论列表 projects.merge_requests.notes.add|创建合并请求的评论 projects.merge_requests.notes.get|查询合并请求的评论列表 projects.merge_requests.notes.modify|编辑合并请求的评论 projects.merge_request.create_pre_merge_commit|产生MR预合并点 projects.merge_request.revert|回退合并请求 projects.merge_requests.review|查询评审信息 projects.merge_requests.review.invite|邀请评审人 projects.merge_requests.review.dismissals|移除评审人 projects.merge_requests.review.cancel|取消评审 projects.merge_requests.review.summary|发表评审意见 projects.merge_requests.review.reopen|重新打开评审 projects.releases|获取releases列表 projects.releases.get|获取某个指定的release projects.releases.add|新增一个release projects.releases.modify|更新一个release projects.releases.delete|删除releases projects.releases.attachments.add|上传附件 projects.releases.attachments.get|下载附件 projects.releases.attachments.delete|删除附件 projects.shares.get|获取项目的 share group 列表 projects.tloc.daily.count|统计功能：按天查询提交次数、提交用户数 projects.tloc.daily.diff|统计功能：按天查询提交代码行增量 projects.tloc.user.diff|统计功能：查询各用户提交增量 projects.tloc.lang.diff|统计功能：查询各语言提交增量 projects.tloc.commit.diff|统计功能：查询指定Commit点的提交增量 projects.tloc.file.diff|统计功能：查询文件的提交情况 projects.tloc.commit.list|统计功能：查询Commit列表 projects.tloc.users.diff|统计功能：查询指定用户代码提交增量 projects.tloc.users.lang|统计功能：查询指定用户各语言提交增量 projects.reviews|日常代码评审：获取项目中所有的Commit评审 projects.reviews.notes|日常代码评审：获取某个指定代码评审的评论 projects.review|日常代码评审：用iid获取项目中某个具体的Commit评审情况 projects.review.get|日常代码评审：用id获取项目中某个具体的Commit评审情况 projects.review.invite|日常代码评审：邀请评审人 projects.review.batch_invite|日常代码评审：批量邀请评审人 projects.review.dismissals|日常代码评审：移除评审人