API 管理應用情境

透過API 管理情境案例中，您將了解組織中常見的 14 種 API 管理功能需求案例，藉由情境演示將能更有效協助企業將其使情境套用於自身組織中。

案例公司

昕力資訊是一家提供 “API 即服務 (API as a Service)” 的科技公司，提供各式 API 資源協助企業內部以及客戶能夠更快速且有彈性的建構企業所需服務。

昕力資訊專責 API 策略以及資源規劃的技術團隊為林經理和他的團隊成員。面對日益增加的 API 數量以及在 API 管理上的不同需求，林經理發現他以及團隊花了許多時間以及溝通成成來達到各方的要求，並且常有資源混亂而導致重工或部門間/內外部溝通落差的狀況出現。

為了夠更有效的控管公司的 API 資源以達到策略上的綜效，林經理導入 digiRunner API 管理平台作為公司的 API 資源管理中心，透過單一介面來輕鬆管理各式 API 以及豐富的 API 管理機制來滿足內外部的需求，大幅降低團隊技術營運成本並有效提升溝通效率。其中林經理的技術團隊、平台開發部門以及財務部門為組織中最常大量使用 API 服務提供給其內外部的客戶的團隊之一。

情境一：平台使用權限

在這個情境中您將能了解如何在 digiRunner 中建構出組織圖，並賦予不同階層相對應的平台權限以及各式功能模組。

使用者案例

平台開發部門以及財務部希望將 digiRunner 作為其團隊 API 開發以及 API 生命週期的管理平台，兩個部門都希望有自己的組織權限規範以及各自需要不同的功能模組來提供給成員 (Approver, IT, Developer) 進行執行相關工作。

林經理的團隊作為平台的最高權限單位(HQ_Admin) 從財務部(BU-1)的需求來設計垂直的組織結構並附賦予組織中不同角色使用者(ex, Admin Approver) 不同的權限以及功能。

BU-1 Admin_Approver 所被授權的內容包含:

授權權限:

權限管理: 使用者維護 / 個人資料維護
用戶端管理: 用戶端維護
API 管理: API 列表
用戶憑證管理: ALL
報表: ALL
各類申請單: 簽核作業
系統現況查詢: API Key 現況查詢 / 入口網上架現況查詢 / 排程作業 / 週期排程 / 寄件歷程

授權角色(作為 Admin_Approver, 被賦予可授權下屬的角色列表):

單位主管: bu_admin_appr
單位系統管理員: bu_admin_it
單位開發人員: bu_dev

步驟

步驟一：組織單位維護

點選『權限管理』>『組織單位維護』，進行組織建立

輸入欲建構組織的相關訊息 (BU-01, Admin_Approver), 點擊【新增】創建組織節點

步驟二：角色建立

點選『權限管理』>『角色維護』，進行角色建立(BU_Admin_Approver)

輸入『角色代號』、『角色名稱』並點選此角色可使用的『功能清單』，點選【建立】

步驟三：角色清單設定

點選『權限管理』>『角色清單設定』，將可授權角色授予 “BU_Admin_Approver” 此角色。可授權之角色清單: BU_Admin_Approver, BU_Admin_IT, BU_dev

步驟四：使用者建立

點選『權限管理』>『使用者維護』，建立一個隸屬於 BU-01 組織底下的使用者: bu01_admin-appr，並將剛剛創建好的角色(BU_Admin_Approver)授予該使用者以取用其角色被授權之功能

情境二：API 代理

在此情境中您將能了解如何將在不同 AP server 上的 API 註冊到 digiRunner 上進行統一的代管。

使用者案例

財務部門有大量在不同伺服器上的 API (AP, DB, FTP…)，因在不同伺服器上管理不易，希望能夠在單一平台上進行統一的管理節省維運時間以及成本。透過 digiRunner 的 API 代理服務，就能輕鬆地透過 API url (http/ https) 或是透過 Swagger 文件將 API 註冊至 digiRunner 平台上。 “currencyRate” 這支匯率查詢 API 也是此次要讓 digiRunner 代理的 API 之一，這邊將以此 API 進行示範。

步驟

步驟一：API 註冊

點選『API 管理』>『API註冊』，進行 API 註冊 (currencyRate API)

(若您手上已持有該Open API 的文件，也可於此頁選擇檔案作上傳)

步驟二：客製 API

點選【CUSTOMIZE】，輸入「來源URL」、「模組名稱」、「API ID (API Key)」及「Http Method」；另外因為匯率為公開資訊不需另外特別授權，因此勾選” No Oauth Required”後，點選【註冊】即可完成註冊流程。

步驟三：啟用 API

完成步驟二後，即能在『API 列表』找到剛剛註冊的 “currencyRate” API。勾選欲啟動的 API，點選【啟動】，啟動 API (狀態燈號顯視為綠色即為成功啟用)

情境三：API 加密

在此情境中您將能了解如何透過 digiRunner 管理平台不須程式編寫即能為您的 API 加密 (JWE/JWS)。

使用者案例

基於資訊安全考量，昕力資訊宣布所有機密資訊內容包含 API 無論是傳輸到組織外部或於組織間傳輸都應進行加密以確保資訊傳輸安全。

digiRunner 管理平台提供不須另外編寫程式即可為 API 加密的功能，平台擁有 API 編輯權限的使用者像是林經理或是財務部的開發人員皆可在平台上對其註冊代理的 API 進行加密(JWE/JWS)，同時 digiRunner 上的 API 列表也提供該支 API 是否以加密的訊息。這邊以 “fileTransform” 格式轉換 API 作為加密標的範例

步驟

步驟一：搜尋 API 列表

點選『API管理』>『API列表』，查詢欲設定加密的”fileTramsform” API 後，點選【搜尋】

步驟二：更新 API

勾選API後，點選【更新】，進行設定。

開啟「JWT 設定」，設定「Request」和「Response」的加密方式，設定完成後點選【更新】來儲存變更。

步驟三：JWT 設定

在『API列表』的「JWT 設定」欄位可以確認加密相關訊息

情境四：API 開關

在此情境您將體驗透過 digiRunner 管理平台輕鬆將 API 啟用或是關閉的功能。

使用者案例

林經理和他的團隊每年會對 digiRunner 上的所有 API 進行盤點清理，將不再使用或是有資安疑慮的 API 關閉，其中 “backendConnection” 後端系統串接 API 是其中一支不再使用的 API，在管理平台上僅需幾得簡單的步驟即能完成 API 關閉。

步驟

步驟一：API 列表

點選『API 管理』>『API列表』，輸入欲停止使用的 “backendConnection” API後，點選【搜尋】

步驟二：選擇 API

勾選 API 後，點選【停止】，停止 API。

步驟三：停用 API

停用的 API 仍可在 API 列表中搜尋到，唯其狀態燈號會顯示紅色。

情境五：API 屬性群組管理

在此情境您將了解 digiRunner 提供的 API 群組管理功能，將相同屬性以及安全等級的 API 群組化，並一次性的授權給平台用戶。

使用者案例

為了確保資訊安全，所有的 API 在註冊至 digiRunner 代理時必須標示其安全等級，用戶僅能搜尋到與其自身標示安全及標相同的 API。

林經理以及其團隊在盤點 API 時同步將其依照安全分級以及不同的屬性進行 API 分組，如此一來當有新的用戶需要取用 API 資源時，可以直接將整”組”的 API 授權給該用戶而非一支一支授權，大幅節省管理時間。

API 群組

依據公司 API 安全規範，所有由昕力資訊內部員工以及認證合作廠商負責建構的 API 接標示為 “System Security” 系統安全，同時為了方便分類管理，API 的功能屬性也是在分類時的依據。 “Composer” 群組就是在組織中其中一個 API 群組。

用戶管理

昕力的第三方合作廠商 Andy 也希望藉由 digiRunner 上提供的 composer API 來加速他的 API 開發，為讓他取得工作上所需的 API，林經理直接將與他安全等級相符的 API 群組授權給他，而非一支一支授權，快速的完成了 API 授權作業。

步驟

API 群組

步驟一：新增群組

點選『用戶端管理』>『群組維護』，點選【新增群組】進行資料建立

步驟二：選擇功能模組

群組名稱: Composer
提供創建群組所需要的相關資訊後點選【選擇 Module】選擇欲授權至群組的模組

點選【套用選擇】套用所選功能模組

步驟三：選擇 API

點選【選擇API】選擇所屬的 API。於”Composer”群組之所屬 API 為 : “fileTransform” 以及 “backendConnection” 兩支 API。選擇後點選【套用選擇】

確認所選擇模組及 API，設定皆成功套用後，點選【建立】完成群組創建流程

用戶管理

步驟一：新增用戶

點選『用戶端管理』>『用戶端維護』，進入頁面。點選【建立】創建新用戶 (帳號: tsp1)，提供所需資訊 (用戶端帳號、用戶端代號、用戶端名稱、密碼、再次確認密碼、擁有者、狀態、開放狀態、電子郵件帳號) 後點選【建立】

步驟二：安全設定

於關鍵字搜尋欄位，輸入用戶訊息(tsp1)，點選【搜尋】。找到用戶後點選「動作」欄位中的【安全】，進行資料設定

步驟三：群組授權

點選【安全】按鈕後，點選視窗上『授權設定』頁籤，點【設定群組】以進行設定

步驟四：授權設定

綁定所屬的群組，勾選 “Composer”, “dppublic (入口網公開群組)”, “Public” 群組以綁定至用戶，點選【更新】

步驟五：Token 設定

點選『Token設定』頁籤，設定「OAuth grant type」、「Access token expire」及「Refresh token expire」，點選【更新】以儲存變更，再點選【返回列表】即完成設定

情境六：API 資料格式轉換

(於 digiRunner 企業版提供)

在此情境您將能體驗到藉由 digiRunner 低代碼 API 編輯器來輕鬆達到 API 資料格式轉換之功能，只要您的 API 是 web service 的形式 (http/https) 皆能輕鬆完成格式轉換 (Ex, XML ↔ JSON)。

使用者案例

一般來說要管理儲存於不同伺服器上且格式不一的 API 是麻煩且困難的事，但是對導入 digiRunner API 管理平台的昕力資訊來說，要統一控管且將其轉換為相同的資料格式並不是件難事。林經理有一支 XML 格式的 API 會需要將其轉為統一的 json 格式，在這邊僅須透過 digiRunner 編輯器 (Composer) 就能不須需編寫程式也能輕鬆快速完成。

步驟

步驟一：目標 API

點選『API 管理』>『API列表』，選擇目標 API Template (fileTransform)。點選【更新】進入編輯畫面。

步驟二：匯出 API Template

點選【開啟編輯器】進入〔DigiRunner Composer〕頁面

點選右上角，選擇【匯出】，匯出.json

步驟三：建立新 API

點選【API組合與設計】，輸入【模組名稱】、【API ID (API Key) 】、【Http Method】後，點選【開啟編輯器】

步驟四：匯入 API Composer

點選【匯入】將.json匯入

重新拉好功能節點

步驟五：部屬

完成編輯後，點選【部署 Deploy】

情境七：後端系統介接

(於 digiRunner 企業版提供)

在此情境您將體驗低代碼 digiRunner 編輯器 (Composer) 所帶來的便捷功能，僅需要拖拉各式功能節點便能快速組合出一支用於後端系統介接的 API，無論您希望串到 MQ 或是 SAP RFC 等系統，都輕鬆無負擔。

使用者案例

昕力資訊將 digiRunner 定位為公司的 API 資源中心，其中也與不少公司後端系統介接。然而通常會需要一些時間來完成系統的串接，尤其當標的的系統不只一個的時候會花費更多的時間以及人力，這時候就可以使用 digiRuuner 編輯器(Composer) 來減低程式編寫的負擔。

平台開發部門的架構工程師，透過 digiRunner 編輯器 (Composer) 上功能強大的低代碼編輯設計，僅需要拖拉連結多樣功能節點，就能在 5 分鐘以內完成一支後端系統介接的 API。

步驟

步驟一：API 組合與設計

點選【API組合與設計】，輸入【模組名稱】、【API ID (API Key) 】、【Http Method】後，點選【開啟編輯器】

步驟二：匯入 .json

點選【匯入Import】將 Template API .json匯入

步驟三：編輯功能節點

編輯功能節點拉出 API 功能

步驟四：部屬

完成編輯後，點選【部署】

情境八：API 授權

在此情境您將體驗如何藉由 digiRunner 管理平台管理 API 的授權。 digiRunner 提供下列授權方式: Public, API Key, OAuth 2.0 (Client Credential/ Password/ Auth Code/ Implicit)

使用者案例

Andy 是第三方開發單位的工程師，他希望可以透過 digiRunner 的入口網 (提供非 digiRunner 管理平台使用者也能取得 API 資源的的入口) 取得特定的 API 資源，以減少自己開發 API 的負擔。

Andy 的 digiRunner 用戶設定中，他的授權方法應為 OAuth: Client Credential，通常這種授權種類一般用於讓用戶僅能成功取得對外公開的 API 而不是昕力資訊內部開發用 API ，主要用於提供給組織外部的用戶。

步驟

步驟一：用戶端管理

點選【用戶端管理】>【用戶端維護】，進入查詢畫面搜尋用戶(tsp1)

步驟二：安全

點選「動作」欄位中的【安全】

步驟三：Token 設定

選擇『Token設定』頁籤

步驟四：OAth grant type

從「OAuth grant Type」進行核身設定，選擇 “Client Credential”。點選【更新】以儲存變更

情境九：API 測試

在此情境您可以了解到如後透過 digiRunner 管理平台來快速驗證您代理在 digiRunner 上的 API 是否有在正常服務。

使用者案例

財務部的 IT 要確認他們的 “currencyRate” (匯率兌換) API 是否仍有正常服務，在 digiRunner 管理平台上僅需幾個簡單的步驟就能輕鬆完成測試。

步驟

步驟一：API 測試

點選『API管理』>『API測試區』，測試API Key(ID) = currencyRate

步驟二：輸入測試資訊

設定「Token」資料，輸入欲測試的「digiRunner URL」、「Http Method」、「請求表頭」及「請求表身」點選【發送請求】

步驟三：發送請求

點選【發送請求】確認是否有正常取得回傳值

情境十：API 報表

在此情境您將了解如何透過 digiRunner 提供的報表功能快速了解 API 各式數據(ex, 呼叫次數最多的 API)，協助使用者更快速的產出數據分析以及策略洞見。 digiRunner 提供多元報表如: API 使用次數統計、次數-時間分析、平均時間計算、流量分析、請求/回覆明細查詢…等。

使用者案例

現今許多企業都希望可以透過蒐集使用者行為數據，分析其行為作為提升企業營運策略的一大重點。昕力資訊財務部門希望可以了解再用戶間最受歡迎的 API 是什麼，以進一步規劃他們的財金 API 策略。

步驟

步驟一：API 使用次數

『報表管理』>『API使用次數統計』取得報表

步驟二：進階條件設定

選擇欲察看的時間區間以及依需求增加搜尋條件(add filter)。

將滑鼠游標一致欲察看的 API 柱狀圖上即可查看細節

步驟三(非必須)：輸出 CSV

點選報表右上角【。。。】，選擇【Inspect】查看該支 API 細節，也可依需求匯出CSV

情境十一：API 明細查詢 (Log)

(於 digiRunner 企業版提供)

在此情境您將體驗如何藉由 digiRunner 管理中心提供的報表功能查詢 API 明細 (log)。 digiRunner 提供多元報表如: API 使用次數統計、次數-時間分析、平均時間計算、流量分析、請求/回覆明細查詢…等。

使用者案例

財務部門的 IT 最近頻繁收到 “currencyRate” API 呼叫異常錯誤的回報，為了要解決問題，查詢 API 明細 (log) 來找出問題是第一步。 IT 人員只需要在 digiRunner 管理中心的報表明細查詢中提供關鍵字以及相關條件，就能快速地取得明細，查找問題。

步驟

步驟一：API 明細查詢

點選『報表管理』>『API 請求/回覆明細查詢』

步驟二：進階條件設定

選擇欲察看的時間區間以及依需求增加搜尋條件(add filter)指定搜尋 “currencyRate” API 明細資訊，設定完成後，點選【搜尋】

情境十二：API 代理安全

在此情進您將了解到 digiRunner 為 API 代理安全所設計的安全機制 (WAF, 流量控管、 IP 綁定(黑/白名單)。

使用者案例

遵循公司的資安政策，所有昕力資訊人員在使用 digiRunner 時應以公司內部 IP (111.111.10.100) 登入用戶使用。而為了完成這項設定，僅須在 digiRunner 控制中心即可輕鬆綁定特定 IP 以及流量控制。

步驟

步驟一：用戶端管理

點選『用戶端管理』>『用戶端維護』，點選【新增】，進入編輯畫面

步驟二：Host IP List

輸入指定 IP 位置 (IP:111.111.10.100) 並提供 Host name

步驟三：API 配額

流量控管:透過「API 配額」、「TPS」此兩個參數進行控制，若「API 配額」參數為0，則為不限制

情境十三：API 入口網

(於 digiRunner 企業版提供)

在此情境您將能理解如何間 API 透過 digiRunner 管理中心上架到開發者入口網提供給內外部人員取用 API 資源。並且設定 API 於入口網的開放狀態(內部/外部)，如此一來，API 用戶就能透過單一的窗口搜索他們需要的 API 並請求授權。

使用者案例

財務部門發現他們的 “currencyRate” 匯率查詢 API 是常被呼叫 (最受歡迎) 的 API，因此規畫將其上架到開發者的入口網上讓無論是內部用戶或外部第三方合作夥伴都可以搜尋並取用該支 API。

有鑑於每個使用者在 digiRunner 管理平台上依據不同的組織結構針對使用者會有不同的權限限制，財務部門也在一開始就設計了其部門於 digiRunner 平台上的組織圖和權限，限制不同層級/角色的人員於平台操作的權限，包含 API 的上架以及審核流程，確保 API 是經過組織審核後才能上架。

步驟

上架請求

步驟一：API 上架請求

點選『各類申請單』>『API上下架』並提供上架相關資訊，點選【保存】儲存申請單。

步驟二：送交審核

點選『各類申請單』>『簽核作業』，點選【送審】

步驟三：進度追蹤

送出審核後，可於同一頁面查詢送審單之最新審核狀態。 (『各類申請單』>『簽核作業』)

審核

步驟一：待審核 (第一關&第二關)

審核人員帳後登入後，點選『各類申請單』>『簽核作業』，選擇『待審核』頁籤，查看待審核案件。

步驟二：簽核 (第一關&第二關)

步驟三：通過 (第一關&第二關)

確認資料並將審核結果填寫於「簽核意見」，點選【通過】

審核人員可透過選擇『已審單』頁籤，查看審核通過的單子。點選【歷程】查看歷程

步驟四：入口網

完成所有簽核步驟後，該 API 即上架成功並於入口網顯示

情境十四：入口網管理

(於 digiRunner 企業版提供)

在此情境您將了解如何在 digiRunner 管理平台來管理入口網後台以及在入口網上發布公告。我們提供以下幾項入口網管理功能: 主題分類、常見問答、關於網站、網站地圖、公告維護以及 swagger 開放設定。

使用者案例

林經理於 digiRunner 管理平台新建了一個 API 主題 – Account Service (帳戶服務)至入口網提供給用戶使用，並且針對這一項更新在入口網發布了公告。

步驟

步驟一：API 主題

點選『入口網後台管理』>『主題分類維護』，建立主題，設定「主題名稱」及上傳圖片後，按【建立】

步驟二：公告維護

點選『入口網後台管理』>『公告維護』，設定公告維護告知新的 API 主題- Account Service 上架

步驟三：入口網

上述所有設定皆可於入口網看到最新更新訊息。

新增 API 主題 – Account Service

公告 – 告知入口網用戶新增 API 主題