一篇文章搞定Github API 调用 (v3）

时间  2019-11-06
标签 一篇 文章 搞定 github api 调用 v3 栏目 Git 繁體版
原文   原文链接
对于经常使用Github的用户来讲，常常有一些自动化的需求。好比个人需求是定时备份Github的issues和comments到本地。如下为Github的API的使用参考。

v3版API的文档连接
v3版API的官方教程javascript

基本访问路径 (Root Endpoints)

一开始读文档的时候，照着它的事例直接在命令行里curl，或者在InSomnia或Postman软件里访问，都完美显示200状态。但是一旦把连接里改写成本身的用户名就各类显示404无页面。还觉得是受权问题，而后在页头HEADER中按照各类方式试了username和token密钥，都没用仍是404。结果发现，原来不是方法的问题，纯粹是连接地址没写对！
实际上只是读取的话，彻底不用任何受权，能够在命令行、Insomnia、网页等各类状况下直接输入连接访问任何人的全部公开信息。
而后对照官方路径列表Root Endpoints获得的连接，好像怎么访问都不对。反而在Stackoverflow中看到的一个连接，顺藤摸瓜本身发现了各类正确的访问路径，总结以下：java

  • 首先！访问的连接最后不能有/。如https://api.github.com/users/solomonxie是能够访问到我我的信息的，可是https://api.github.com/users/solomonxie/就不行了，惟一不一样是多了一个/.
  • 其次！不一样于通常URL访问，GIthub的API访问连接是区分大小写的！
  • 我的主要信息。 https://api.github.com/users/用户名,获得数据以下图：

image

  • 我的全部repo。https://api.github.com/users/用户名/repos。会获得一个repo的JSON格式列表。
  • repo详细信息。https://api.github.com/repos/用户名/仓库名。repo的路径就开始和我的信息不一样了。
  • 获取某个repo的内容列表。https://api.github.com/repos/solomonxie/gists/contents，注意这只会返回根目录的内容。
  • 获取repo中子目录的内容列表。https://api.github.com/repos/solomonxie/gists/contents/目录名。必定要注意这里必定要彻底遵循原文件名的大小写，不然没法得到信息。若是是更深层的内容，则在连接列按照顺序逐级写上目录名称。
  • 获取repo中某文件信息（不包括内容）。https://api.github.com/repos/solomonxie/gists/contents/文件路径。文件路径是文件的完整路径，区分大小写。只会返回文件基本信息。
  • 获取某文件的原始内容（Raw）。1. 经过上面的文件信息中提取download_url这条连接，就能获取它的原始内容了。2. 或者直接访问：https://raw.githubusercontent.com/用户名/仓库名/分支名/文件路径
  • repo中全部的commits列表。https://api.github.com/repos/用户名/仓库名/commits。
  • 某一条commit详情。https://api.github.com/repos/用户名/仓库名/commits/某一条commit的SHA
  • issues列表。https://api.github.com/repos/用户名/仓库名/issues。
  • 某条issue详情。https://api.github.com/repos/用户名/仓库名/issues/序号。issues都是以1,2,3这样的序列排号的。
  • 某issue中的comments列表。https://api.github.com/repos/用户名/仓库名/issues/序号/comments。
  • 某comment详情。https://api.github.com/repos/用户名/仓库名/issues/comments/评论详情的ID。其中评论ID是从issues列表中得到的。

查询参数 (Parameters)

若是在上面基本连接中加入查询条件，那么返回的数据就是filtered，过滤了的。好比要求只返回正在开放的issues，或者让列表数据分页显示。经常使用以下：python

  • 分页功能。格式是?page=页数&per_page=每页包含数量。

如https://api.github.com/users/solomonxie/repos?page=2&per_page=3git

  • issues状态。格式是?state=状态。

如https://api.github.com/repos/solomonxie/solomonxie.github.io/issues?state=closedgithub

权限认证 Authentication

首先须要知道都是，到此为止以前全部都查询都是不须要任何权限的，给个地址就返回数据，全公开。
可是建立文件、更新、删除等就是必须用本身的帐号"登陆"才能实现的。因此为了下面的增删改作准备，须要先看一下权限问题。
官网虽然写的很简答，不过若是不熟悉API的话仍是不能立刻就理解。

经常使用的认证方法有三种，Basic authentication, OAuth2 token, OAuth2 key/secret
三种方法效果同样，可是各有其特色和方便之处。选哪一种就要看本身哪一种方便了。api

认证方法一：Basic authentication

这种最简单，若是是用curl的话，就：app

curl -u "用户名:密码" https://api.github.com

若是是用Insomnia等api调试工具的话，直接在Auth选项栏里选Basic Auth，而后填上用户名密码便可。curl

认证方法二：OAuth2 token

关于token

这种token方式，说实话若是不是操做过API或深度了解REST的话，是很难理解的东西。
说白了就是 第二个密码，你既不用处处泄露本身的用户名密码，又能够专门给这个"第二密码"设置不一样须要的权限，若有的只可读有的还能够写等。并且这个“第二密码”是既包括用户名又包括密码功能的，全站只此一个绝对不会和别人重复。初次以外，你还能够设置不少个token，也就是第3、第4、第五...密码。很方便。

设置token方法

就位于github我的帐号设置->开发者设置->我的token里。建立一个新token时，能够选择具体的权限，建立成功时必定要复制到本地哪里保存，只会让你看见一次，若是忘记的话就须要从新生成（其实丢了也不算麻烦）。
imageide

另外！注意：工具

token字符串不能存储在github的repo中，通过测试，一旦提交的文件中包含这个token字符串，那么github就会自动删除这个token -_-! 我用了好久才明白过来，建立的Personal Access Token老是自动消失，还觉得是有时限的。

用token经过权限认证

有两种传送方法，哪一种均可以：

  1. 做为url中的参数明文传输：
curl https://api.github.com/?access_token=OAUTH-TOKEN
  1. 做为header中的参数传输：
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

若是不是用curl而是Insomnia测试的话，和上面basic auth是大同小异的，很容易操做就不复述了。
到此为止，权限认证就算搞清了，并且也实际验证过有效了。强烈建议用insomnia工具操做，有GUI界面方便理解，成功后再转为curl或python等程序语言。

认证方法三：OAuth2 key/secret

这个是除了Personal Access Token以外的另外一种好用的方法，即建立本身的OAuth app，而后获得一对client_id和client_secret。以下：
image
image
获得这两个值以后，直接在访问任何api的url链接后面显性加上这两个参数便可完成认证，如：
https://api.github.com/users/yourusername?client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET
可是：

目前这种认证方式 不支持查询之外的操做，也就是只能GET获取某些api信息，不能执行request里的任何PUT/PATCH/DELETE操做。

建立新文件 Create content

Contents操做 官方文档
  • 传输方法：PUT
  • 访问路径：https://api.github.com/repos/用户名/仓库名/contents/文件路径
  • JSON格式：
{
  "message": "commit from INSOMNIA",
  "content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}

JSON填写以下图：
image

  • 注意：1.必须添加权限验证（上面有写） 2. 数据传送格式选择JSON 3. 文件内容必须是把文件总体转为Base64字符串再存到JSON变量中 4. 文件路径中若是有不存在的文件夹，则会自动建立

起初无论怎么尝试都一直报一样都错误，400 Invalid JSON，以下图：
[图片上传失败...(image-884e71-1527903120996)]

最后发现原来是犯了很小很小都错误才致使如此：
image
原来，个人token看似是正常的，惟独错误的是，多了一个空行！也就是说，标明都是invalid JSON，结果没注意居然是invalid Token!

增长文件成功后返回的消息：
image

更新文件 Update content

主要这几点： 1. 传送方式用 PUT 和建立文件同样 2. 须要权限验证，3. 传输内容数据用JSON 4. 须要指定该文件的SHA码 4. 路径和访问content时同样 5. 文件内容必须是把文件总体转为Base64字符串再存到JSON变量中
  • 传输方法：PUT
  • 访问路径：https://api.github.com/repos/用户名/仓库名/contents/文件路径
  • JSON格式：
{
  "message": "update from INSOMNIA",
  "content": "Y3JlYXRlIGZpbGUgZnJvbSBJTlNPTU5JQQoKSXQncyB1cGRhdGVkISEhCgpJdCdzIHVwZGF0ZWQgYWdhaW4hIQ==",
  "sha": "57642f5283c98f6ffa75d65e2bf49d05042b4a6d"
}
  • 注意：必须指定该文件的SHA码，至关于文件的ID。

SHA虽然是对文件的惟一识别码，至关于ID，可是它是会随着文件内容变化而变化的！因此必须每次都从新获取才行。

至于获取方式，验证后发现，目前最靠谱的是用前面的get content获取到该文件的信息，而后里面找到sha。

对上传时的JSON格式另有要求，若是没有按照要求把必填项输入，则会出现422错误信息：
image

或者若是用错了SHA，会出现409错误消息：
image

若是正确传送，就会显示200完成更新：
image

删除文件 Delete content

  • 传输方法：DELETE
  • 访问路径：https://api.github.com/repos/用户名/仓库名/contents/文件路径
  • JSON格式：
{
  "message": "delete a file",
  "sha": "46d2b1f2ef54669a974165d0b37979e9adba1ab2"
}

删除成功后，会返回200消息：
image

增删改issues

若是作过了上面文件的增删改，这里大同小异，不一样的访问路径和JSON的格式而已。惟一不一样的是，issues是不用把内容转为Base64码的。

参考连接：github官方文档

增长一条issue

  • 传输方法：POST
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues
  • JSON格式：
{
  "title": "Creating issue from API",
  "body": "Posting a issue from Insomnia"
}
  • 注意：issue的数据里面是能够加label，milestone和assignees的。可是必须注意milestone和assignees必须是已有的名次彻底对应才行，不然没法完成建立。

更改某条issue

  • 传输方法：PATCH
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/序号
  • JSON格式：
{
  "title": "Creating issue from API ---updated",
  "body": "Posting a issue from Insomnia \n\n Updated from insomnia.",
  "state": "open"
}
  • 注意：若是JSON中加入空白的labels或assignees，如"labels": []，做用就是清空全部的标签和相关人。

锁住某条issue

不容许别人评论（本身能够）
image

  • 传输方法：PUT
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/序号/lock
  • JSON格式：
{
  "locked": true,
  "active_lock_reason": "too heated"
}
  • 注意：active_lock_reason只能有4种值可选：off-topic, too heated, resolved, spam，不然报错。

另外，成功锁住，会返回204 No Content信息。

解锁某条issue

  • 传输方法：DELETE
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/序号/lock
  • 无JSON传输

增删改comments

参考 官方文档

增长comment

  • 传输方法：POST
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/序号/comments
  • JSON格式：
{
  "body": "Create a comment from API"
}

更改comment

  • 传输方法：PATCH
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/comments/评论ID
  • JSON格式：
{
  "body": "Create a comment from API \n\n----Updated"
}
  • 注意：地址中，issues后不用序号了，由于能够经过惟一的评论ID追查到。查看评论ID的方法，直接在上面查询连接中找。

删除comment

  • 传输方法：DELETE
  • 访问路径：https://api.github.com/repos/用户名/仓库名/issues/comments/评论ID
  • 无传输数据
相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程