tgit-api

腾讯工蜂 RESTful API 的 NodeJS 封装，以简化调用方式和提供 Typescript 类型系统。

其中请求库是使用的 axios，重试库使用 async-retry。

Install

npm install --save tgit-api

Usage

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 可以在这里查询。其中 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 调用方式

tgitApi(token)

0.16.0 调用方式

tgitApi(token, undefined, undefined, {
    baseURL: "path_to_api"
})

0.65.0 及以上

支持在初始化的时候，传入 axios 实例：

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|日常代码评审：移除评审人