一篇文章搞定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教程