叫用 Azure 函式/REST API 檢查

發行項
01/10/2024

叫用 Azure 函式/REST API 檢查可讓您撰寫程式代碼，以決定是否允許特定管線階段存取受保護的資源。這些檢查可以透過兩種模式執行：

異步（建議）：推送模式，其中 Azure DevOps 會等候 Azure 函式/REST API 實作，以階段存取決策回呼至 Azure DevOps
同步：輪詢模式，其中 Azure DevOps 會定期呼叫 Azure 函式/REST API 以取得階段存取決策

在本指南的其餘部分，我們只會將 Azure 函式/REST API 檢查視為檢查。

建議使用檢查的方式處於異步模式。此模式提供您最高層級的檢查邏輯控制權、讓您輕鬆地推理系統處於何種狀態，並將 Azure Pipelines 與檢查實作分離，以提供最佳的延展性。所有同步檢查都可以使用異步檢查模式來實作。

異步檢查

在異步模式中，Azure DevOps 會呼叫 Azure 函式/REST API 檢查，並使用資源存取決策等候回呼。在等候期間，Azure DevOps 與檢查實作之間沒有開啟的 HTTP 連線。

本節的其餘部分會討論 Azure 函式檢查，但除非另有說明，否則指導方針也適用於叫用 REST API 檢查。

異步檢查的建議實作

建議的異步模式有兩個通訊步驟：

傳遞檢查承載。 Azure Pipelines 只會對 Azure 函式/REST API 進行 HTTP 呼叫，以提供檢查承載，而不是在現場收到決策。您的函式應該只會確認收到資訊，並終止與 Azure DevOps 的 HTTP 連線。您的檢查實作應在 3 秒內處理 HTTP 要求。
透過回呼傳遞存取決策。您的檢查應該以異步方式執行，評估管線存取受保護資源所需的條件（可能在不同的時間點執行多個評估）。一旦達成最終決策，您的 Azure 函式就會對 Azure DevOps 進行 HTTP REST 呼叫，以傳達決策。在任何時間點，Azure DevOps 與檢查實作之間應該會有單一開啟的 HTTP 連線。這麼做可節省 Azure 函式端和 Azure Pipelines 端的資源。

如果檢查通過，則允許管線存取受保護的資源，而階段部署可以繼續進行。如果檢查失敗，則階段會失敗。如果單一階段有多個檢查，則所有都需要在允許存取受保護資源之前通過，但單一失敗足以讓階段失敗。

下圖說明單一 Azure 函式檢查之異步模式的建議實作。

Diagram that shows the recommended implementation of the async mode for a single Azure Function check.

圖表中的步驟如下：

檢查傳遞。 Azure Pipelines 準備部署管線階段，而且需要存取受保護的資源。它會藉由 HTTP 200 狀態代碼結尾的呼叫叫用對應的 Azure 函式檢查並預期收到確認。暫止部署暫停，等待決策。
檢查評估。此步驟會在您的 Azure 函式實作內執行，其會在您自己的 Azure 資源上執行，而其程式代碼完全在您控制之下。我們建議您的 Azure 函式遵循下列步驟：
- 2.1 啟動異步工作並傳回 HTTP 狀態代碼 200
- 2.2 輸入內部迴圈，在其中可以執行多個條件評估
- 2.3 評估存取條件
- 2.4 如果無法達成最終決定，請重新排程條件重新評估一段時間，然後移至步驟 2.3
決策通訊。 Azure 函式會使用存取決策回呼 Azure Pipelines。階段部署可以繼續進行

當您使用建議的實作時，管線執行詳細數據頁面會顯示最新的檢查記錄。

Screenshot of pipeline run details with check information.

異步檢查的建議設定

在 Azure 函式/REST API 檢查組態面板中，確定您：

完成事件的選取回呼
將評估之間的時間（分鐘）設定為 0

將評估之間的時間設定為非零值表示檢查決策（通過/失敗）不是最終的。檢查會重新評估，直到所有其他核准和檢查都達到最終狀態為止。

傳遞管線執行資訊以檢查

設定檢查時，您可以指定您想要傳送至檢查的管線執行資訊。您至少應該傳送：

"PlanUrl": "$(system.CollectionUri)"
"ProjectId": "$(system.TeamProjectId)"
"HubName": "$(system.HostType)"
"PlanId": "$(system.PlanId)"
"JobId": "$(system.JobId)"
"TaskInstanceId": "$(system.TaskInstanceId)"
"AuthToken": "$(system.AccessToken)"

根據預設，這些索引鍵/值組會在 Azure Pipelines 進行的 REST 呼叫中 Headers 設定。

您應該使用 AuthToken 來呼叫 Azure DevOps，例如當您的檢查回呼時，請做出決定。

呼叫 Azure DevOps

若要達成決策，您的檢查可能需要無法傳遞至檢查的目前管線執行相關信息，因此檢查需要擷取它。假設您的檢查會驗證管線執行是否執行特定工作，例如靜態分析工作。您的檢查需要呼叫 Azure DevOps，並取得已執行的工作清單。

若要呼叫 Azure DevOps，建議您使用針對檢查執行發出的作業存取令牌，而不是個人存取令牌（PAT）。根據預設，令牌會提供給標頭中的 AuthToken 檢查。

相較於 PAT，作業存取令牌較不容易進行節流，不需要手動重新整理，也不會繫結至個人帳戶。令牌的有效時間為 48 小時。

使用作業存取令牌，但移除 Azure DevOps REST API 節流問題。當您使用 PAT 時，您會針對管線的所有執行使用相同的 PAT。如果您執行大量管線，則 PAT 會受到節流。這不是作業存取令牌的問題，因為每次檢查執行都會產生新的令牌。

令牌會針對用來執行管線的組建身分識別發出，例如 FabrikamFiberChat 建置服務（FabrikamFiber） 。換句話說，令牌可用來存取主機管線可以執行的相同存放庫或管線執行。如果您已啟用 保護 YAML 管線中存放庫的存取權，其範圍會進一步限制為只限於管線執行中所參考的存放庫。

如果您的檢查需要存取非管線相關資源，例如 Boards 用戶劇本，您應該將這類許可權授與管線的組建身分識別。如果可以從多個專案觸發檢查，請確定所有專案中的所有管線都可以存取所需的資源。

將決策傳送回 Azure DevOps

您的檢查實作必須使用 Post事件 REST API 呼叫，將決策傳達回 Azure Pipelines。請確定您指定下列屬性：

Headers: Basic: {AuthToken}
Body：

{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

從檢查將狀態更新傳送至 Azure DevOps

您可以使用 Azure Pipelines REST API，從檢查中提供 Azure Pipelines 使用者的狀態更新。例如，如果您想要讓使用者知道檢查正在等候外部動作，例如有人需要核准 ServiceNow 票證，這項功能就很有用。

傳送狀態更新的步驟如下：

所有 REST API 呼叫都必須經過驗證。

範例

基本 Azure 函式檢查

在此基本範例中，Azure 函式會先檢查叫用管線是否執行工作CmdLine，再授與受保護資源的存取權。

Azure 函式會逐步執行下列步驟：

確認檢查承載的收據
將狀態更新傳送至已啟動檢查的 Azure Pipelines
用來 {AuthToken} 對 Azure Pipelines 進行回呼，以擷取管線執行的時間軸專案
檢查時間軸是否包含具有 "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" 的工作（工作識別元 CmdLine ）
使用搜尋結果傳送狀態更新
將檢查決策傳送至 Azure Pipelines

您可以從 GitHub 下載此範例。

若要使用此 Azure 函式檢查，您必須在設定檢查時指定下列專案 Headers ：

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

進階 Azure 函式檢查

在此進階範例中，Azure 函式會檢查觸發管線執行的認可訊息中所參考的 Azure Boards 工作專案是否處於正確狀態。

Azure 函式會逐步執行下列步驟：

確認檢查承載的收據
將狀態更新傳送至已啟動檢查的 Azure Pipelines
用來 {AuthToken} 對 Azure Pipelines 進行回呼，以擷取觸發管線執行之認可訊息中所參考的 Azure Boards 工作項目狀態
檢查工作專案是否處於 Completed 狀態
使用檢查的結果傳送狀態更新
如果工作專案不在 Completed 狀態中，則會在1分鐘內重新排程另一個評估
工作項目處於正確狀態之後，就會將正面決策傳送至 Azure Pipelines

您可以從 GitHub 下載此範例。

若要使用此 Azure 函式檢查，您必須在設定檢查時指定下列專案 Headers ：

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

錯誤處理

目前，Azure Pipelines 最多會評估單一檢查實例 2,000 次。

如果您的檢查未在設定的逾時內回呼至 Azure Pipelines，則會略過相關聯的階段。視其而定的階段也會略過。

同步檢查

在同步模式中，Azure DevOps 會呼叫 Azure 函式/REST API 檢查，以立即決定是否允許存取受保護的資源。

下圖說明單一 Azure 函式檢查的同步模式實作。

Diagram that shows the implementation of the sync mode for a single Azure Function check.

步驟是：

Azure Pipelines 準備部署管線階段，且需要存取受保護的資源
它會進入內部迴圈，在此迴圈中：

2.1. Azure Pipelines 會叫用對應的 Azure 函式檢查，並等候決策
2.2. 您的 Azure 函式會評估允許存取並傳回決策所需的條件
2.3. 如果 Azure 函式響應主體不符合 您定義的成功準則 ，且評估之間的時間不是零，Azure Pipelines 會在評估之間的時間之後 重新排程另一個檢查評估

設定同步檢查

若要使用 Azure 函式/REST API 的同步模式，請在檢查組態面板中，確定您：

已針對 [進階] 下的 [完成] 事件選取 [ApiResponse]
指定成功準則，以根據檢查的回應本文來定義何時通過檢查
在 [控件] 選項下，將評估之間的時間設定為 0
將 [逾時] 設定為您想要等候檢查成功的時間長度。如果沒有正面決策且達到逾時，則會略過對應的管線階段

評估之間的時間設定會定義檢查決策的有效時間。值為 0 表示決策是最終決定。非零值表示當其決策為負數時，會在設定的間隔之後重試檢查。當多個核准和檢查正在執行時，不論決策為何，都會重試檢查。

評估數目上限是由評估值之間的逾時與時間之間的比率所定義。我們建議您確定此比率最多為 10。

傳遞管線執行資訊以檢查

設定檢查時，您可以指定您想要傳送至 Azure 函式/REST API 檢查的管線執行資訊。根據預設，Azure Pipeline 會在 HTTP 呼叫中 Headers 新增下列資訊。

"PlanUrl": "$(system.CollectionUri)"
"ProjectId": "$(system.TeamProjectId)"
"HubName": "$(system.HostType)"
"PlanId": "$(system.PlanId)"
"JobId": "$(system.JobId)"
"TaskInstanceId": "$(system.TaskInstanceId)"
"AuthToken": "$(system.AccessToken)"

我們不建議以同步模式對 Azure DevOps 進行呼叫，因為它很可能造成您的檢查需要 3 秒以上的回復時間，因此檢查失敗。

錯誤處理

目前，Azure Pipelines 最多會評估單一檢查實例 2,000 次。

使用異步檢查與同步檢查的時機

讓我們看看一些範例使用案例，以及要使用的建議檢查類型。

外部信息必須正確

假設您有生產資源的服務連線，而且您想要確保只有在 ServiceNow 票證中的資訊正確時，才允許存取它。在此情況下，流程如下所示：

您新增異步的 Azure 函式檢查，以驗證 ServiceNow 票證的正確性
當想要使用 Service 連線 ion 的管線執行時：
- Azure Pipelines 會呼叫您的檢查函式
- 如果資訊不正確，檢查會傳回負面決策。假設此結果
- 管線階段失敗
- 您會更新 ServiceNow 票證中的資訊
- 您重新啟動失敗的階段
- 檢查會再次執行，這次會成功
- 管線執行會繼續

必須授與外部核准

假設您有生產資源的服務連線，而且您想要確保只有在系統管理員核准 ServiceNow 票證之後，才允許存取它。在此情況下，流程如下所示：

您新增異步的 Azure 函式檢查，以驗證 ServiceNow 票證已核准
當想要使用 Service 連線 ion 的管線執行時：
- Azure Pipelines 會呼叫您的檢查函式。
- 如果未核准 ServiceNow 票證，Azure 函式會將更新傳送至 Azure Pipelines，並在 15 分鐘內重新排程檢查票證的狀態
- 票證核准後，檢查會以正面決策回呼 Azure Pipelines
- 管線執行會繼續

已遵循開發程式

假設您有服務連線生產資源，而且您想要確保只有在程式代碼涵蓋範圍超過 80% 時，才允許存取它。在此情況下，流程如下所示：

您會以這樣的方式撰寫管線，讓階段失敗導致組建失敗
您可以新增異步的 Azure 函式檢查，以驗證相關聯管線執行的程式代碼涵蓋範圍
當想要使用服務連線 ion 的管線執行時：
- Azure Pipelines 會呼叫您的檢查函式
- 如果不符合程式代碼涵蓋範圍條件，則檢查會傳回負面決策。假設此結果
- 檢查失敗會導致您的階段失敗，這會導致您的管線執行失敗
工程小組新增必要的單元測試，以達到80%的程式代碼涵蓋範圍
觸發新的管線執行，這次會通過檢查
- 管線執行會繼續

必須符合效能準則

假設您在多個步驟中部署新版的系統，從 Canary 部署開始。您想要確保 Canary 部署的效能已足夠。在此情況下，流程如下所示：

您新增 異步 Azure 函式 檢查
當想要使用 Service 連線 ion 的管線執行時：
- Azure Pipelines 會呼叫您的檢查函式
- 檢查會啟動 Canary 部署效能的監視
- 檢查會排程多個評估檢查點，以查看效能如何演進
- 一旦您對 Canary 部署的效能有足夠的信心，您的 Azure 函式會以正面決策回呼 Azure Pipelines
- 管線執行會繼續

部署原因必須有效

假設您有服務連線生產環境資源，而且您想要確保只有手動佇列組建才會存取它。在此情況下，流程如下所示：

您新增同步 Azure 函式檢查，確認Build.Reason管線執行是否為Manual
您可以設定 Azure 函式檢查以傳入 Build.Reason 其 Headers
您將評估之間的時間設定為 0，因此失敗或通過是最終的，而且不需要重新評估
當想要使用服務連線的管線執行時：
- Azure Pipelines 會呼叫您的檢查函式
- 如果原因不是 Manual，則檢查失敗，且管線執行失敗

檢查相容性

叫用 Azure 函式和 REST API 檢查現在包含符合建議使用方式的規則。檢查必須遵循這些規則，視模式和重試次數而定：

異步檢查（回呼模式）：Azure Pipelines 不會重試異步檢查。評估為最終時，您應該以異步方式提供結果。若要將異步檢查視為相容，評估之間的時間間隔必須是0。
同步檢查（ApiResponse 模式）：檢查重試次數上限為 10。您可以透過數種方式進行設定。例如，您可以將逾時設定為20，以及評估到2之間的時間間隔。或者，您可以將逾時設定為100，以及評估到10之間的時間間隔。但是，如果您將逾時設定為100，並將評估之間的時間間隔設定為2，則您的檢查不符合規範，因為您要求重試50次。評估之間的逾時與時間間隔的比例應該小於或等於10。

深入瞭解檢查合規性的推出。

多重檢查

在 Azure Pipelines 在管線執行中部署階段之前，可能需要通過多個檢查。受保護的資源可能會有一或多個與其相關聯的檢查。階段可能會使用多個受保護的資源。 Azure Pipelines 會收集與階段中使用的每個受保護資源相關聯的所有檢查，並同時評估它們。

只有在所有檢查同時通過時，才允許管線執行部署到階段。單一最終負面決策會導致管線遭到拒絕存取，而階段會失敗。

當您以建議的方式使用檢查時（異步，含最終狀態）會將其存取決策變成最終狀態，並輕鬆了解系統的狀態。

如需範例，請參閱 [多重核准和檢查] 區段。

叫用 Azure 函式/REST API 檢查

異步檢查

異步檢查的建議實作

異步檢查的建議設定

傳遞管線執行資訊以檢查

呼叫 Azure DevOps

將決策傳送回 Azure DevOps

從檢查將狀態更新傳送至 Azure DevOps

範例

基本 Azure 函式檢查

進階 Azure 函式檢查

錯誤處理

同步檢查

設定同步檢查

傳遞管線執行資訊以檢查

錯誤處理

使用異步檢查與同步檢查的時機

外部信息必須正確

必須授與外部核准

已遵循開發程式

必須符合效能準則

部署原因必須有效

檢查相容性

多重檢查

深入了解

意見反應

意見反應

其他資源