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

  • [アーティクル]

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

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

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

使用可能なフック

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

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

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

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

フック構成

フックは、azure.yaml ファイルの root または特定のサービス構成内に登録できます。 どのタイプのフックでも、次の構成オプションをサポートしています。

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

フックの例

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

root コマンドの登録

フックは、azure.yaml ファイルの root にある特定の 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

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

フックは、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 の新機能の提案を行う方法については、トラブルシューティングとサポートのページを参照してください。