Azure 関数/REST API チェックを呼び出す

[アーティクル]
07/18/2023

Azure 関数/REST API チェックの呼び出しを使用して、特定のパイプラインステージが保護されたリソースへのアクセスを許可されるかどうかを判断するためのコードを作成できます。これらのチェックは 2 つのモードで実行できます。

非同期 (推奨): プッシュモード。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 チェックの呼び出しにも適用されます。

非同期チェックの推奨される実装

推奨される非同期モードには、次の 2 つの通信ステップがあります。

チェックペイロードを配信します。 Azure Pipelines が、Azure 関数/REST API に対して HTTP 呼び出しを行うのは、チェックペイロードを配信する "だけ" で、決定をその場で受け取るためでは "ありません"。関数は、情報の受信をただ確認して、Azure DevOps との HTTP 接続を終了する必要があります。チェック実装は、3 秒以内に HTTP 要求を処理する必要があります。
コールバックでアクセス決定を配信します。非同期でチェックを実行し、保護されているリソースにパイプラインがアクセスするために必要な条件を評価する必要があります (複数の評価を異なる時点で行う可能性があります)。最終的な決定に達すると、Azure 関数が Azure DevOps への HTTP REST 呼び出しを行って決定を伝えます。どの時点でも、Azure DevOps とチェック実装の間にオープンしている HTTP 接続が 1 つ存在する必要があります。こうすることで、Azure 関数側と Azure Pipelines 側の両方でリソースが節約されます。

チェックに成功すると、パイプラインは保護されたリソースへのアクセスを許可され、ステージの配置を続行できます。チェックに成功しないと、ステージは失敗します。 1 つのステージに複数のチェックがある場合、保護されたリソースへのアクセスが許可されるには、すべてが成功する必要があります。ただし、1 つが成功しないだけでステージは失敗します。

1 つの Azure 関数チェックの非同期モードの推奨実装を次の図に示します。

1 つの Azure 関数チェックの非同期モードの推奨実装を示す図。

図のステップは次のとおりです。

配信について調べます。 Azure Pipelines はパイプラインステージの配置を準備しており、保護されたリソースへのアクセスを必要とします。これが、対応する Azure 関数チェックを呼び出し、HTTP 200 状態コードで終わる呼び出しによって、受信確認を受け取ります。決定が保留されるため、ステージの配置は一時停止されます。
評価について調べます。このステップはAzure 関数の実装内で行われます。これは、ユーザー独自の Azure リソースで実行され、コードは完全にユーザーの制御下にあります。 Azure 関数が次の手順に従うことをお勧めします。
- 2.1 "非同期" タスクを開始し、200 HTTP 状態コードを返します
- 2.2 複数の条件評価を実行できる内部ループに入ります
- 2.3 アクセス条件を評価します
- 2.4 最終的な決定に到達できない場合は、条件の再評価を後の時点に再スケジュールしてステップ 2.3 に進みます
決定の伝達。 Azure 関数は、アクセスの決定を Azure Pipelines にコールバックします。ステージの配置を続行できます

推奨される実装を使用すると、パイプライン実行の詳細ページに最新のチェックログが表示されます。

パイプラインの実行の詳細とチェック情報のスクリーンショット。

非同期チェックの推奨される構成

[Azure Function / REST API check configuration] (Azure 関数/ REST API チェック構成) パネルで、次を確認します。

[完了イベント] で [コールバック] を選択しています
[Time between evaluations (minutes)] (評価の間隔 (分)) を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)" など、パイプラインの実行に使用されるビルド ID に対して発行されます。つまり、トークンを使用すると、ホストパイプラインと同じリポジトリまたはパイプライン実行にアクセスできます。 [Protect access to repositories in YAML pipelines] (YAML パイプランのリポジトリへのアクセスを保護する) を有効にした場合、そのスコープはパイプライン実行で参照されるリポジトリのみにさらに制限されます。

チェックが、パイプライン関連リソース以外 (Boards ユーザーストーリーなど) にアクセスする必要がある場合、そのようなアクセス許可をパイプラインのビルド ID に付与する必要があります。複数のプロジェクトからチェックをトリガーできる場合は、すべてのプロジェクト内のすべてのトリガーが必要なリソースにアクセスできるようにする必要があります。

決定を Azure DevOps に送り返す

チェック実装では、Post Event REST API 呼び出しを使用して、決定を Azure Pipelines に伝達する必要があります。次のプロパティを指定してください。

Headers: Bearer {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 にコールバックし、パイプライン実行の Timeline エントリを取得します
Timeline に "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (CmdLine タスクの ID) のタスクが含まれるかどうかを調べます
検索結果を含む状態の更新を送信します
チェックの決定を 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 では、1 つのチェックインスタンスが最大 2,000 回評価されます。

構成されたタイムアウト内にチェックが Azure Pipelines をコールバックしない場合、関連付けられているステージがスキップされます。それに依存するステージもスキップされます。

同期チェック

同期モードでは、Azure DevOps は Azure 関数/REST API チェックを呼び出して、保護されたリソースへのアクセスが許可されているかどうかをすぐに判断します。

1 つの Azure 関数チェックの同期モードの実装を次の図に示します。

1 つの Azure 関数チェックの同期モードの実装を示す図。

手順は次のとおりです。

Azure Pipelines はパイプラインステージの配置を準備しており、保護されたリソースへのアクセスを必要とします
次のような内部ループに入ります。

2.1. Azure Pipelines が、対応する Azure 関数チェックを呼び出して、決定を待機します
2.2. Azure 関数が、アクセスを許可するために必要な条件を評価し、決定を返します
2.3. Azure 関数の応答本文が、定義されている [成功の条件] を満たさず、[Time between evaluations] (評価の間隔) がゼロ以外である場合、Azure Pipelines は [Time between evaluations] (評価の間隔) 後に再度のチェック評価を再スケジュールします

同期チェックを構成する

Azure 関数/REST API の同期モードを使用するには、チェック構成パネルで次を確認します。

[詳細設定] の [完了イベント] で [ApiResponse] を選択しています
チェックの応答本文に基づいてチェックを成功にするタイミングを定義する [成功の条件] を指定しています
[管理オプション] で [Time between evaluations] (評価の間隔) を 0 に設定しています
チェックの成功を待機する期間を [タイムアウト] に設定しています。肯定的な決定がなく、[タイムアウト] に到達すると、対応するパイプラインステージはスキップされます

[Time between evaluations] (評価の間隔) 設定によって、チェックの決定が有効な期間が定義されます。値 0 は決定が最終であることを意味します。 0 以外の値は、決定が否定的だった場合に、構成された間隔の後にチェックが再試行されることを意味します。複数の承認とチェックが実行されている場合は、決定に関係なくチェックが再試行されます。

評価の最大回数は、[タイムアウト] 値と [Time between evaluations] (評価の間隔) 値の比率によって定義されます。この比率を 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 では、1 つのチェックインスタンスが最大 2,000 回評価されます。

非同期チェックと同期チェックを使用するタイミング

ユースケースの例と、使用するチェックとして推奨される種類を見てみましょう。

外部情報が正しい必要がある

たとえば、実稼働リソースへのサービス接続があるとき、ServiceNow チケット内の情報が正しい場合にのみ、そのリソースへのアクセスが許可されるようにします。この場合、フローは次のようになります。

ServiceNow チケットの正確性を検証する、"非同期" Azure 関数チェックを追加します
そのサービス接続を使用しようとするパイプラインが実行されるとき:
- Azure Pipelines がチェック関数を呼び出します
- 情報が正しくない場合、チェックは否定的な決定を返します。次の結果を想定します
- パイプラインステージが失敗します
- ServiceNow チケットの情報を更新します
- 失敗したステージを再び開始します
- チェックが再度実行され、今度は成功します
- パイプラインの実行が続行されます

外部承認を付与する必要がある

たとえば、実稼働リソースへのサービス接続があるとき、管理者が ServiceNow チケットを認証した後でのみ、そのリソースへのアクセスが許可されるようにします。この場合、フローは次のようになります。

ServiceNow チケットが承認されたことを検証する、"非同期" Azure 関数チェックを追加します
そのサービス接続を使用しようとするパイプラインが実行されるとき:
- Azure Pipelines がチェック関数を呼び出します。
- ServiceNow チケットが承認されない場合、Azure 関数は、Azure Pipelines に更新を送信し、チケットの状態をチェックするように15 分以内に再スケジュールします
- チケットが承認されると、チェックが、肯定的な決定で Azure Pipelines をコールバックします
- パイプラインの実行が続行されます

開発プロセスの後に続く

たとえば、実稼働リソースへのサービス接続があるとき、コードカバレッジが 80 % を超える場合にのみ、そのリソースへのアクセスが許可されるようにします。この場合、フローは次のようになります。

ステージエラーが原因でビルドが失敗するようにパイプラインを記述します
関連付けられたパイプライン実行のコードカバレッジを検証する "非同期" Azure 関数チェックを追加します
そのサービス接続を使用しようとするパイプラインが実行されるとき:
- Azure Pipelines がチェック関数を呼び出します
- コードカバレッジ条件が満たされないと、チェックは否定的な決定を返します。次の結果を想定します
- チェックエラーによりステージが失敗し、そのためにパイプライン実行が失敗します
エンジニアリングチームが、80% のコードカバレッジに到達するために必要な単体テストを追加します
新しいパイプライン実行がトリガーされ、今度はチェックに成功します
- パイプラインの実行が続行されます

パフォーマンス条件を満たす必要がある

たとえば、カナリア配置から開始して、複数のステップで新しいバージョンのシステムを配置するとします。カナリア配置のパフォーマンスが十分であることを確認する必要があります。この場合、フローは次のようになります。

"非同期" Azure 関数チェックを追加します
そのサービス接続を使用しようとするパイプラインが実行されるとき:
- Azure Pipelines がチェック関数を呼び出します
- チェックが、カナリア配置のパフォーマンスの監視を開始します
- チェックが、複数の評価チェックポイントをスケジュールして、パフォーマンスがどのように向上したかを確認します
- カナリア配置のパフォーマンスに十分な確信を得たら、Azure 関数が、肯定的な決定で Azure Pipelines にコールバックします
- パイプラインの実行が続行されます

配置の理由が有効でなければならない

たとえば、実稼働環境リソースへのサービス接続があるとき、手動でキューに登録されたビルドに対してのみアクセスを行うようにします。この場合、フローは次のようになります。

パイプライン実行の Build.Reason が Manual であることを検証する "同期" Azure 関数チェックを追加します
Headers で Build.Reason を渡すように Azure 関数を構成します
チェックの [Time between evaluations] (評価の間隔) を 0 に設定します。失敗または成功が確定され、再評価は必要なくなります
そのサービス接続を使用しようとするパイプラインが実行されるとき:
- Azure Pipelines がチェック関数を呼び出します
- 理由が Manual 以外の場合、チェックは失敗し、パイプライン実行が失敗します

ポリシー準拠状況の確認

Azure 関数と REST API チェックを呼び出すと、推奨される使用方法に一致する規則が組み込まれます。チェックは、モードと再試行回数に応じて、特定の規則に従う必要があります。

非同期チェック (コールバックモード): Azure Pipelines は非同期チェックを再試行しません。評価が最終的な場合は、非同期的に結果を提供する必要があります。非同期チェックを準拠していると見なすには、評価の間隔を 0 にする必要があります。
同期チェック (ApiResponse モード): チェックの再試行の最大数は 10 回です。さまざまな方法で設定できます。たとえば、タイムアウトを 20 に、評価の時間間隔を 2 に設定できます。または、タイムアウトを 100 に設定し、評価の時間間隔を 10 に設定できます。ただし、タイムアウトを 100 に設定し、評価の時間間隔を 2 に設定すると、50 回の再試行が要求されるため、チェックは準拠しなくなります。タイムアウトと評価間の時間間隔の比率は 10 以下である必要があります。

チェックコンプライアンスのロールアウトの詳細を学習します。

複数のチェック

Azure Pipelines がパイプライン実行でステージを配置する前に、複数のチェックに成功する必要がある場合があります。保護されたリソースに 1 つ以上のチェックが関連付けられている場合があります。 1 つのステージによって、複数の保護されたリソースが使用される場合があります。 Azure Pipelines は、ステージで使用される保護された各リソースに関連付けられているすべてのチェックを収集し、それらを同時に評価します。

パイプライン実行がステージへの配置を許可されるのは、"すべて" のチェックが同時に成功した場合のみです。最終的に否定的な決定が 1 つあると、パイプラインのアクセスが拒否され、ステージが失敗します。

推奨の方法 (非同期、最終状態) でチェックを使用すると、アクセスの決定が確定し、システムの状態を把握しやすくなります。

例については、「複数の承認とチェック」セクションを参照してください。

次の方法で共有

Azure 関数/REST API チェックを呼び出す

非同期チェック

非同期チェックの推奨される実装

非同期チェックの推奨される構成

パイプラインの実行情報をチェックに渡す

Azure DevOps を呼び出す

決定を Azure DevOps に送り返す

チェックから Azure DevOps に状態の更新を送信する

例

基本の Azure 関数チェック

高度な Azure 関数チェック

エラー処理

同期チェック

同期チェックを構成する

パイプラインの実行情報をチェックに渡す

エラー処理

非同期チェックと同期チェックを使用するタイミング

外部情報が正しい必要がある

外部承認を付与する必要がある

開発プロセスの後に続く

パフォーマンス条件を満たす必要がある

配置の理由が有効でなければならない

ポリシー準拠状況の確認

複数のチェック

詳細情報

フィードバック

その他のリソース