針對服務掛勾進行問題排除

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

本文提供 Azure DevOps 服務鉤子的一般故障排除指引。 它也提供常見問題解答(FAQ)。

檢視活動和偵錯問題

Web 存取管理員中的 服務掛勾 頁面摘要列出每個訂閱在過去七天的活動。 此頁面也會顯示每個訂用帳戶都已啟用、停用或限制。

針對每個訂用帳戶,您可以存取詳細記錄,其中包含每個事件的完整要求和響應數據。 這項資訊可協助您偵錯有問題的服務或訂用帳戶。

  1. 若要檢視訂閱的活動和狀態,請前往 Service Hooks 頁面。

     服務鉤子頁面截圖,顯示訂閱的狀態、狀態及其他資料。Project設定和服務鉤子會被高亮標示。

  2. 若要檢視訂用帳戶的詳細活動,包括完整要求、回應和事件承載數據,請選取數據表中的訂用帳戶,然後選取 [ 歷程記錄]。

    顯示訂用帳戶歷程記錄的螢幕快照,其中包含失敗事件的詳細資訊,例如狀態、訊息和錯誤訊息。

訂閱失敗和試用期(受限)

如果 HTTP 對通知請求的回應顯示錯誤,失敗的嚴重程度決定了 Azure DevOps 的回應方式。 某些類型的故障可能會停用訂閱,或將其置於暫停狀態。

失敗類型

服務攔截通知失敗會分組為下列類別:

  • 終端機失敗
  • 暫時性失敗
  • 持久失敗

HTTP 回應的錯誤代碼決定了 Azure DevOps 如何分類失敗。

終端機失敗

分類為終端機失敗的唯一 HTTP 狀態代碼是 410 (已消失)。

當訂用帳戶中發生終端機失敗時,無論其先前的狀態為何,訂閱都會自動停用。

暫時性失敗

具有下列狀態代碼的 HTTP 回應會分類為暫時性失敗:

  • 408 (要求逾時)
  • 502 (不正確的閘道)
  • 503 (服務無法使用)
  • 504 (閘道逾時)

當訂閱發生暫時性故障時,Azure DevOps 會嘗試重發通知最多八次,且每次延遲逐漸增加。

下表列出發生暫時性失敗后所嘗試重試的相關信息。 包含的是大約的退避時間,或是嘗試重新傳送通知之前等待的時間。 最大退避時間為 60 秒。 數據表也會顯示每次重試的總延遲。

重試數目 退避時間以秒為單位 以秒為單位的總延遲
1 1 1
2 2 3
3 4 7
4 8 15
5 16 31
6 32 63
7 六十 123
8 六十 183

如果通知的所有重試都用盡,而且每次嘗試都會導致暫時性失敗,就不會再傳送通知。 相反地,它會分類為持續性故障。

持久失敗

所有其他 HTTP 失敗碼,例如 404(找不到)和 500 (內部伺服器錯誤),會導致持久的失敗。

當訂閱服務中發生持久失敗時,訂閱服務會進入 觀察期。

緩刑

當訂閱處於試用期時,會失去任何新活動。 系統嘗試重新傳送失敗的通知次數有限。

下表列出系統在試用期間嘗試重試的近似退回時間與總試用時間。 系統最多嘗試七次重試,緩刑重試的最長退回時間為15小時。

重試數目 退避時間 以小時為單位的總緩刑時間
1 20 分鐘 0.33
2 40 分鐘 1
3 1 小時 20 分鐘 2.33
4 2 小時 40 分鐘 5
5 5 小時 20 分鐘 10.33
6 10 小時 40 分鐘 21
7 15 小時 36

如果訂閱在試用期內成功收到回應,系統會將其恢復為完全啟用狀態,並重新發布活動。 若七次重試皆失敗,系統會將訂閱狀態設為 DisabledBySystem。

因閒置而停用訂閱

Azure DevOps 會在訂閱最近一次成功通知傳遞距今已超過六個月時,自動停用該訂閱。 訂閱會停止接收事件,直到使用者重新啟用它。

此非活動檢查僅根據最後一次成功傳遞。 它不會考慮訂閱何時建立、最後編輯,或有多少活動與訂閱相符。 只要訂閱持續成功傳送通知,就不會因閒置而遭停用,無論其存在多久。 沒有成功送達紀錄的訂閱不會受到未使用檢查的影響。

使用 AI 來排除服務鉤子的問題

以下 Copilot Chat 範例提示幫助 Copilot 排除錯誤代碼與訊息。 將此提示複製貼上到 Copilot Chat,並用你指定的錯誤訊息取代佔位符。

I'm getting this Azure DevOps service hook error: [PASTE YOUR ERROR MESSAGE HERE]

Can you help me troubleshoot this issue? Please provide step-by-step instructions to:
1. Identify the root cause
2. Fix the issue
3. Verify the solution works

Context: This is for a service hook in Azure DevOps.

常見問題

問:服務鉤子的承載限制為何?

一個: 承載限制為 2 MB。 較大的承載會導致效能及可靠性降低。 最佳實踐是,服務鉤子應將負載限制為 2 MB。

問:已啟用狀態(受限制)是什麼意思?

一個: 如果發生太多失敗,訂用帳戶就會受到限制。 處於 啟用(受限制) 狀態,與處於試用或限制階段相同。

問:為什麼訂閱會被停用?

A: 在下列情況下,訂閱會自動停用:

  • 發生終端機失敗。
  • 一連串的連續失敗會在很長的期間內發生。
  • 最近一次成功送達通知是在六個多月前。
  • 創建訂閱的使用者已不再是團隊成員。

問:狀態為已停用(因為失敗)是什麼意思?

答: 導致暫時性故障的通知會多次重試,才會被宣告為持續失敗。 在 試用期期間,對於持續失敗的通知,重試的次數是有限的。 如果所有緩刑重試失敗,訂用帳戶就會停用。

下列狀態代碼提供每種失敗類型的範例:

  • 暫時性:408(要求逾時)、502(錯誤的網關)、503(服務無法使用)、504(網關逾時)
  • 終端機:410(消失)
  • 持續性:非短暫或非致命的所有失敗

問:「因未活動而致殘」狀態是什麼意思?

答:訂閱最近一次成功發送通知是在六個多月前,因此 Azure DevOps 已停用該通知。 此狀態與因失敗而被停用的狀態不同,後者表示 Azure DevOps 嘗試交付但多次失敗。 如果還需要整合,請重新啟用訂閱。

問:為什麼未啟用的訂閱會被停用?

答:Azure DevOps 會在發布匹配事件時評估每個訂閱,即使接收整合已不再啟用。 隨著管道遭到淘汰、整合被棄用,組織久而久之可能會累積閒置的訂閱。 有些組織擁有數萬筆訂閱,卻多年未收到通知。 停用非使用中的訂閱,有助於讓服務掛鉤對仍在使用中的訂閱維持快速且可靠。

問:狀態為 Disabled (使用者已離開專案)代表什麼意思?

A:建立訂閱的使用者不再是團隊的成員。

問:如果服務掛鉤無法運作,應該嘗試什麼?

A: 檢查下列項目:

  • 確認訂用帳戶已啟用。
  • 確認訂用帳戶設定正確。 檢查事件篩選和動作。
  • 查看歷程記錄,特別是在發生失敗時。

問:我可以授與一般專案用戶檢視及管理專案的服務掛勾訂閱能力嗎?

一個: 根據預設,只有專案管理員具有這些許可權。 若要直接授權給其他使用者,請使用 命令列工具 或 Security REST API。

問:我是否可以以程序設計方式建立訂用帳戶?

甲: 是,請使用 REST APIs。