跳至主要内容

使用 Postman 存取 Asgard Generic API

本教學將引導您如何使用 Postman 工具，串接並測試 Asgard Generic API，協助您進行開發與除錯。

注意：請求方式是採用 SSE（Server-Sent Events）方式，與一般 API 不同，請求後會持續收到一連串事件資料，而不是一次性回應。

1. 取得 SSE API 網址與 API Key​

  1. 進入您的專案。
  2. 點擊左側側邊欄的 Apps。
  3. 找到已設定完成、狀態為 Integrated 的應用，點擊右上角的「⋯」選單。
Integrated 狀態與 Integrate 選單
  1. 選擇 Integrate，在彈出視窗中展開 Message API 的 Send Message (SSE Streaming) 下拉選單，點擊網址右側的 Copy 按鈕複製 API 網址
SSE 欄位與 Copy 按鈕
  1. （如有設定 API Key）重複步驟3打開選單，選擇 View，即可看到 API Key 的資訊。
API Key 位置
警告

SSE API 網址與 API Key 屬於高度敏感資訊，請務必妥善保存，嚴禁公開或洩漏於網路、文件、郵件或第三方平台。 一旦外洩，任何人都能直接存取您的服務，可能導致資料外洩、資源被濫用、帳號遭盜用，甚至產生高額費用與不可逆損失。

2. Postman 設定步驟​

  1. 開啟 Postman。
  2. Method 選擇 POST。
  3. 在 URL 欄位輸入 {您的 SSE API 網址}。
  4. （如有 API Key）於 Headers 區塊新增：
    • Key：X-API-KEY
    • Value：{您設定的 API Key}

以上步驟完成後，即可進行 API 測試。

3. JSON 格式欄位說明​

在開始對話前，先了解傳送的 JSON 格式欄位定義：

  • customChannelId：聊天頻道 ID，可自訂。同一頻道 ID 才會記憶對話內容。
  • customMessageId：訊息 ID，可自訂或留空，便於追蹤與除錯。
  • text：輸入的訊息內容。
  • action：命令方法，常用值為 RESET_CHANNEL（初始化）與 NONE（一般訊息）。

4. 初始化頻道​

首次對話前，需先初始化頻道。

操作步驟： 切換到 Body，選擇 raw 並設定為 JSON，填入下列格式：

{
  "customChannelId": "a-random-channel-id-1",
  "customMessageId": "a-random-msg-id-1",
  "text": "",
  "action": "RESET_CHANNEL"
}

初始化設定​

  • customChannelId：必填，可任意設定。
  • customMessageId：可留空。
  • text：初始化時請留空。
  • action：初始化必須填寫 RESET_CHANNEL。

點擊 Send，若 AI Bot 有設定初始發言內容，會在此次回應中顯示。

Postman Send 並查看回應

注意：必須先初始化頻道，才能正常進行傳送訊息。

5. 傳送訊息​

初始化完成後，即可開始與 AI Bot 對話。

操作步驟： 切換到 Body，選擇 raw 並設定為 JSON，填入下列格式：

{
  "customChannelId": "a-random-channel-id-1",
  "customMessageId": "a-random-msg-id-2",
  "text": "微波烤箱可以烤德國豬腳或生鮮料理嗎?",
  "action": "NONE"
}

傳送訊息設定​

  • customChannelId：請與初始化時相同，確保對話連貫。
  • customMessageId：可自訂或留空，建議流水號遞增。
  • text：您的訊息內容。
  • action：傳送訊息時填寫 NONE。

點擊 Send，即可收到 AI Bot 的回應。

Postman Send 並查看回應

注意：customChannelId 必須一致，AI Bot 才會記住前序對話。

6. 重置對話​

若需重置頻道內所有對話，只需重複「初始化頻道」步驟，即可讓頻道回到初始狀態。

7. 傳送訊息附加檔案​

當您的 AI Bot 支援檔案分析功能時，可以透過附加檔案的方式讓 AI Bot 分析檔案內容並回覆結果。

請依序完成以下兩個步驟：

7.1 上傳檔案​

重要提醒

上傳檔案需要使用 Blob API！請選擇 Blob 欄位（不是 SSE），點擊右側 Copy 複製網址。詳細位置可參考 取得 SSE API 網址與 API Key 的步驟四。

設定步驟：

  1. 在 URL 欄位輸入 {您的 Blob API 網址}
  2. 其他設定與對話設定相同
  3. 切換到 Body 標籤
  4. 選擇 form-data 並設定為 Key-Value 格式
  5. 填入以下欄位：
KeyTypeValue
customChannelIdTexta-random-channel-id-1
fileFilefile.png

參數說明：

  • customChannelId：請與初始化時相同，確保對話連貫
  • file：點擊 Value 欄位的位置，即可選擇要上傳的檔案

點擊 Send 即可上傳檔案。成功後會收到以下 JSON 回應：

{
    "isSuccess": true,
    "data": [
        {
            "channelId": "1939596381945597952",
            "blobId": "1939596382025289728",
            "fileType": "IMAGE",
            "fileName": "image.png",
            "size": 326492,
            "mime": "image/png"
        }
    ],
    "paging": null,
    "error": null,
    "errorCode": null
}

請記錄回應中的 blobId，以便進行下一個步驟。

7.2 傳送訊息附加檔案 (使用 Blob ID)​

設定步驟：

  1. 將設定調整為與 5. 傳送訊息 相同
  2. 記得將網址改回 SSE API 網址
  3. 使用上一步取得的 blobId，在 JSON 中加入 blobIds 欄位

傳送附加檔案的訊息：

{
    "customChannelId": "a-random-channel-id-1",
    "customMessageId": "a-random-msg-id-3",
    "text": "圖片上有什麼?",
    "action": "NONE",
    "blobIds": ["1939596382025289728"]
}

參數說明：

  • customChannelId：請與初始化時相同，確保對話連貫
  • customMessageId：可自訂或留空，建議使用流水號遞增
  • text：您的訊息內容
  • action：傳送訊息時填寫 NONE
  • blobIds：上傳檔案完成時取得的 blobId，可傳入多個檔案 ID，用陣列格式

點擊 Send 後，即可收到 AI Bot 分析檔案內容的回應。

注意事項

如果您的 AI Bot 未設定有檔案分析功能，系統只會回覆您的文字訊息，不會處理附加的檔案內容。

9. Response 格式解說​

當您送出請求後，系統會依照對話流程回傳一連串 JSON 事件，涵蓋完整的生命週期與欄位格式。
想深入了解每個事件的內容與範例，請參考：

10. 常見問題排除​

  • 未初始化頻道無法對話：請務必先執行初始化步驟。
  • API Key 錯誤或遺漏：請確認 Header 是否正確帶入 X-API-KEY。
  • 頻道 ID 不一致：同一對話請保持 customChannelId 一致。
  • 訊息格式錯誤：Body 必須為正確的 JSON 格式。
  • 檔案上傳失敗：請確認上傳網址是否為 Blob API 的網址。