如何透過API讀取/寫入資料到工作表

niio 為有開發能力的使用者提供API介面，方便使用者將外部資料寫入工作表或從工作表中讀取資料。

一、使用案例

您的應用中創建了一個訂單管理工作表，用於管理線上和離線訂單。還有另一個銷售系統，每當客戶在線上下訂單時，它都會透過工作表的 API 直接將新的訂單資料寫入訂單管理工作表。

二、API說明

應用管理員點選【API文件】可以查看應用中的所有API。

三、授權說明

平台採用基於token的認證方式，因此AppKey和SecretKey需要由系統管理員取得，或者可以重新產生。

四、欄位和控制類型

欄位ID：系統自動為欄位產生的ID，不可修改，透過API寫入資料時需要欄位ID來表示欄位。

欄位名稱：應用管理員為該欄位設定的名稱。

類型：欄位的控制類型。

元件編號：使用的元件的編號，通常在傳遞參數時使用。對於不同類型的元件，過濾可能會有所不同。

說明：該欄位的使用說明。

工作表別名和欄位別名：由於工作表ID和欄位ID是一長串字符，不易記憶和書寫，因此可以為工作表和欄位設置別名，用於傳遞參數。

五、新增資料介面

應用中針對不同的應用場景提供了10多個介面。以下是創建新資料的範例，即透過API向工作表新增資料。

六、規則

API請求位址：https://niiodemo.apsm.com.tw/api/v2/open/worksheet/addRow
對於參數 appkey、sign、worksheetid、controls 和 controlId，您可以使用右側已提供的值。參數名稱不需要修改，是根據工作表自動產生的，測試時只需要修改參數值。

請求範例（可以複製並使用）

{
  "appKey": "9d2e1434b94b9c48",
  "sign": "MmM2ZTdmNWU1MzU1YTRjOWU4ZWMxMWE3NWU5OTRlNzA3OTdjNGRmNjQ2OGEzYzFiODBjM2I0OTgzZDY5YjVlYg==",
  "worksheetId": "ceshi",
  "controls": [
    {
      "controlId": "6674d8a26f6a78ef82056f2c",
      "value": "文本"
    },
    {
      "controlId": "ownerid",
      "value": "8b88cc23-4f2c-49bd-bb0d-429df19740ff"
    }
  ],
  "triggerWorkflow": true
}

響應參數及返回資料範例

{
  "data": "rowId",
  "success": true,
  "error_code": 1
}

可能的錯誤

錯誤代碼	描述
0	失敗
1	成功
10001	缺少參數
10002	參數值不正確
10005	無權限操作
10007	資料不存在
10101	請求令牌不存在
10102	簽名不合法
99999	資料操作異常

線上測試

這裡我們透過一個簡單的線上API測試來模擬外部資料的寫入。

線上 API 測試：https://hoppscotch.io。您也可以使用其他 API 測試工具。

將API請求位址貼到輸入框中
選擇【Post】
選擇【Body】
選擇【application/json】作為內容類型
將上面的範例請求程式碼貼到編輯框中
點擊發送
如果為 "success": true ，則表示寫入成功。刷新工作表即可查看 API 創建的新資料。

七、相關參數取得方法

測試時，可以先取得一個固定的參數值，例如視圖ID和行資料ID（rowId）。

1. 資料ID（rowId）

進入工作表並開啟目標資料的詳細資料頁面。

rows/ 和 ? 之間的內容連結中是資料 ID。

截圖中取得的資料ID：

27a00b14-d1c0-483d-a57c-ec07fdedf35f

2. 查看ID

需要視圖 ID 才能取得資料清單。

一、使用案例​

二、API說明​

三、授權說明​

四、欄位和控制類型​

五、新增資料介面​

六、規則​

七、相關參數取得方法​

1. 資料ID（rowId）​

2. 查看ID​