跳至主要内容

API整合

一、功能概述​

在整合中心的API整合模組中，您可以管理第三方API的認證設定和API的請求設定，您可以在任何授權的應用中呼叫設定的API以取得資料或推送資料。

除了介面的自訂設定外，API庫中預先建置了100多個常用API範本，組織管理員還可以在組織內新增自訂連線到API庫。

二、入口​

在首頁，點選左側導覽列「整合」按鈕，進入整合中心。

API整合的兩個模組：

  • 我的連接 使用者可以在這裡創建與第三方API的連接並儲存認證、設定介面的請求資訊並授權給應用。
  • API函式庫
    • 公共庫：預設的API連線範本可以直接安裝使用，但連線設定無法更改，只能填寫參數。
    • 組織庫：組織管理員可以將在其組織中創建的 API 連線新增至此處，其他成員可以申請使用它們。

三、設定概述​

步驟1：設定第三方API認證​

一個服務提供者可能有多個接口來提供不同的服務，但是獲取的認證資訊基本上是通用的，比如獲取token只需要獲取一次，並且在有效期內可以調用多個接口，所以在整合中心設定後，相關介面即可進行認證。

部分服務提供者不需要取得其API的認證訊息，因此您可以跳過此步驟並設定下面的步驟2。

步驟2：設定API請求訊息​

使用不同的資料服務需要呼叫不同的接口，每個接口都需要設定相關的輸入參數和接口地址。對於所取得的資料，您需要設定資料的輸出格式以在工作表或工作流中使用。

步驟3：向應用授予授權​

只有授權的應用才能使用整合的 API。

步驟4：使用整合 API​

設定好的連線認證或API可以直接用於以下3種場景：

  • 工作表中的 API 查詢欄位
  • 工作流中的【呼叫整合API】節點
  • 工作流中的【API連線與認證】節點

四、安裝預建API​

API庫中內建了30種常用的API服務，您可以根據需要進行安裝，安裝完成後，您需要做的就是填寫和設定必要的參數值。

以下是安裝和使用範例。

1. 安裝目標API​

進入整合中心，您將看到介面服務的詳細資訊，然後點擊安裝。

2. 設定連接​

到網站註冊服務，申請介面並取得token，然後在這裡填寫並儲存。

3. 啟用所需的API​

一個服務提供者的一個連線中可能有多個介面服務，因此啟用需要的介面。

4. 授予應用授權​

只有授權的應用才能使用連線服務和API。

5. 工作表中的 API 查詢​

轉到應用並新增 API 查詢欄位。

五、第一步：連線與身份驗證​

以下詳細介紹如何設定自訂連線。

1. 新增自訂連接​

進入整合中心，點選【我的連線】> 【+自訂連線】。

2. 選擇身份驗證方法​

根據所需API服務的認證要求選擇認證方式。如果請求URL中不需要或需要API Key認證，則選擇【API Key或無需認證】，點選儲存並繼續。

3. 連接參數​

連線參數是設定認證時依賴的一些身分參數，例如WeCom中取得token需要corpid和corpsecret，這些參數是服務商分配給我們的，直接貼到這裡即可。如果 API 中不需要，則可以不設定連接參數。

從API服務商取得相關資訊後，填寫對應的參數值並儲存（對於已安裝的API服務，只能填入參數值，不能變更參數名稱等資訊）。

  • 參數值可以隱藏，如果隱藏，則參數值被加密，無法顯示。
  • 參數值一旦隱藏，只能修改，不能再顯示。如需查看，請前往服務商平台查看。

連接參數：不僅是獲取token時需要，還可能是調用API時的請求參數，所以這裡填寫服務商的所有基本應用資訊，用於認證或API請求。

4. 基本身份驗證​

此方法意味著每次請求 API 時都需要提供使用者名稱和密碼。

使用者名稱和密碼可以在此處寫入固定值或從設定的連接參數中選擇。

5. OAuth身份驗證​

這樣您就可以獲得 API 請求的Access Token。

  • app_id和app_secret參數預設產生；它們可以被修改或刪除。
  • 參數值可以從連接參數中選擇。
  • 設定完成後點選【取得存取權杖】按鈕進行測試。
  • 根據API服務需求，可以設定過期時間，然後自動取得新的Token。

6. 連接的基本訊息​

您可以設定連接的名稱、Logo和描述。

六、第二步：API請求設定​

認證設定完成後，開始設定API請求。在【API管理】中，點選創建API按鈕開始設定。

主要設定為基本資訊、輸入參數、API請求參數、輸出參數，以及用程式碼區塊處理輸入輸出參數。

1. 基本訊息​

設定API的名稱、描述、圖示和顏色。

2. 輸入參數​

輸入參數用於在工作表或工作流中執行 API 查詢時傳入動態值。傳入後，即可將參數值傳遞給API請求參數。

2.1 參數預設值​

  • 如果不需要該參數且傳入空值，則採用預設值（如果有）。
  • 如果需要參數，則必須有一個值傳入，不需要預設值，但可以設定（不需要參數時使用）。

2.2 參數格式規則​

  • 參數類型：文字、數字、日期和時間、成員、部門、文件、陣列、物件陣列；
  • 無論file欄位中有多少文件，對於傳入的陣列，格式如下： ["URL1","URL2","URL3"...] ，如果需要 URL 字串，請在將其傳遞給 API 請求參數之前使用程式碼區塊對其進行處理。
  • 對於必填參數，在工作表、工作流中使用此介面時傳入的參數不能為空；
  • 是否需要物件陣列：
    • 如果需要物件陣列，則在使用時必須傳入該陣列；如果不需要，使用時不能傳入；
    • 如果需要物件陣列，而子元素沒有設定必填欄位，則使用時可以傳入空陣列；
    • 若物件陣列為必填項，且子元素有必填項，則使用時會檢查傳入的子元素是否有值；
    • 如果不需要物件陣列，但子元素有必填項，則在不傳入物件陣列時，不會檢查子元素的值；傳入陣列時，需要檢查所需的子元素是否有值；
  • 別名規則：僅支援字母、數字、底線、破折號（減號）。
  • 發送API請求時，對於陣列物件的子元素，以別名為key。
  • 可以為參數設定預設值。

3. 插入程式碼​

當傳入的參數的格式或資料不符合API參數的要求時，可以透過程式碼區塊處理，然後傳遞給API參數。 API回傳的結果也可以透過程式碼區塊處理後輸出。

它支援 JavaScript 和 Python。

使用案例：

  • 結合時間戳、金鑰等加密後得到token
  • 傳遞附加圖像時傳遞 URL 字串。
  • 將API傳回的資料封裝成JSON陣列並輸出。
  • 處理API傳回的JSON資料並輸出。

有關程式碼塊節點的更多詳細資訊

4. API請求設定​

設定發送API請求時所需的URL、Query Param、Header、Body等請求參數。

請求中的參數值可以是【連線參數】 、【輸入參數】和【驗證】中的動態值。

設定完成後，點選【測試API】。

有關“發送 API 請求”節點的更多詳細資訊

5. 輸出參數​

執行API請求後，將取得的資料以某種格式輸出，以便工作表欄位或工作流節點可以使用。

其所依據的範例資料是上一個測試步驟中傳回的回應正文中的資料。

設定：JSON解析後將所需的內容加入參數中。有關 JSON 解析節點的更多詳細資訊

6. 發佈API​

設定好輸出參數後，即可發佈API。只有在發佈後才能被工作表或工作流使用。

7. 增加更多API連結​

可以將多個 API 請求新增到單一連線驗證中。

七、第三步：授予應用授權​

對於整合式中心設定的API，您需要設定連接的所有者、錯誤提示以及授權的應用程序，因為應用只有在獲得授權後才能呼叫該API。點選【應用授權】，對應用進行授權。

1. 連接所有者​

連線的擁有者可以修改和查看連線的設定並接收錯誤訊息。

2. 發送錯誤訊息​

呼叫API出錯時是否向所有者發送通知訊息，如果是，可以設定發送的訊息類型以及發送同類型訊息的時間間隔。

3. 授予應用授權​

只能新增和授權本組織的應用程序，授權後應用中的工作表和工作流可以使用API。

八、第四步：如何呼叫整合API​

九、連線和 API管理​

1. 連線管理​

在【我的連接】中，有所有創建的連接，包括設定不完整的連接。組織管理員可以管理組織中的所有連線。

點擊連線名稱，進入該連線的管理頁面，可以繼續設定API和授權、刪除該連線或申請發佈到API庫。

2. API管理​

在某個連線的【API管理】中，管理該連線的所有API，啟用或停用API。

點選某個API可以進一步檢視和管理該API的資訊。

2.1 查看 API 呼叫的連結​

檢查該介面是由哪些工作表和工作流呼叫的。點選工作表或工作流名稱，開啟對應的編輯頁面。

2.2 請求日誌​

查看對 API 的所有呼叫的請求日誌。沒有權限的人無法查看日誌。

請求參數範例：

傳回結果範例：