Partilhar via

Personalizar seus fluxos de trabalho da CLI do Azure Developer usando ganchos de comando e evento

Ganchos são azd pontos de extensão que executam automaticamente scripts personalizados antes e depois azd de comandos e eventos do ciclo de vida do serviço. Os ganchos seguem uma convenção de nomenclatura usando prefixos pré e pós no comando correspondente azd ou no nome do evento de serviço.

Por exemplo, talvez você queira executar um script personalizado nos seguintes cenários:

  • Use o gancho de pré-restauração para personalizar o gerenciamento de dependência.
  • Use o gancho de pré-implantação para verificar se dependências externas ou configurações personalizadas estão em vigor antes de implantar seu aplicativo.
  • Use o gancho de postagem no final de um fluxo de trabalho ou pipeline para executar limpeza ou registro personalizado.

Ganchos disponíveis

Os seguintes azd ganchos de comando estão disponíveis:

  • prerestore e postrestore: Executar antes e depois que as dependências do pacote forem restauradas.
  • preprovision e postprovision: Executar antes e depois da criação dos recursos do Azure.
  • prepackage e postpackage: Execute antes e depois que o aplicativo for empacotado.
  • predeploy e postdeploy: Execute antes e depois que o código do aplicativo for implantado no Azure.
  • prepublish e postpublish: Executar antes e depois da publicação da aplicação.
  • preup e postup: Executar antes e depois do pipeline de implantação combinado. Up é um comando abreviado que é executado restore, provisione deploy sequencialmente.
  • predown e postdown: Execute antes e depois que os recursos forem removidos.

Os seguintes ganchos de eventos do ciclo de vida do serviço estão disponíveis:

  • prerestore e postrestore: Executar antes e depois que os pacotes de serviço e as dependências forem restaurados.
  • prebuild e postbuild: Execute antes e depois que o código-fonte ou contêiner do serviço for criado.
  • prepackage e postpackage: Execute antes e depois que o aplicativo for empacotado para implantação.
  • predeploy e postdeploy: Execute antes e depois que o código de serviço for implantado no Azure.
  • prepublish e postpublish: Executar antes e depois da publicação do serviço.

Configuração do gancho

Os ganchos são registrados em seu azure.yaml arquivo na raiz ou dentro de uma configuração de serviço específica. Todos os tipos de ganchos suportam as seguintes opções de configuração:

  • shell: sh | pwsh
    • Nota: O PowerShell 7 é necessário para pwsho .
  • run: Defina um script embutido ou um caminho para um arquivo.
  • continueOnError: Quando definido continuará a ser executado mesmo depois que um erro de script ocorreu durante um gancho de comando (falso padrão).
  • interactive: Quando definido irá vincular o script em execução ao console stdin, stdout & stderr (padrão false).
  • windows: Especifica que as configurações aninhadas só serão aplicadas no sistema operacional Windows. Se essa opção de configuração for excluída, o gancho será executado em todas as plataformas.
  • posix: Especifica que as configurações aninhadas só se aplicarão a sistemas operacionais baseados em POSIX (Linux ou MaxOS). Se essa opção de configuração for excluída, o gancho será executado em todas as plataformas.

Exemplos de ganchos

Os exemplos a seguir demonstram diferentes tipos de registros e configurações de gancho.

Registro de comando raiz

Os ganchos podem ser configurados para serem executados para comandos específicos azd na raiz do seu azure.yaml arquivo.

O diretório do projeto (onde o azure.yaml arquivo está localizado) é o diretório de trabalho atual padrão (cwd) para ganchos de comando.

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

Registo do serviço

Os ganchos também podem ser configurados para serem executados apenas para serviços específicos definidos em seu .yaml arquivo.

O diretório de serviço (mesmo caminho definido na project propriedade da configuração de serviço no azure.yaml arquivo) é o padrão cwd para ganchos de serviço.

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

Ganchos específicos do SO

Opcionalmente, os ganchos também podem ser configurados para serem executados no Windows ou Posix (Linux ou MaxOS). Por padrão, se as configurações do Windows ou Posix forem excluídas, o gancho será executado em todas as plataformas.

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

Vários ganchos por evento

Você pode configurar vários ganchos por evento em escopos diferentes, como o nível de registro raiz ou para um serviço específico:

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

Executar ganchos de forma independente

O azd hooks run comando permite que você execute ganchos independentemente de seus eventos de gatilho normais. Isso é útil para testar e depurar ganchos sem passar por todo o fluxo de trabalho.

azd hooks run <hook-name>

Substitua <hook-name> pelo nome do gancho que você deseja executar (por exemplo, preprovision, postdeploy).

Opções avançadas

# Run a specific service hook
azd hooks run postdeploy --service api

# Force hooks to run for a specific platform
azd hooks run preprovision --platform windows

# Run hooks in a specific environment
azd hooks run postup -e staging

# Run hooks with all options combined
azd hooks run predeploy --service frontend --platform posix -e production --interactive

Configurar o modo interativo

Os ganchos são executados no modo interativo por padrão. O modo de ganchos interativos permite que você execute scripts de gancho com interação direta com o console, facilitando a depuração, o monitoramento e a interação com seus ganchos em tempo real. Você pode definir explicitamente a propriedade em sua configuração de gancho se quiser desativar o interactive modo interativo para um gancho específico:

hooks:
  postprovision:
    shell: sh
    run: ./scripts/setup-database.sh
    interactive: false # Default is true

Para ganchos específicos de serviço:

services:
  api:
    project: ./src/api
    language: js
    host: appservice
    hooks:
      postdeploy:
        shell: sh
        run: ./scripts/post-deploy-verification.sh
        interactive: false  # Override the default interactive mode

Usar variáveis de ambiente com ganchos

Os ganchos podem obter e definir variáveis de .env ambiente no arquivo usando os azd env get-values comandos and azd set <key> <value> . Os ganchos também podem recuperar variáveis de ambiente do seu ambiente local usando a ${YOUR_ENVIRONMENT VARIABLE} sintaxe. azd define automaticamente determinadas variáveis de ambiente no arquivo quando os .env comandos são executados, como AZURE_ENV_NAME e AZURE_LOCATION. Os parâmetros de saída do main.bicep arquivo também são definidos no .env arquivo. A página gerenciar variáveis de ambiente inclui mais informações sobre fluxos de trabalho de variáveis de ambiente.

Os ganchos podem obter e definir variáveis de ambiente embutidas ou por meio de scripts referenciados, conforme demonstrado no exemplo a seguir:

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}

O script: prepdocs.sh referenciado:

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

Pedir ajuda

Para obter informações sobre como arquivar um bug, solicitar ajuda ou propor um novo recurso para a CLI do Desenvolvedor do Azure, visite a página de solução de problemas e suporte .

  • Last updated on