集成中心-API集成介紹
功能概述
在集成中心的API集成模塊,可以統一管理第三方API的鑒權認證配置和API接口的請求配置,經過授權的應用都可以直接調用配置好的API來獲取數據或推送數據。
除瞭自定義配置接口外,在API庫中,平臺還預置瞭100多個常用的API模闆,組織管理員也可以將自定義的連接添加到組織下的API庫。
入口
在平臺主頁,點擊左側導航欄下方的“集成中心”按鈕,進入集成中心管理頁麵。
API集成分兩個模塊:
-
我的鏈接
在這裏可以創建第三方API的連接並保存鑒權認證、配置接口請求信息和授權給相關應用。
-
API庫
-
公共庫: 由平臺預設的API鏈接模闆,可以直接安裝使用,但是API連接配置不能更改,隻能填充參數。
-
組織庫: 組織管理員可以將組織內創建的API鏈接添加到組織庫,其他成員可以申請使用。
-
使用流程簡述
第1步、配置第三方API的鑒權認證信息
一個服務商可能有多個接口提供不同的服務,但是獲取身份認證信息基本是通用的,例如獲取token,隻需獲取一次,有效期內可以調用多個接口,在集成中心統一配置後,相關接口都可以直接使用此認證信息。
有些服務商的API接口不需要先獲取認證信息,則可以跳過此步,直接配置第2步。
第2步、配置API接口請求信息
使用不同的數據服務就需要調用不同的接口,每個接口都需要配置相關輸入參數,接口地址。對於獲取到數據,需要配置數據的輸齣格式,供工作錶或工作流使用。
第3步、將接口授權給相關應用
隻有獲得授權的應用,纔能使用集成好的API接口。
第4步、調用集成API
以下3處可直接調用配置好的連接認證或API接口
- 工作錶的API查詢字段
- 工作流的[調用已集成 API]節點,可以直接使用集成中心裏的配置好的API
- 工作流的[ API認證與連接 ] 節點,可以直接使用集成中心裏的「連接與認證」
安裝預置API快速體驗功能
在API庫中,內置瞭30種常用API服務,您可以根據需要直接安裝,安裝後,連接認證以及API接口等相關信息都配置好,您隻需填寫和配置必要的參數值即可。
我們以[天眼查]為例,介紹下安裝和使用過程。
1、安裝目標API
進入集成中心後,點擊[天眼查],會詳細介紹相關接口服務,然後點擊安裝。
2、配置連接信息
界麵中齣現瞭需要token的信息,需要我們前往[天眼查]網站注冊服務,申請接口並獲取到這個token,然後填寫進來保存即可。天眼查的token信息獲取可參考:如何獲取token
3、啓用需要的API
一個服務商的連接可以有多個接口服務,找到需要的接口開啓即可
4、授權給需要的應用
隻有添加瞭授權的應用,纔能使用此連接服務和API功能。
5、工作錶中使用集成API
進入CRM應用,添加API查詢字段和工商信息相關的字段。
功能效果
第一步、 連接與認證
上一章我們通過安裝預置API模闆,瞭解瞭使用過程。本章我們詳細介紹從0開始配置自定義連接的操作過程。
添加自定義連接
進入集成中心後,切換到[我的連接],點擊+自定義連接
選擇鑒權方式
根據所需API服務的鑒權要求,選擇對應的鑒權方式,如果不需要或者在請求URL中進行API Key鑒權,則直接點擊[APIKey或無需鑒權無需認證],選擇後點擊保存並繼續。
連接參數
連接參數是配置鑒權時依賴的一些身份參數,比如企業微信中要獲取Token時需要corpid和corpsecret,這些參數服務服務商都會分配給我們,我們隻需粘貼到此處即可,如果API接口不需要,連接參數可以不配置。
在API服務商係統內獲取到相關信息後,填充到對應的參數值然後保存即可(安裝的API服務,隻能填寫參數值,不能改參數名等信息)
-
參數值可以選擇隱藏顯示,勾選隱藏後,參數值加密顯示,不允許取消隱藏
-
參數值隱藏後,隻能修改,不能再顯示,需要查看需到服務商平臺查看
連接參數 除瞭獲取Token時可能需要,在調用API時請求參數也可能需要,因此,服務商的基礎應用信息都可以填寫在這裏供鑒權認證使用或API請求時使用。
Basic Auth 認證
此方式錶示每次請求API時都需要提供用戶的username和password。
用戶名和密碼可以在這裏直接寫固定值,也可以從配置好的連接參數中選擇。
OAuth 鑒權認證
通過此方式可以獲取到的Access Token,供API請求時使用。
- 默認生成 app_id 和 app_secret 兩個param參數;可以更改或刪除
- 參數值可以從連接參數中選擇
- 配置完畢後點擊[獲取Access Token]按鈕,測試
- 根據API服務要求, 可以配置過期時長,到時自動獲取新Token。
配置連接的基本信息
可以設置連接的名稱、Logo、和描述
第二步、API接口請求配置
連接認證配置完成後,就可以開始配置相關的API請求瞭。 切換到[API管理],點擊創建API按鈕開始配置。
主要配置基本信息、輸入參數、API請求參數和輸齣參數,以及使用代碼塊來個性化處理輸入和輸齣參數。
API基本信息
點擊相關位置,可以設置API的名、描述說明、圖標和顔色
輸入參數
輸入參數用於在工作錶或工作流中使用 API 查詢時,可以傳入動態值。傳進來後,可以將此參數值再傳給API請求參數。
參數默認值
-
如果參數為非必填,且傳進來的為空值,則使用默認值(如果有)。
-
必填參數一定會有值傳進來,不需要設置默認值,但也支持設置(取消必填時可用)
參數格式規則和要求
-
參數類型:文本、數值、日期時間、人員、部門、附件、數組、對象數組;
-
附件字段中無論有多少個文件,傳入的的數組,格式如下。
["URL1","URL2","URL3"...], 如果需要URL字符串,則使用代碼塊處理後再傳入API請求參數。
-
必填的參數在工作錶和工作流中使用此API時傳入的參數不能為空;
-
對象數組的必填驗證規則:
- 對象數組必填,則在使用時必須傳入該數組;對象數組不必填,則在使用時該數組可以不傳入;
- 對象數組必填且子元素沒有設置必填項,則在使用時允許傳入的數組為空數組;
- 對象數組必填且子元素有必填項,則在使用時會驗證傳入的子元素是否有值;
- 對象數組不必填但子元素有必填項,則未傳入 對象數組時不驗證子元素是否有值,該數組傳瞭值之後,則需要驗證必填的子元素項是否有值;
-
彆名規則:僅支持字母、數字、下劃綫、短橫綫(減號)
-
在發送API請求時,數組對象子元素將以彆名作為key
-
參數支持默認值
插入代碼
當傳入的參數格式或數據不符閤API參數要求時,可以通過代碼處理後再傳遞給API參數。也可以將API返迴的結果經常代碼處理後再輸齣。
支持 Javascript和Python語言。
常見場景有:
-
結閤時間戳、密鑰等加密後獲取Token
-
傳遞手機號時去掉 +86
-
傳遞附件圖片時傳遞URL字符串
-
將API返迴的數據封裝為JSON數組並輸齣返迴
-
從API返迴的JSON數據中進行處理後輸齣返迴
API請求配置
在這裏配置發送 API 請求時需要的URL、 Query Param、Header、Body 等請求參數。
請求中的參數值可以選擇[連接參數]和[輸入參數]、[鑒權認證]3個地方的動態值。
配置完畢後,點 擊[測試API],輸入測試參數,即可返迴請求的數據。
相關配置信息介紹,可參考發送API請求介紹
輸齣參數
在API執行請求後,將獲取到的數據格式化輸齣,以便被工作錶字段或被工作流節點引用。
其依據的示例數據是上一步測試時返迴的響應Body中的數據。
輸齣配置方法: 使用JSON解析後將需要的內容添加到參數中。JSON解析
發布API
輸齣參數配置完畢後,就可以發布API瞭。發布後纔能被應用的工作錶或工作流調用。
添加更多API接口
一個連接認證 內,可以添加多個API接口請求,這些API接口共用用同一個連接。
第三步、授權給應用
集成中心配置好的API,需要配置連接的擁有者,錯誤提醒機製和授權應用,獲得授權纔能直接調用。
切換到[授權到應用]欄位下,可以進行操作操作。
擁有者
連接的擁有者可以修改和查看連接的配置,可以接收錯誤消息。
發送錯誤消息
如果調用時齣現錯誤,是否嚮擁有者發送消息,如果發送,可以配置發送消息類型,如果是相同類型消息則多久纔通知一次,不需要次次提醒,造成乾擾。
授權應用
隻有本組織的應用纔能添加授權,授權後,應用下的工作錶和工作流可以調用API。