Invocar verificações da Função do Azure / API REST

As verificações da API Invoke Azure Function / REST permitem que você escreva código para decidir se um estágio de pipeline específico tem permissão para acessar um recurso protegido ou não. Essas verificações podem ser executadas em dois modos:

• Assíncrono (Recomendado): modo push, no qual o Azure DevOps aguarda a implementação da Função do Azure/API REST para chamar de volta ao Azure DevOps com uma decisão de acesso ao estágio
• Síncrono: modo de sondagem, no qual o Azure DevOps chama periodicamente a Função/API REST do Azure para obter uma decisão de acesso ao estágio

No restante deste guia, nos referimos às Verificações da Função do Azure / API REST simplesmente como verificações.

A maneira recomendada de usar verificações é no modo assíncrono. Esse modo oferece o mais alto nível de controle sobre a lógica de verificação, facilita o raciocínio sobre em que estado o sistema está e separa o Azure Pipelines de sua implementação de verificações, fornecendo a melhor escalabilidade. Todas as verificações síncronas podem ser implementadas usando o modo de verificações assíncronas.

Verificações assíncronas

No modo assíncrono, o Azure DevOps faz uma chamada para a verificação da Função do Azure/API REST e aguarda um retorno de chamada com a decisão de acesso ao recurso. Não há nenhuma conexão HTTP aberta entre o Azure DevOps e sua implementação de verificação durante o período de espera.

O restante desta seção fala sobre as verificações do Azure Function, mas, a menos que indicado de outra forma, a orientação também se aplica às verificações da API REST Invoke.

Implementação recomendada de verificações assíncronas

O modo assíncrono recomendado tem duas etapas de comunicação:

1. Entregue a carga útil do cheque. O Azure Pipelines faz uma chamada HTTP para sua API do Azure Function/REST apenas para entregar a carga útil de verificação e não para receber uma decisão no local. Sua função deve apenas confirmar o recebimento das informações e encerrar a conexão HTTP com o Azure DevOps. Sua implementação de verificação deve processar a solicitação HTTP dentro de 3 segundos.
2. Entregue a decisão de acesso por meio de um retorno de chamada. Sua verificação deve ser executada de forma assíncrona, avaliar a condição necessária para que o pipeline acesse o recurso protegido (possivelmente fazendo várias avaliações em diferentes pontos no tempo). Assim que chegar a uma decisão final, sua Função do Azure fará uma chamada HTTP REST no Azure DevOps para comunicar a decisão. A qualquer momento, deve haver uma única conexão HTTP aberta entre o Azure DevOps e sua implementação de verificação. Isso economiza recursos no lado da Função do Azure e no lado do Azure Pipelines.

Se uma verificação for aprovada, o pipeline terá acesso a um recurso protegido e a implantação em estágio poderá prosseguir. Se uma verificação falhar, o estágio falhará. Se houver várias verificações em um único estágio, todas precisarão passar antes que o acesso aos recursos protegidos seja permitido, mas uma única falha é suficiente para falhar no estágio.

A implementação recomendada do modo assíncrono para uma única verificação de Função do Azure é descrita no diagrama a seguir.

As etapas no diagrama são:

1. Verificar Entrega. O Azure Pipelines se prepara para implantar um estágio de pipeline e requer acesso a um recurso protegido. Ele invoca a verificação correspondente da Função do Azure e espera a confirmação de recebimento, pela chamada que termina com um código de status HTTP 200. A implantação em estágio é pausada enquanto se aguarda uma decisão.
2. Verifique a avaliação. Esta etapa acontece dentro de sua implementação do Azure Function, que é executada em seus próprios recursos do Azure e cujo código está completamente sob seu controle. Recomendamos que a sua Função do Azure siga estes passos:
   • 2.1 Iniciar uma tarefa assíncrona e retornar o código de status HTTP 200
   • 2.2 Entre em um loop interno, no qual ele pode fazer várias avaliações de condição
   • 2.3 Avaliar as condições de acesso
   • 2.4 Se não conseguir chegar a uma decisão final, reagende uma reavaliação das condições para um ponto posterior e, em seguida, avance para o passo 2.3
3. Comunicação de Decisão. A função do Azure chama de volta para o Azure Pipelines com a decisão de acesso. A implantação em estágio pode prosseguir

Quando você usa a implementação recomendada, a página de detalhes de execução do pipeline mostra o log de verificação mais recente.

Configuração recomendada para verificações assíncronas

No painel de configuração de verificação da Função do Azure / API REST, certifique-se de que:

• Retorno de chamada selecionado para o evento Conclusão
• Definir Tempo entre avaliações (minutos) para 0

Definir o tempo entre as avaliações para um valor diferente de zero significa que a decisão de verificação (aprovação/reprovação) não é final. A verificação é reavaliada até que todas as outras Aprovações e Verificações atinjam um estado final.

Passar informações de execução de pipeline para verificações

Ao configurar a verificação, você pode especificar as informações de execução do pipeline que deseja enviar para a verificação. No mínimo, deve enviar:

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

Esses pares chave-valor são definidos, por padrão, na Headers chamada REST feita pelo Azure Pipelines.

Você deve usar AuthToken para fazer chamadas no Azure DevOps, como quando sua verificação chama de volta com uma decisão.

Ligue para o Azure DevOps

Para chegar a uma decisão, sua verificação pode precisar de informações sobre a execução de pipeline atual que não podem ser passadas para a verificação, portanto, a verificação precisa recuperá-la. Imagine que sua verificação verifica se uma execução de pipeline executou uma tarefa específica, por exemplo, uma tarefa de análise estática. Sua verificação precisa chamar o Azure DevOps e obter a lista de tarefas já executadas.

Para chamar o Azure DevOps, recomendamos que você use o token de acesso ao trabalho emitido para a execução da verificação, em vez de um token de acesso pessoal (PAT). O token já é fornecido às suas verificações por padrão, no AuthToken cabeçalho.

Em comparação com PATs, o token de acesso ao trabalho é menos propenso a ser limitado, não precisa de atualização manual e não está vinculado a uma conta pessoal. O token é válido por 48 horas.

Usar o token de acesso a trabalho praticamente remove os problemas de limitação da API REST do Azure DevOps. Quando você usa um PAT, está usando a mesma PAT para todas as execuções do seu pipeline. Se você executar um grande número de pipelines, a PAT será limitada. Isso é menos um problema com o token de acesso ao trabalho, uma vez que um novo token é gerado para cada execução de verificação.

O token é emitido para a identidade de compilação usada para executar um pipeline, por exemplo, o serviço de compilação FabrikamFiberChat (FabrikamFiber). Em outras palavras, o token pode ser usado para acessar os mesmos repositórios ou execuções de pipeline que o pipeline de host pode. Se você habilitou Proteger o acesso a repositórios em pipelines YAML, seu escopo será ainda mais restrito apenas aos repositórios referenciados na execução do pipeline.

Se sua verificação precisar acessar recursos não relacionados a Pipelines, por exemplo, histórias de usuários de Painéis, você deverá conceder essas permissões às identidades de compilação dos pipelines. Se sua verificação puder ser acionada a partir de vários projetos, certifique-se de que todos os pipelines em todos os projetos possam acessar os recursos necessários.

Enviar uma decisão de volta para o Azure DevOps

Sua implementação de verificação deve usar a chamada da API REST pós-evento para comunicar uma decisão de volta ao Azure Pipelines. Certifique-se de especificar as seguintes propriedades:

• Headers: Bearer {AuthToken}
• Body:

{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

Enviar atualizações de status para o Azure DevOps a partir de verificações

Você pode fornecer atualizações de status para usuários do Azure Pipelines de dentro de suas verificações usando APIs REST do Azure Pipelines. Essa funcionalidade é útil, por exemplo, se você deseja informar aos usuários que a verificação está aguardando uma ação externa, como alguém precisa aprovar um tíquete ServiceNow.

As etapas para enviar atualizações de status são:

1. Criar um registo de tarefas
2. Anexar ao log de tarefas
3. Atualizar registro de linha do tempo

Todas as chamadas à API REST precisam ser autenticadas.

Exemplos

Verificação básica da função do Azure

Neste exemplo básico, a Função do Azure verifica se a execução do pipeline de invocação executou uma CmdLine tarefa antes de conceder-lhe acesso a um recurso protegido.

A Função do Azure passa pelas seguintes etapas:

1. Confirma o recebimento da carga útil do cheque
2. Envia uma atualização de status para o Azure Pipelines que a verificação iniciou
3. Usa {AuthToken} para fazer um retorno de chamada no Azure Pipelines para recuperar a entrada da Linha do tempo da execução do pipeline
4. Verifica se a Linha do tempo contém uma tarefa com "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (a ID da CmdLine tarefa)
5. Envia uma atualização de status com o resultado da pesquisa
6. Envia uma decisão de verificação para o Azure Pipelines

Você pode baixar este exemplo do GitHub.

Para usar essa verificação do Azure Function, você precisa especificar o seguinte Headers ao configurar a verificação:

{
    "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)"
}

Verificação avançada da função do Azure

Neste exemplo avançado, a Função do Azure verifica se o item de trabalho do Azure Boards referenciado na mensagem de confirmação que disparou a execução do pipeline está no estado correto.

A Função do Azure passa pelas seguintes etapas:

1. Confirma o recebimento da carga útil do cheque
2. Envia uma atualização de status para o Azure Pipelines que a verificação iniciou
3. Usa {AuthToken} para fazer um retorno de chamada no Azure Pipelines para recuperar o estado do item de trabalho do Azure Boards referenciado na mensagem de confirmação que disparou a execução do pipeline
4. Verifica se o Completed item de trabalho está no estado
5. Envia uma atualização de status com o resultado da verificação
6. Se o item de trabalho não estiver no Completed estado, ele reagenda outra avaliação em 1 minuto
7. Quando o item de trabalho estiver no estado correto, ele enviará uma decisão positiva para o Azure Pipelines

Você pode baixar este exemplo do GitHub.

Para usar essa verificação do Azure Function, você precisa especificar o seguinte Headers ao configurar a verificação:

{
    "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)"
}

Processamento de erros

Atualmente, o Azure Pipelines avalia uma única instância de verificação no máximo 2.000 vezes.

Se sua verificação não chamar de volta para o Azure Pipelines dentro do tempo limite configurado, o estágio associado será ignorado. Etapas dependendo dele também são ignoradas.

Verificações síncronas

No modo síncrono, o Azure DevOps faz uma chamada para a verificação da Função do Azure/API REST para obter uma decisão imediata se o acesso a um recurso protegido é permitido ou não.

A implementação do modo de sincronização para uma única verificação de Função do Azure é descrita no diagrama a seguir.

Os passos são:

1. O Azure Pipelines se prepara para implantar um estágio de pipeline e requer acesso a um recurso protegido
2. Ele entra em um loop interno no qual:

• 2.1. O Azure Pipelines invoca a verificação de Função do Azure correspondente e aguarda uma decisão
• 2.2. Sua Função do Azure avalia as condições necessárias para permitir o acesso e retorna uma decisão
• 2.3. Se o corpo de resposta da Função do Azure não atender aos critérios de Sucesso definidos e o Tempo entre as avaliações for diferente de zero, o Azure Pipelines reagendará outra avaliação de verificação após Tempo entre avaliações

Configurar verificações síncronas

Para usar o modo síncrono para a Função do Azure / API REST, no painel de configuração de verificação, verifique se:

• ApiResponse selecionado para o evento Completion em Advanced
• Especificados os critérios de Sucesso que definem quando passar na verificação com base no corpo de resposta da verificação
• Defina o tempo entre as avaliações como 0 nas opções de controle
• Defina o tempo limite para quanto tempo você deseja esperar para que uma verificação seja bem-sucedida. Se não houver uma decisão positiva e o tempo limite for atingido, o estágio de pipeline correspondente será ignorado

A configuração Tempo entre avaliações define por quanto tempo a decisão do cheque é válida. Um valor 0 significa que a decisão é final. Um valor diferente de zero significa que a verificação será repetida após o intervalo configurado, quando sua decisão for negativa. Quando várias Aprovações e Verificações estão em execução, a verificação é repetida independentemente da decisão.

O número máximo de avaliações é definido pela razão entre os valores de Tempo Limite e Tempo entre as avaliações. Recomendamos que se certifique de que este rácio é, no máximo, 10.

Passar informações de execução de pipeline para verificações

Ao configurar a verificação, você pode especificar as informações de execução do pipeline que deseja enviar para sua verificação da Função do Azure/API REST. Por padrão, o Pipeline do Azure adiciona as seguintes informações na Headers chamada HTTP que faz.

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

Não recomendamos fazer chamadas para o Azure DevOps no modo síncrono, porque isso provavelmente fará com que sua verificação demore mais de 3 segundos para responder, portanto, a verificação falhará.

Processamento de erros

Atualmente, o Azure Pipelines avalia uma única instância de verificação no máximo 2.000 vezes.

Quando usar verificações assíncronas vs síncronas

Vejamos alguns exemplos de casos de uso e quais são os tipos de verificações recomendados para usar.

As informações externas devem estar corretas

Digamos que você tenha uma Conexão de Serviço com um recurso de produção e deseje garantir que o acesso a ela seja permitido somente se as informações em um tíquete do ServiceNow estiverem corretas. Neste caso, o fluxo seria o seguinte:

• Você adiciona uma verificação assíncrona do Azure Function que verifica a correção do tíquete ServiceNow
• Quando um pipeline que deseja usar a Conexão de Serviço é executado:
  • O Azure Pipelines chama sua função de verificação
  • Se a informação estiver incorreta, o cheque devolve uma decisão negativa. Assuma este resultado
  • O estágio de pipeline falha
  • Você atualiza as informações no tíquete ServiceNow
  • Reinicie o estágio com falha
  • A verificação é executada novamente e, desta vez, é bem-sucedida
  • A corrida do gasoduto continua

Aprovação externa deve ser concedida

Digamos que você tenha uma Conexão de Serviço com um recurso de produção e deseje garantir que o acesso a ela seja permitido somente depois que um administrador aprovar um tíquete do ServiceNow. Neste caso, o fluxo seria o seguinte:

• Você adiciona uma verificação assíncrona do Azure Function que verifica se o tíquete ServiceNow foi aprovado
• Quando um pipeline que deseja usar a Conexão de Serviço é executado:
  • O Azure Pipelines chama sua função de verificação.
  • Se o tíquete ServiceNow não for aprovado, a Função do Azure enviará uma atualização para o Azure Pipelines e se reagendará para verificar o estado do tíquete em 15 minutos
  • Depois que o tíquete é aprovado, a verificação é chamada de volta para o Azure Pipelines com uma decisão positiva
  • A corrida do gasoduto continua

O processo de desenvolvimento foi seguido

Digamos que você tenha uma conexão de serviço com um recurso de produção e deseje garantir que o acesso a ele seja permitido apenas se a cobertura do código for superior a 80%. Neste caso, o fluxo seria o seguinte:

• Você escreve seu pipeline de tal forma que falhas de estágio fazem com que a compilação falhe
• Você adiciona uma verificação assíncrona do Azure Function que verifica a cobertura de código para a execução de pipeline associada
• Quando um pipeline que deseja usar a Conexão de Serviço é executado:
  • O Azure Pipelines chama sua função de verificação
  • Se a condição de cobertura do código não for atendida, o cheque retornará uma decisão negativa. Assuma este resultado
  • A falha de verificação faz com que o estágio falhe, o que faz com que a execução do pipeline falhe
• A equipe de engenharia adiciona os testes de unidade necessários para alcançar 80% de cobertura de código
• Uma nova execução de pipeline é acionada e, desta vez, a verificação passa
  • A corrida do gasoduto continua

Os critérios de desempenho devem ser cumpridos

Digamos que você implante novas versões do seu sistema em várias etapas, começando com uma implantação canária. Você deseja garantir que o desempenho da sua implantação canária seja adequado. Neste caso, o fluxo seria o seguinte:

• Adicionar uma verificação assíncrona da Função do Azure
• Quando um pipeline que deseja usar a Conexão de Serviço é executado:
  • O Azure Pipelines chama sua função de verificação
  • A verificação inicia um monitor do desempenho da implantação canária
  • A verificação agenda vários pontos de verificação de avaliação, para ver como o desempenho evoluiu
  • Depois de ganhar confiança suficiente no desempenho da implantação canária, sua Função do Azure chama de volta para o Azure Pipelines com uma decisão positiva
  • A corrida do gasoduto continua

O motivo da implantação deve ser válido

Digamos que você tenha uma Conexão de Serviço com um recurso de ambiente de produção e deseje garantir que o acesso a ela aconteça apenas para compilações enfileiradas manualmente. Neste caso, o fluxo seria o seguinte:

• Você adiciona uma verificação síncrona do Azure Function que verifica se Build.Reason a execução do pipeline é Manual
• Você configura a verificação da Função do Azure para passar Build.Reason em seu Headers
• Você define o tempo da verificação entre as avaliações como 0, portanto, a reprovação ou aprovação é final e nenhuma reavaliação é necessária
• Quando um pipeline que deseja usar a Conexão de Serviço é executado:
  • O Azure Pipelines chama sua função de verificação
  • Se o motivo for diferente de Manual, a verificação falhará e a execução do pipeline falhará

Verificar conformidade

Invoque a função do Azure e as verificações da API REST agora incluem regras para corresponder ao uso recomendado. As verificações precisam seguir estas regras, dependendo do modo e do número de tentativas:

• Verificações assíncronas (modo de retorno de chamada): o Azure Pipelines não tenta novamente verificações assíncronas. Você deve fornecer um resultado de forma assíncrona quando uma avaliação for final. Para que as verificações assíncronas sejam consideradas conformes, o intervalo de tempo entre as avaliações tem de ser 0.

• Verificações síncronas (modo ApiResponse): O número máximo de novas tentativas para sua verificação é 10. Você pode fazer o set de várias maneiras. Por exemplo, você pode configurar o tempo limite para 20 e o intervalo de tempo entre as avaliações para 2. Ou, você pode configurar o tempo limite para 100 e o intervalo de tempo entre as avaliações para 10. Mas, se você configurar o tempo limite para 100 e definir o intervalo de tempo entre as avaliações para 2, sua verificação não será compatível porque você está pedindo 50 tentativas. O rácio entre o tempo limite e o intervalo de tempo entre as avaliações deve ser inferior ou igual a 10.

Saiba mais sobre a implementação da verificação de conformidade.

Verificações múltiplas

Antes do Azure Pipelines implantar um estágio em uma execução de pipeline, várias verificações podem precisar ser aprovadas. Um recurso protegido pode ter uma ou mais verificações associadas a ele. Um estágio pode usar vários recursos protegidos. O Azure Pipelines coleta todas as verificações associadas a cada recurso protegido usado em um estágio e as avalia simultaneamente.

Uma execução de pipeline só pode ser implantada em um estágio quando todas as verificações passam ao mesmo tempo. Uma única decisão final negativa faz com que o acesso ao pipeline seja negado e o estágio falhe.

Quando você usa verificações da maneira recomendada (assíncrona, com estados finais) torna suas decisões de acesso finais e facilita a compreensão do estado do sistema.

Consulte a secção Múltiplas Aprovações e Verificações para obter exemplos.

Mais informações

• Aprovações e verificações
• Invocar a tarefa de função do Azure
• Invocar tarefa da API REST