「Github」是免費架設靜態網頁的好選擇，同時也提供了完善的 API，不必手動操作，用程式就能更新網頁，也能管理 Github 上的所有檔案。本篇整理如何利用 Github API 上傳檔案的流程，並提供前端操作的範例程式碼。
(圖片出處: flickr.com)
一、準備動作
1. API 文件說明
官方說明文件都是英文，直接啃可能會消化不良，可先參考這篇整理：
大概熟悉 API 可做哪些事情之後，可再對照官方原文教程。
2. 取得 Token
「上傳檔案」這個動作需要安全性，因此呼叫 API 得先取得金鑰(Access Token)，操作流程可參考官網說明：
這個頁面有圖文說明應該不難懂，摘要中文重點：
- 先確認 Github 帳號已進行 Email 驗證
- 登入 Github 網頁後，點擊右上角帳號圖示 → Settings
- 點擊左側選單 Developer settings
- 點擊左側選單 Personal access tokens
- 點擊按鈕 Generate new token
- Token descript 隨意填入描述文字
- 下面借用官網的圖，勾選 repo 所有選項即可，其他不用勾選
- 點擊按鈕 Generate token
- 複製產生的 token 字串
- 請好好保存，token 字串只會出現一次，以後不會再出現
- 如 token 遺失，可重新產生 token 即可
二、上傳檔案 API
操作上傳檔案的 API 官網文件在此：
上傳檔案的部分是「Create a file」，操作的語法如下：
PUT /repos/擁有者帳號/目錄/contents/檔案路徑其他重點可參考文件，但我必須說，文件內容非常不完整，除非已經有開發工程師的底子，否則光靠文件根本無法成功操作 API。除了參考其他教學文章，自己也亂試一通才找出成功上傳的方法，因此不如直接看範例程式碼比較快。
三、上傳檔案範例程式碼
製作上傳檔案的按鈕，可參考這篇「自訂 Input File 檔案上傳按鈕 CSS 最佳解法」，取得檔案內容後，接者用 jQuery Ajax 來呼叫 Github API 上傳檔案：
<script src='//ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js'></script>
<script>
var url = "https://api.github.com/repos/wfublog/test/contents/abc.txt?access_token=xxxxxxxxxxxxxxxxxxxxxxx",
data = {
"message": "test", // 檔案的備註資訊
"content": "bXkgbmV3IGZpbGUgY29udGVudHM=" // base64 編碼
};
$.ajax({
type: "put",
url: url,
headers: {
"Content-Type": "application/json" // 指定送出資料為 json 格式
},
data: JSON.stringify(data), // 一定要將物件轉成字串才會被接受
success: function ()json {
console.log("good! " + JSON.stringify(json));
},
error: function ()json {
console.log("error! " + JSON.stringify(json));
}
});
</script>以下一一詳細說明：
- 呼叫 api 的 url 紅色字串：
- "wfublog" 字串換成你的 owner 名稱
- "test" 字串換成你要上傳的目錄
- "abc.txt" 換成你的檔案名稱，也可加上子目錄的路徑，例如 "sub/abc.txt"；如果子目錄不存在，系統會自動建立子目錄。
- "xxxxx...." 換成你的 token 金鑰
- 送出的 data 內容：
- message 參數可隨意填入自己的檔案描述文字
- content 參數即為上傳的檔案內容，必須是 base64 編碼
- 用 jQuery 的 Ajax 呼叫 API 時，要加入 headers 指定送出資料為 json 格式
- 不能直接送出 data 物件，Github API 只能吃字串格式，所以要用 JSON.stringify 把 data 轉成字串
成功送出後，可在 Chrome 開發人員工具看到 console 訊息如下：
返回的物件有各種上傳檔案的相關路徑、其他資訊，可做進一步的後續處理。
四、補充說明
本篇提供的程式碼，僅供學習理解、前端測試之用，千萬不能直接在公開網頁上使用，因為 token 大喇喇被別人看到，你的 Github 權限大開，網頁、檔案所有資料都將不保。
瞭解概念後，請將範例程式碼改為後端執行，不讓 token 曝光才能安心上傳檔案。
更多 相關文章：