佇列端點
您可以透過以下端點存取所有佇列功能：
例如，要使用 curl 提交請求並將其新增至佇列：
request_id 的範例回應：
request_id，並提供用於檢查狀態、取消或擷取回應的 URL，簡化您的工作流程而無需額外的端點開發。
請求狀態
若要監控您的請求進度，請使用提供的端點搭配您唯一的請求 ID。這讓您能夠追蹤狀態、佇列位置，或在回應準備好後擷取回應。端點使用
範例回應
當您的請求在佇列中時，您將會收到像這樣的回應：可能的狀態
您的請求可以是以下三種狀態之一：-
IN_QUEUE：表示請求正在等待處理。
queue_position：顯示您在佇列中的位置。response_url：處理完成後擷取回應的 URL。
-
IN_PROGRESS：請求目前正在處理中。
logs：詳細的日誌 (如果啟用) 顯示處理步驟。response_url：最終回應將可用的位置。
-
COMPLETED：處理已完成。
logs：詳細說明整個過程的日誌。response_url：直接連結到您已完成的回應。
啟用日誌
日誌提供有關請求處理的見解。它們預設為停用，但可以使用查詢參數啟用：message：事件的描述。level：嚴重性 (例如，INFO、ERROR)。source：日誌的來源。timestamp：日誌產生的時間。
即時監控
若需持續更新，請使用串流端點：text/event-stream 格式提供即時狀態更新，直到請求完成。
Webhooks
如果您不想輪詢，可以在提交請求時傳入webhook 查詢參數。當請求達到最終狀態時，Sunra 會將最終結果 POST 到該 URL，無需保持長連接或定時輪詢。
啟用 Webhooks
將經過 URL 編碼的webhook 查詢參數附加到提交端點：
https%3A%2F%2F...），並確保 Sunra 能夠存取該位址；強烈建議使用 HTTPS。提交回應保持不變 — 您仍會收到 request_id 以及相同的狀態/取消/回應 URL。
觸發時機
Sunra 僅在最終事件時呼叫您的 webhook：succeeded— 請求已完成，輸出包含在負載中。failed— 請求發生錯誤，錯誤詳情包含在負載中。
IN_QUEUE、IN_PROGRESS）不會觸發 webhook。如果您還需要進度更新，請將 webhook 與上文的串流或輪詢端點結合使用。
請求格式
Sunra 將向您的 webhook URL 發送POST 請求，包含以下標頭：
您的端點必須在 5 秒內回傳
2xx 狀態碼。請快速確認並將耗時操作交給背景任務處理 — 回應過慢會被視為失敗並觸發重試。
負載
成功事件：output 替換為 error。error 的具體內容因失敗類型而異 — 下例展示其中一種常見形式：
重試機制
Webhook 投遞保證至少一次。如果您的端點逾時（5 秒）或回傳非2xx 狀態，Sunra 會進行最多 3 次指數退避重試，初始延遲 10 秒，最大不超過 30 秒。最後一次重試失敗後，會記錄失敗資訊且不再嘗試。
由於重試可能多次投遞同一事件，請確保您的處理程序是冪等的 — 使用 id 欄位作為去重鍵。
最佳實踐
- 使用 HTTPS 並驗證流量確實來自您預期的端點。
- 立即回傳
2xx，將負載放到非同步流程中處理。 - 將投遞視為至少一次，並按
id去重。 - 如果在最終事件之前還需要進度更新，請將 webhook 與輪詢或串流端點結合使用。
取消請求
如果您的請求仍在佇列中，您可以使用以下指令取消它：擷取回應
一旦您的請求狀態為COMPLETED，請使用以下指令擷取回應：
透過 Sunra Client 簡化整合
Sunra 客戶端會自動追蹤狀態，簡化使用 Sunra 函數的應用程式開發。速率限制
為確保公平使用和系統穩定性，我們的 API 端點受到以下速率限制：
如果您超過這些限制，您將收到
403 Forbidden 回應。我們建議實作具有指數退避的重試機制來處理這些情況。