【Day 22】Google Apps Script - API Blueprint 篇 - API Blueprint 格式範例 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2021 iThome 鐵人賽

DAY 22

IT管理

「Google Apps Script」學習筆記系列第 22 篇

【Day 22】Google Apps Script - API Blueprint 篇 - API Blueprint 格式範例

13th鐵人賽 google app script

Jason Hung

2021-10-07 19:31:16

2099 瀏覽

分享至

以「查詢Gamil資訊」API 文件為範例，介紹 API Blueprint 格式 —— 這是一個簡單的 API，允許查看 Jason Gmail 信箱的前 5封信。

今日要點：
》API Blueprint 格式介紹

API Blueprint 格式介紹

創建 Blueprint 的第一步是指定 API 名稱和 Metadata。此步驟如下所示：

Metadata

Blueprint 從 Metadata 部分開始。

HOST: https://script.google.com
FORMAT: 1A

在本例中，我們指定 FORMAT 的值為 1A。FORMAT 關鍵字表示 API blueprint 的版本，版本的資訊可以參考這裡，如下圖紅色虛框的地方：

API Name & Description

Blueprint中的第一級標題 # 後面就是 API 的名稱，之後就是 API 描述，可以用 markdown 的語法寫。不過通常我們會先用 Group 來包起來。
　

Resource Groups (資源群組)

在標題# 後使用 Group 關鍵字，可以建立了一組相關資源。

# Group API文件Demo

Resource (資源)

就是指單一個 API，像在 Group API文件Demo 資源群組中，我們有一個名為 查詢Gmail資訊 的資源。此資源允許查看 Jason Gmail 信箱的前 5封信。標題末尾的方括號內，是的資源訪問的 URI。

## 查詢Gmail資訊[/macros/s/AKfycbyLOQLi_p2I2y0TQ4IrQ8vV53rtMSRdunWLqFJB5pBhHG9frBOf7rKB0Yunfl6x1twr/exec{?name,func}]

Actions(動作)

API Blueprint 允許我們指定可能對資源執行的每個操作。一個動作是用資源內的子標題指定的，該子標題後跟 HTTP 方法的動作名稱。

### try:查詢Gmail資訊 [GET]

一個動作應該至少包含一個來自服務器的響應，它必須包含一個狀態代碼並且可能包含一個正文。響應被定義為操作中的列表項。列表是通過在列表項前面加上 a、* 或 - 創建的。

此操作會返回 200 狀態代碼和 JSON 正文。

+ Response 200 (application/json)

URI Template(模板)

就是上面方括號裡 URI 中的 {?name,func}
　

URI Parameters(參數)

URI Parameters應該使用參數表來描述 URI。對於 查詢Gmail資訊，它將如下所示：

Parameters
- name: Jason (string, optional) -查詢人的姓名
- func: getGmailInfo (string, required) - 要呼叫的功能名稱

完整的範例

API描述的部份我稍微精簡一點，閱讀起來不會太長。

HOST: https://script.google.com
FORMAT: 1A

# 鐵人賽 2021 
## Version
v1.0


# Group API文件Demo

## 查詢Gmail資訊 [/macros/s/AKfycbyLOQLi_p2I2y0TQ4IrQ8vV53rtMSRdunWLqFJB5pBhHG9frBOf7rKB0Yunfl6x1twr/exec{?name,func}]
<table>
    <tr>
        <th>Docs Demo</th>
        <th>getGmailInfo</th>
        <th>查詢Gmail資訊</th>
    </tr>
    <tr>
        <td>說明</td>
        <td colspan=2> 使用 Google Apps Script 查詢 Gmail 資訊。</td>
    </tr>
</table>

### try:查詢Gmail資訊 [GET]
+ Parameters
    + name: Jason (string, optional) -查詢人的姓名
    + func: getGmailInfo (string, required) - 要呼叫的功能名稱

+ Response 200 (application/json)