Skip to main content

整合服務

路徑：【後台管理】⇒【業務整合】⇒【整合服務】

1. 整合服務的組成​

【整合服務】 用來登錄外部系統提供的 API，讓 GooJob 的表單、流程與業務模型可以直接呼叫外部系統的功能。

整合服務採用 「目錄 ⇒ 服務 ⇒ 方法」 三層結構：

  • 目錄：整合服務的分類資料夾，例如「API 測試」、「行銷寄信」。
  • 服務：一個外部系統的連線設定，包含 Adapter 類型、授權方式與地址 URL。
  • 方法：服務底下的單一支 API，包含請求方法、路徑、傳入參數與傳回值。

系統初始沒有任何目錄，首次進入 【整合服務】 時，畫面會顯示「新增整合服務前請新增目錄」的提示。

整合服務初始畫面

整合服務初始畫面

note

必須先建立目錄，才能新增服務；服務建立完成後，才能在服務底下新增方法。

2. 新增目錄​

📌 首次新增目錄​

  1. 點擊畫面中央的 『新增目錄』，系統會開啟 【新增目錄】 對話框；輸入 顯示名稱（必填）後，點擊 『確定』 即可建立。

    新增目錄對話框

    新增目錄對話框

  2. 建立成功後畫面會出現「新增目錄成功」的提示，新目錄會顯示在左側 ［目錄］ 清單中，右側則切換為服務列表。

    目錄建立完成

    目錄建立完成

📌 新增更多目錄​

已有目錄後，可點擊左側 ［目錄］ 右方的 『＋』，隨時再新增其他分類目錄。

由左側目錄區新增目錄

由左側目錄區新增目錄

tip

左上方的搜尋框可依目錄名稱快速查找；點選 『全部』 則會列出所有目錄底下的服務。

3. 新增、編輯、刪除服務​

📌 新增服務​

  1. 點擊畫面右上角的 『新增服務』。

    新增服務按鈕

    新增服務按鈕

  2. 系統會由右側展開 【新增服務】 面板，請依序填寫 ［基本資訊］：

    • 服務名稱（必填）：服務在列表上顯示的名稱。
    • 服務編碼（必填）：系統識別用的代碼，例如 bpmH3_01。
    • Adapter（必填）：介接時採用的轉接器類型，由下拉選單選擇。
    • 所屬目錄（必填）：服務要歸屬的目錄，預設帶入目前選取的目錄。
    • 服務類型：可選擇 『私人』 或 『共享』。

    確認資訊無誤後，點擊右下角的 『儲存』 即完成建立。

    新增服務面板

    新增服務面板

📌 編輯服務​

  1. 在服務列表中找到要修改的服務，點擊 ［操作］ 欄的 『編輯』。

    編輯服務

    編輯服務

  2. 系統會展開 【編輯服務】 面板，上方顯示 建立人、建立時間、修改人、修改時間 等紀錄，下方則帶入目前的設定：

    • ［基本資訊］：可修改 服務名稱、所屬目錄、授權方式（如「無身份驗證」）與 服務類型；服務編碼 與 Adapter 建立後即固定，無法修改。
    • ［屬性名稱］：設定 地址URL（必填），即外部系統的 API 根位址，例如 https://<專案網域>/rest/v1。

    修改完成後點擊 『儲存』 即可套用。

    編輯服務面板

    編輯服務面板

note

地址URL 為服務層級的共用位址，方法層級只需再填寫相對路徑（例如 /orders），系統會自動組合成完整的 API 位址。

📌 刪除服務​

點擊 ［操作］ 欄的 『刪除』，系統會跳出「確認刪除目前服務嗎？」的確認訊息，點擊 『確定』 即可移除該筆服務；若要保留，點 『取消』。

刪除服務確認

刪除服務確認

warning

刪除服務會一併移除其底下的所有方法，且無法復原。建議刪除前先確認沒有任何業務模型正在引用（參見 ［查看引用］）。

4. 新增、編輯、刪除方法​

📌 新增方法​

  1. 在服務列表中，點擊該筆服務 ［操作］ 欄的 『新增』。

    於服務底下新增方法

    於服務底下新增方法

  2. 系統會展開 【新增方法】 面板，［基本資訊］ 的欄位如下：

    • 方法名稱（必填）：方法在列表上顯示的名稱。
    • 方法編碼（必填）：系統識別用的代碼，例如 bpmH3_01。
    • 請求方法：選擇 Post、Get、Put、Patch、Delete。
    • 地址URL：接在服務地址之後的相對路徑；輸入 $env( 可選擇環境變數。
    • Request Body格式：選擇 Form-urlencoded、JSON 或 Text。
    • 連線逾時時間（必填）：等待回應的秒數，預設 10 秒。
    • 連線重連次數（必填）：逾時後的重試次數，預設 3 次。
    • 允許前端線上開發呼叫：開啟後可由前端直接呼叫此方法。
    • 方法描述：補充說明此方法的用途，方便後續維護時辨識。

    新增方法面板

    新增方法面板

  3. 面板下半部提供 ［傳入參數］ 與 ［傳回值］ 兩個頁籤。［傳入參數］ 再依參數的擺放位置分為 Query、Path、Header、Body 四個子頁籤，點擊 『＋ 新增參數』 即可逐筆設定：

    欄位說明
    參數名稱實際傳送給外部 API 的參數名稱，例如 apikey。
    顯示名稱在 GooJob 中對應的欄位名稱，例如 SupabaseApiKey。
    應用位置參數在請求中的位置。
    參數類型參數的資料型別，例如「單行文字」。
    是否必填以開關控制此參數是否必填。
    描述補充說明此參數的用途或格式。

  4. 設定完成後，點擊 『儲存』 直接存檔；或點擊 『儲存並連接測試』 存檔後立即進行連線測試。儲存後的方法會顯示在服務底下，可點擊服務左側的展開圖示檢視。

    服務底下的方法列表

    服務底下的方法列表

📌 編輯方法​

在方法列表中點擊 ［操作］ 欄的 『編輯』，系統會展開 【編輯方法】 面板並帶入目前的設定，欄位與新增時相同（方法編碼 建立後不可修改）。調整完成後點擊 『儲存』 即可套用。

編輯方法面板

編輯方法面板

5. 測試連線​

方法設定完成後，建議先實際試打一次，確認能正常連通外部系統。

  1. 在方法列表中點擊 ［操作］ 欄的 『運行』。

    運行方法

    運行方法

  2. 系統會展開 【測試連線】 面板，內容包含：

    • ［基本資訊］：顯示目前要測試的整合方法名稱。
    • ［傳入參數］：列出此方法設定的所有參數（數據名稱、參數類型），可逐一填入測試用的值；標示紅色星號者為必填。
    • ［請求體］：依方法設定自動帶出 Request Body 的欄位樣板，可直接填入測試資料。
    • ［傳回值］：執行後顯示外部系統實際回傳的內容。

    填妥後點擊右下角的 『運行』 送出請求；若要將回傳結果套用為此方法的傳回值定義，可點擊 『擷取到回傳值』。

    測試連線面板

    測試連線面板

tip

測試連線只會實際呼叫外部 API，不會影響 GooJob 內的資料；但若測試的是新增、刪除類的方法，外部系統仍會真實寫入或移除資料，建議使用測試環境的位址進行驗證。

6. 方法的其他操作​

在方法列表 ［操作］ 欄點擊 『更多』，可展開 『查看引用』、『刪除』、『複製』 三項操作。

方法的更多操作

方法的更多操作

  • 查看引用：查詢有哪些業務模型正在使用這支方法。
  • 刪除：移除該筆方法。
  • 複製：以現有方法為範本快速建立一筆新方法。

點擊 『查看引用』 後，系統會展開 【查看引用】 面板，上方以「以下 N 個業務模型引用了目前業務整合方法：○○」說明引用數量，下方列表則顯示 序號、業務模型 與 所屬應用；若沒有任何引用，會顯示「暫無數據」。

查看引用

查看引用

warning

刪除方法前請務必先 『查看引用』，確認沒有業務模型正在使用，以免影響既有應用的運作。

7. 匯出、匯入服務​

整合服務支援以檔案方式搬移設定，適合在測試環境完成設定後轉移到正式環境。

📌 匯出服務​

勾選要匯出的服務（可勾選表頭的核取方塊一次全選），畫面上方會顯示「已選擇 N 個整合服務」，接著點擊右上角的 『匯出服務』，系統即會下載一份 .zip 檔案。

匯出服務

匯出服務

📌 匯入服務​

  1. 點擊右上角的 『匯入服務』，系統會開啟 【匯入-整合服務】 對話框，並以三個步驟引導完成。於 ［上傳檔案］ 步驟選擇 所屬目錄，再將檔案拖曳到指定區域或點擊 『點選上傳』（支援 .zip 格式，檔案大小不限）。

    匯入服務－上傳檔案

    匯入服務－上傳檔案

  2. 進入 ［檔案驗證］ 步驟，系統會先檢查檔案格式。若匯入檔中的服務方法編碼在目前系統已存在，會詢問是否覆寫，並列出處理規則：

    • 選擇 『匯入並覆蓋』：
      • 目前系統和匯入檔案中都存在的業務方法：使用匯入檔案中的覆蓋。
      • 目前系統已存在，且匯入檔案中不存在的業務方法：仍然保留。
      • 目前系統中未存在的業務方法：直接匯入。
    • 選擇 『修改編碼』：修改編碼再匯入，將會產生新的服務方法。

    匯入服務－檔案驗證

    匯入服務－檔案驗證

  3. 完成 ［匯入］ 步驟後，畫面會顯示「匯入成功」，點擊 『完成』 關閉對話框，即可在列表中看到匯入的服務與方法。

    匯入服務－匯入成功

    匯入服務－匯入成功

8. 搜尋服務​

當服務數量較多時，可在畫面右上方的搜尋框輸入 服務編碼 或 顯示名稱 的關鍵字，列表會即時篩選出符合的服務，並將命中的文字以高亮標示。

搜尋服務

搜尋服務