Compartilhar via

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

  • Artigo

A CLI do Desenvolvedor do Azure dá suporte a vários pontos de extensão para personalizar seus fluxos de trabalho e implantações. O middleware de ganchos permite executar scripts personalizados antes e depois de azd comandos e eventos de ciclo de vida do serviço. os ganchos seguem uma convenção de nomenclatura usando pre e pós- prefixos no comando azd correspondente 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é-armazenamento para personalizar o gerenciamento de dependências.
  • Use o gancho de pré-implantação para verificar se as dependências externas ou as configurações personalizadas estão em vigor antes de implantar seu aplicativo.
  • Use o postup gancho no final de um fluxo de trabalho ou pipeline para executar limpeza personalizada ou registro em log.

Ganchos disponíveis

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

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

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

  • prerestore e postrestore: execute 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 do serviço ou contêiner for criado.
  • prepackage e postpackage: execute antes e depois de o aplicativo ser empacotado para implantação.
  • predeploy e postdeploy: execute antes e depois que o código de serviço for implantado no Azure.

Configuração do gancho

Os ganchos podem ser registrados no arquivo azure.yaml na raiz ou em uma configuração de serviço específica. Todos os tipos de ganchos dão suporte às seguintes opções de configuração:

  • shell: sh | pwsh
    • Observação: o PowerShell 7 é necessário para pwsh.
  • run: defina um script embutido ou um caminho para um arquivo.
  • continueOnError: quando o conjunto continuará a ser executado mesmo depois de ocorrer um erro de script durante um gancho de comando (falso padrão).
  • interactive: quando definido associará o script em execução ao console stdin, stdout & stderr (falso padrão).
  • 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 se aplicarão somente a OSes baseados em POSIX (Linux & MaxOS). Se essa opção de configuração for excluída, o gancho será executado em todas as plataformas.

Exemplos de gancho

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 azd específicos na raiz do arquivo azure.yaml.

O diretório do projeto (em que o arquivo azure.yaml 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

Registro de serviço

Os ganchos também podem ser configurados para execução somente para serviços específicos definidos em seu arquivo de .yaml.

O diretório de serviço (mesmo caminho definido na propriedade project da configuração de serviço no arquivo azure.yaml) é o cwd padrão 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 sistema operacional

Opcionalmente, os ganchos também podem ser configurados para serem executados no Windows ou posix (Linux & 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 diferentes escopos, 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

Usar variáveis de ambiente com ganchos

Os ganchos podem obter e definir variáveis de ambiente no arquivo .env usando os comandos azd env get-values e azd set <key> <value>. Os ganchos também podem recuperar variáveis de ambiente do seu ambiente local usando a sintaxe ${YOUR_ENVIRONMENT VARIABLE}. azd define automaticamente determinadas variáveis de ambiente no arquivo .env quando os comandos são executados, como AZURE_ENV_NAME e AZURE_LOCATION. Os parâmetros de saída do arquivo main.bicep também são definidos no arquivo .env. 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 referenciado: 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

Solicitar 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 solução de problemas e suporte.