动机
gitlab是一个类似于github的配置管理服务, 目前已经有丰富的Hook服务和API服务, 能够很好的支持持续集成. 本文介绍了笔者是如何开始使用gitlab提供的API的. 需求比较简单, 取得gitlab上一个repo的某一个文件的内容.
准备
gitlab API的使用可以参考你所使用的gitlab服务上的帮助文档.
gitlab.png
帮助文档已经比较完善了. 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下可以找到
token.png
实践
这里我使用自己比较熟悉的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的文档已经比较详实, 读者可以自行选择语言进行调用. 细节问题可以仔细阅读文档寻找答案.
