iT邦幫忙

2021 iThome 鐵人賽

DAY 22
0
IT管理

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

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

以「查詢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)

 

參考


上一篇
【Day 21】Google Apps Script - API Blueprint 篇 - API Blueprint 介紹
下一篇
【Day 23】Google Apps Script - API Blueprint 篇 - Google Docs 轉換 API Blueprint 格式(1)
系列文
「Google Apps Script」 學習筆記30

尚未有邦友留言

立即登入留言