跳至主要内容

集成中心-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。

第4步、如何調用集成API

具體請參考相關介紹

連接和API管理

連接管理

[我的連接]下,會列齣所有創建的連接,包括未完成配置的連接。組織管理員可管理員組織下所有的連接

點擊連接名稱,進去此連接的管理頁麵,可以刪除連接或申請上架的API庫,可以繼續配置API和授權。

連接中的API管理

在連接的API管理欄目下,可以管理此連接下的所有API,可以開啓停用API。

點擊某個API,可以進一步查看和管理此API的信息。

查看引用

可以看到此接口被哪些工作錶和工作流引用。點擊工作錶/工作流名稱可以直接打開對應的編輯頁麵。

請求日誌

可以查看所有引用此 API 發送的請求日誌。 無權限人員不能查看日誌。

請求參數示例:

返迴結果示例

如何申請上架到API庫


在集成中心中您可申請上架自己集成的産品到API庫中,以提供給其他用戶使用。在申請上架後,我們工作人員會在1~3個工作日內完成審核。

上架標準

在申請前需要注意以下事項避免審核不通過。

  • 完善“自定義連接”Logo、基礎信息、連接說明、接口名稱、接口說明等信息。
  • 不齣現無意義字符如test、123等名稱或標識。
  • 必須包含産品介紹、産品官網、對接流程(接口文檔鏈接不強製)。
  • 若您有特殊需求如加急審核可通過聯係與您對應的明道雲HAP銷售或實施進行谘詢。

補充:建議在産品介紹中加上您的聯係方式,以免後續用戶想要使用您提供的API時齣現接口報錯等其他問題時可通過該聯係方式聯係您。

可參考以下“自定義連接”模闆(也可通過查看API庫中的官方已對接産品)

上架步驟
  1. 在"集成中心" > "我的鏈接"中找到需要上架的連接(産品)

  2. 補充連接的“使用說明”

    必須包含産品介紹、産品官網、對接流程(接口文檔不強製)。建議留下您的聯係方式方便後續用戶安裝使用您的連接時齣現疑問或其它接口相關問題可聯係您進行解決。

  3. 點擊右上角""按鈕 ,然後選擇“申請上架到API庫”

  4. 根據提示信息完善連接上架信息,最後點擊“申請上架新版本”即申請成功。等待後臺工作人員進行審核,審核時間約1~3個工作日。

如何更新已上架API
  1. 進入需要更新上架的“自定義連接”

  2. 點擊右上角""按鈕,並點擊“申請上架新版本”

  3. 默認情況下更新接口不需要改動原有産品信息,若需要更改調整可按照下麵提示更改所需要的産品連接信息即可,最後點擊“申請上架新版本”即申請成功。等待後臺工作人員進行審核,審核時間約1~3個工作日。

添加或安裝最新API

在用戶使用集成中心API庫的接口過程中,作者需要對所擁有的API更新上架。需要將更新的接口進行復製並且關閉原有接口重新申請上架,否則需要維護更新的API則不會齣現在已安裝的用戶連接中。

用戶若需要更新從API庫中安裝的連接中的API可分為以下兩種情況。

  • SaaS環境:

    點擊“添加API”,在列錶中會顯示新的API接口。

  • 私有環境:需要重新安裝API庫中的連接。


文檔問題反饋

文檔中是否有錯彆字、內容過期、難以理解等問題? 點此給我們反饋吧