使用gitlab API

动机

gitlab是一个类似于github的配置管理服务, 目前已经有丰富的Hook服务和API服务, 能够很好的支持持续集成. 本文介绍了笔者是如何开始使用gitlab提供的API的. 需求比较简单, 取得gitlab上一个repo的某一个文件的内容.

准备

gitlab API的使用可以参考你所使用的gitlab服务上的帮助文档.

帮助文档已经比较完善了. gitlab有多种语言版本的client支持, 这里我们使用最直接的http方式. 文档上给除了如下的例子

GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U

和

curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"

这两个例子分别列举了token作为参数, 和作为Header是的使用方法. 在我们的程序中, 我们只需要选择一种自己觉得方便的方式就可以了. 这里我选择用参数的方式加载token.

token作为用户调用api的唯一标识, 在账户的profile下可以找到

实践

这里我使用自己比较熟悉的python语言和其requests扩展包来作为示例

• 通过查阅api的帮助文档, 我们可以推断出, 想访问某个项目的内容, 首先需要知道这个项目的id.
  查阅api文档, 发现列举项目的api如下

GET /projects

其返回一个Json形式的数据组.

所以编写如下的脚本取得当前用户能够访问的所有项目信息

import requests
url = 'http://gitlab.myserver.com/api/v3/projects?private_token=XXXXXX&per_page=50'
r = requests.get(url)

data = r.json
for i in data:
    if i[u'name']=='Snack-Cherry':
        print i[u'id']    

• gitlab API的返回值大多是分页的, 这里将页面的内容扩展为50个(项目). 如果当前用户可以访问的项目太多, 以至于超过页面容量, 那么在返回值里因为默认返回一页, 可能就找不到想找的项目
• 这里我们在屏幕上打印了"Snack-Cherry" 这个项目的id

• 找到了project id, 我们就可以使用这个id来访问指定的项目了.

GET /projects/:id/repository/files

使用如下的代码

url = http://gitlab.myserver.com//api/v3/projects/24948/repository/files?private_token=xxxx
r = requests.get(url)
print r.text

但是我们得到了如下的输出

u'{"message":"400 (Bad request) \\"file_path\\" not given"}'

原来是有两个参数忘记加上了.重新修改url如下

url = 'http://gitlab.myserver.com//api/v3/projects/24948/repository/files?private_token=XXXXX&file_path=myfolder/myfile.txt&ref=master'

这样我们就得到指定的文件了.

• 解析文件内容.

data = r.json['content']
print data

结果我们得到了一堆如下的文字:

'KioqIFNldHRpbmdzICoqKgpTdWl0ZSBTZXR1cCAgICAgICDlhbP...

这是为什么呢? 在API说明上我们可以找到答案:
Note that file content is Base64 encoded.

所以我们还需要将内容转换成UTF-8或者其他可以输出的形式:

import base64
print base64.b64decode(data)

可以看到屏幕上打出了文件的内容.

总结

gitlab API的文档已经比较详实, 读者可以自行选择语言进行调用. 细节问题可以仔细阅读文档寻找答案.