利用 Github API 上傳檔案﹍操作範例心得整理

「Github」是免費架設靜態網頁的好選擇，同時也提供了完善的 API，不必手動操作，用程式就能更新網頁，也能管理 Github 上的所有檔案。

本篇整理如何利用 Github API 上傳檔案的流程，並提供前端操作的範例程式碼。

(圖片出處: flickr.com)

一、準備動作

1. API 文件說明

官方說明文件都是英文，直接啃可能會消化不良，可先參考這篇整理：

• 一篇文章搞定Github API 调用

大概熟悉 API 可做哪些事情之後，可再對照官方原文教程。


2. 取得 Token

「上傳檔案」這個動作需要安全性，因此呼叫 API 得先取得金鑰(Access Token)，操作流程可參考官網說明：

• Creating a personal 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 官網文件在此：

• REST API v3 Contents

上傳檔案的部分是「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 曝光才能安心上傳檔案。

更多 相關文章：