コマンドとイベントフックを使用して Azure Developer CLI ワークフローをカスタマイズする

2025-01-30

Azure Developer CLI では、ワークフローとデプロイをカスタマイズするためのさまざまな拡張ポイントがサポートされています。フックミドルウェアを使用すると、azd コマンドとサービスライフサイクルイベントの前後にカスタムスクリプトを実行できます。フックは、事前を使用して名前付け規則に従い、一致する azd コマンドまたはサービスイベント名のポスト プレフィックスを します。

たとえば、次のシナリオでカスタムスクリプトを実行できます。

依存関係管理をカスタマイズするには、プレリストア フックを使用します。
事前デプロイ フックを使用して、アプリをデプロイする前に外部の依存関係またはカスタム構成が配置されていることを確認します。
カスタムクリーンアップまたはログ記録を実行するには、ワークフローまたはパイプラインの末尾にある ポストアップ フックを使用します。

使用可能なフック

次の azd コマンドフックを使用できます。

prerestore と postrestore: パッケージの依存関係が復元される前と後に実行されます。
preprovision と postprovision: Azure リソースが作成される前後に実行されます。
predeploy と postdeploy: アプリケーションコードが Azure にデプロイされる前と後に実行します。
preup と postup: 結合されたデプロイパイプラインの前後に実行します。 Up は、restore、provision、および deploy を順番に実行する短縮コマンドです。
predown と postdown: リソースが削除される前と後に実行されます。

次のサービスライフサイクルイベントフックを使用できます。

prerestore と postrestore: サービスパッケージと依存関係が復元される前と後に実行されます。
prebuild と postbuild: サービスのソースコードまたはコンテナーがビルドされる前と後に実行されます。
prepackage と postpackage: アプリがデプロイ用にパッケージ化される前と後に実行されます。
predeploy と postdeploy: サービスコードが Azure にデプロイされる前と後に実行します。

フックの構成

フックは、ルートまたは特定のサービス構成内の azure.yaml ファイルに登録できます。すべての種類のフックでは、次の構成オプションがサポートされます。

shell: sh | pwsh
- メモ: pwshには PowerShell 7 が必要です。
run: インラインスクリプトまたはファイルへのパスを定義します。
continueOnError: コマンドフック中にスクリプトエラーが発生した後も、設定が継続して実行されます (既定値は false)。
interactive: 設定すると、実行中のスクリプトがコンソール stdinにバインドされ、stdout & stderr されます (既定値は false)。
windows: 入れ子になった構成が Windows OS にのみ適用されることを指定します。この構成オプションが除外されている場合、フックはすべてのプラットフォームで実行されます。
posix: 入れ子になった構成が POSIX ベースの OS (Linux & MaxOS) にのみ適用されることを指定します。この構成オプションが除外されている場合、フックはすべてのプラットフォームで実行されます。

フックの例

次の例では、さまざまな種類のフックの登録と構成を示します。

ルートコマンドの登録

フックは、azure.yaml ファイルのルートにある特定の azd コマンドに対して実行するように構成できます。

プロジェクトディレクトリ (azure.yaml ファイルが配置されている場所) は、コマンドフックの既定の現在の作業ディレクトリ (cwd) です。

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: # Example of an inline script. (shell is required for inline scripts)
    shell: sh
    run: echo 'Hello'
  preprovision: # Example of external script (Relative path from project root)
    run: ./hooks/preprovision.sh
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

サービスの登録

フックは、.yaml ファイルで定義されている特定のサービスに対してのみ実行するように構成することもできます。

サービスディレクトリ (azure.yaml ファイル内のサービス構成の project プロパティで定義されているのと同じパス) は、サービスフックの既定の cwd です。

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice
    hooks:
      prerestore: # Example of an inline script. (shell is required for inline scripts)
        shell: sh
        run: echo 'Restoring API service...'
      prepackage: # Example of external script (Relative path from service path)
        run: ./hooks/prepackage.sh

OS 固有のフック

必要に応じて、フックを Windows または Posix (Linux & MaxOS) で実行するように構成することもできます。既定では、Windows または Posix の構成が除外されている場合、フックはすべてのプラットフォームで実行されます。

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
hooks:
  prerestore: 
    posix: # Only runs on Posix environments
      shell: sh
      run: echo 'Hello'
   windows: # Only runs on Windows environments
     shell: pwsh
     run: Write-Host "Hello"
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

イベントごとに複数のフック

ルート登録レベルや特定のサービスなど、さまざまなスコープでイベントごとに複数のフックを構成できます。

name: example-project
services:
    api:
        project: src/api
        host: containerapp
        language: ts
        hooks:
            postprovision:
                - shell: sh
                  run: scripts/postprovision1.sh
                - shell: sh
                  run: scripts/postprovision2.sh
hooks:
    postprovision:
        - shell: sh
          run: scripts/postprovision1.sh
        - shell: sh
          run: scripts/postprovision2.sh

フックで環境変数を使用する

フックは、azd env get-values コマンドと azd set <key> <value> コマンドを使用して、.env ファイル内の環境変数を取得および設定できます。フックは、${YOUR_ENVIRONMENT VARIABLE} 構文を使用してローカル環境から環境変数を取得することもできます。 azd AZURE_ENV_NAME や AZURE_LOCATIONなど、コマンドの実行時に、.env ファイル内の特定の環境変数が自動的に設定されます。 main.bicep ファイルからの出力パラメーターも、.env ファイルに設定されます。環境変数の管理ページには、環境変数ワークフローに関する詳細情報が含まれています。

フックは、次の例に示すように、環境変数をインラインで、または参照されるスクリプトを使用して取得および設定できます。

name: azure-search-openai-demo
metadata:
  template: azure-search-openai-demo@0.0.2-beta
services:
  backend:
    project: ./app/backend
    language: py
    host: appservice
hooks:
  postprovision:
    windows: # Run referenced script that uses environment variables (script shown below)
      shell: pwsh
      run: ./scripts/prepdocs.ps1
      interactive: true
      continueOnError: false
    posix:
      shell: sh
      run: ./scripts/prepdocs.sh
      interactive: true
      continueOnError: false
  postdeploy: # Pull environment variable inline from local device and set in .env file
      shell: sh
      run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}

参照先: prepdocs.sh スクリプト:

echo "Loading azd .env file from current environment"

# Use the `get-values` azd command to retrieve environment variables from the `.env` file
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values) 
EOF

echo 'Creating python virtual environment "scripts/.venv"'
python3 -m venv scripts/.venv

echo 'Installing dependencies from "requirements.txt" into virtual environment'
./scripts/.venv/bin/python -m pip install -r scripts/requirements.txt

echo 'Running "prepdocs.py"'
./scripts/.venv/bin/python ./scripts/prepdocs.py './data/*' 
    --storageaccount "$AZURE_STORAGE_ACCOUNT"
    --container "$AZURE_STORAGE_CONTAINER"
    --searchservice "$AZURE_SEARCH_SERVICE"
    --openaiservice "$AZURE_OPENAI_SERVICE"
    --openaideployment "$AZURE_OPENAI_EMB_DEPLOYMENT"
    --index "$AZURE_SEARCH_INDEX"
    --formrecognizerservice "$AZURE_FORMRECOGNIZER_SERVICE"
    --tenantid "$AZURE_TENANT_ID" -v

ヘルプを要求する

バグの報告、ヘルプの要求、または Azure Developer CLI の新機能の提案方法については、のトラブルシューティングとサポートのに関するページを参照してください。

次の方法で共有

コマンドとイベント フックを使用して Azure Developer CLI ワークフローをカスタマイズする