本篇要解決的問題
前一篇寫了 用 GitHub API 來取得 Issue、Comments,而這一篇是使用 API 來建立 Issue、Comment,讓使用者能夠在頁面上新增留言。
要新增 Issue、Comments 的 API 很簡單,麻煩的是取得具有權限的 token
。
August 研究了一下後,找到 2 種取得 token
的方法:
- 後台建立一組 Personal access tokens。
- 後台建立 GitHub Apps,使用者登入 App 後就可以取得每一次可使用的 Token。
本篇會寫的是第一種方法:Personal access tokens。
另一個方法 GitHub Apps 的部份在這篇:GitHub App。
本篇主要的參考文件來自於 GitHub 官方說明:Create an issue、Create an issue comment。
Create Issue / Comment API
使用 API 的方式很簡單,因為要傳送資料,因此是用 POST。
Create Issue URL
https://api.github.com/repos/{owner}/{repo}/issues
Create Issue Comment URL
https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}/comments
owner
、repo
、issue_number
這三個值在前一篇 取得 Issue、Comment 的部份有說明過了,這邊就不再重寫。
POST 時要有 header
及 body
。
header
要帶入二個值:
Accept application/vnd.github.v3+json
Bearer 有權限的Token
有權限的 Token
就是本篇跟下一篇的主要內容。
body
有幾個值可以帶入,都是我們在 Issue 頁面上會看到的:
title: Issue 的標題。
body: Issue 的內文,支援 Markdown。
Create Issue 時才會用到 title
,且 title
為必填。
Create Comment 只需要 body
,且 body
為必填。
body
都支援 Markdown,因為 GItHub 的 Issue 跟 Comment 都是可以寫 Markdown 的。
另外還有 milestone
、labels
、assignees
,但這三個都必須要具備權限,而且之後拿 Issue 當留言功能時也用不到,這邊就不使用,有興趣的朋友請自行看 文件說明。
使用 API 的程式碼範例如下:
Create an issue API
Create an issue comment API
目前使用 API 的 URL、body 都沒問題了,剩下的就是如何取得 token
。
Personal access token
取得 Token 的第一種方法,就是直接到 Github 後台建立一組 Personal access token。
直接點擊這個連結:GitHub Developer Settings
或是進到 GitHub 後點擊 Settings 進到個人帳號設定,接著左側選單點擊 Developer setting,再點擊 Personal access token,會看到像以下的頁面:
點擊「Generate new token」後,會進到產生一組 token 的頁面:
Note 是給自己看的,提示自己這組 token 是用在什麼地方。
Select scopes 就是選擇這組 token 可以擁有什麼權限。
如果我們要讓這組 token 可以在公開的專案中建立 Issue、發佈 Comment,那只需要勾選「public_repo」。
如果想讓這組 token 也可以在私人的專案中建立 Issue、發佈 Comment,那就整個「repo」都要勾選。要注意的是,這邊的私人專案是指我們建立這個 token 的帳號所擁有的專案,無法用到路邊的任何一個私人專案上。
Note 跟 Select scopes 都選好了後,滑到頁面底部點擊「Generate Token」,就會看到頁面上顯示了一組 token 出來:
token 的權限之後都可以再更改。
Personal access tokens 注意事項
有了 Personal access tokens 後,替換掉第一段範例程式碼的 取得的Token
就可以使用了。
所以,用 Personal access tokens 的方式要注意的就是:
token 不要外流!token 不要外流!token 不要外流!
用了 token 打 API,到時 Issue、Comment 上顯示的就是你 GitHub 的帳號,等於是我們授權這組 token 來替我們的帳號發聲。
如果外流出去,就容易被拿來做惡意使用。
這也就是為什麼這一篇 August 不製作 Demo 的原因。
用 Personal access tokens 的方式建議是在後端使用,因為寫在前端一定都是明碼,防無可防。