Verificações de Invocação da Função do Azure/API REST

As Verificações de Invocação da Função do Azure/API REST permitem que você grave o código para decidir se uma fase de pipeline específica tem permissão para acessar um recurso protegido. Essas verificações podem ser executadas de dois modos:

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

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

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

Verificações assíncronas

No modo assíncrono, o Azure DevOps faz uma chamada à 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á conexão HTTP em aberto 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 da Função do Azure, mas a menos que indicado de outra forma, as diretrizes também se aplicam às Verificações de Invocação da API REST.

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

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

1. Fornecer o conteúdo de verificação. O Azure Pipelines faz uma chamada HTTP para sua Função do Azure/API REST apenas para fornecer o conteúdo de verificação e não para receber uma decisão no spot. Sua função deve apenas reconhecer o recebimento das informações e terminar a conexão HTTP com o Azure DevOps. Sua implementação de verificação deve processar a solicitação HTTP em 3 segundos.
2. Fornecer 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). Depois de chegar a uma decisão final, sua Função do Azure faz uma chamada REST HTTP para o Azure DevOps, para comunicar a decisão. A qualquer momento, deve haver uma única conexão HTTP em aberto entre o Azure DevOps e sua implementação de verificação. Isso salva recursos no lado da Função do Azure e no lado do Azure Pipelines.

Se uma verificação for aprovada, o pipeline poderá acessar um recurso protegido e a implantação de fase poderá continuar. Se uma verificação falhar, a fase falhará. Se houver várias verificações em uma única fase, todas precisarão ser aprovadas antes que o acesso a recursos protegidos seja permitido, mas uma única falha é suficiente para reprovar a fase.

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

As etapas no diagrama são:

1. Entrega da Verificação. O Azure Pipelines se prepara para implantar uma fase de pipeline e requer acesso a um recurso protegido. Ele invoca a verificação da Função do Azure correspondente e espera a confirmação de recebimento pela chamada que termina com um código de status HTTP 200. A implantação de fase está pausada, aguardando uma decisão.
2. Avaliação da Verificação. Essa etapa ocorre dentro da sua implementação de Função do Azure, que é executada nos seus próprios recursos do Azure e cujo código está completamente sob seu controle. Recomendamos que sua Função do Azure siga estas etapas:
   • 2.1 Inicie uma tarefa assíncrona e retorne o código de status HTTP 200
   • 2.2 Insira um loop interno, no qual ele pode fazer várias avaliações de condição
   • 2.3 Avalie as condições de acesso
   • 2.4 Se não conseguir chegar a uma decisão final, reagende uma reavaliação das condições em um ponto posterior e vá para a etapa 2.3
3. Comunicação da Decisão. A função do Azure faz um retorno de chamada para o Azure Pipelines com a decisão de acesso. A implantação de fase pode continuar

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, verifique se você:

• Selecionou o Retorno de chamada para o Evento de conclusão
• Definiu o Tempo entre avaliações (minutos) como 0

Definir o Tempo entre avaliações como um valor diferente de zero significa que a decisão da verificação (aprovação/falha) 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 as verificações

Ao configurar a verificação, você pode especificar as informações de execução de pipeline que deseja enviar para sua verificação. No mínimo, você 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, no Headers da chamada REST feita pelo Azure Pipelines.

Você deve usar AuthToken para fazer chamadas para o Azure DevOps, como quando a verificação faz o retorno de chamada com uma decisão.

Chamada ao 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á-las. Imagine que sua verificação constata que 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 PAT (token de acesso pessoal). O token já é fornecido às suas verificações por padrão, no cabeçalho AuthToken.

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 um conta pessoal. O token é válido por 48 horas.

Usar o token de acesso ao trabalho elimina os problemas de limitação da API REST do Azure DevOps. Ao usar um PAT, você está usando o mesmo PAT para todas as execuções do pipeline. Se você executar um grande número de pipelines, o PAT será limitado. Isso é menos um problema com o token de acesso ao trabalho, pois um novo token é gerado para cada execução de verificação.

O token é emitido para a identidade de build usada para executar um pipeline, por exemplo, 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. 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 a verificação precisar acessar recursos não relacionados a pipelines, por exemplo, histórias de usuários do Boards, você deverá conceder essas permissões às identidades de build dos pipelines. Se for possível disparar a verificação de vários projetos, verifique se todos os pipelines em todos os projetos podem acessar os recursos necessários.

Enviar uma decisão para o Azure DevOps

Sua implementação de verificação deve usar a chamada à API REST Pós-Evento para comunicar uma decisão para o Azure Pipelines. Especifique 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 das verificações

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

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

1. Criar um log de tarefas
2. Acrescentar 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 tarefa CmdLine, antes de conceder a ela acesso a um recurso protegido.

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

1. Confirma o recebimento do conteúdo de verificação
2. Envia uma atualização de status para o Azure Pipelines de que a verificação foi iniciada
3. Usa {AuthToken} para fazer um retorno de chamada para o 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 tarefa CmdLine)
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 da Função do Azure, 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 no mensagem do commit que disparou a execução do pipeline está no estado correto.

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

1. Confirma o recebimento do conteúdo de verificação
2. Envia uma atualização de status para o Azure Pipelines de que a verificação foi iniciada
3. Usa {AuthToken} para fazer um retorno de chamada para o Azure Pipelines para recuperar o estado do item de trabalho do Azure Boards referenciado no mensagem do commit que disparou a execução do pipeline
4. Verifica se o item de trabalho está no estado Completed
5. Envia uma atualização de status com o resultado da verificação
6. Se o item de trabalho não estiver no estado Completed, ele reagendará outra avaliação em 1 minuto
7. Depois que 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 da Função do Azure, 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)"
}

Tratamento de erros

No momento, o Azure Pipelines avalia uma única instância de vezes, no máximo, 2.000 vezes.

Se a verificação não fizer o retorno de chamada para o Azure Pipelines no tempo limite configurado, a fase associada será ignorada. As fases que dependem disso também serão ignoradas.

Verificações síncronas

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

A implementação do modo síncrono para uma única verificação da Função do Azure está descrita no diagrama a seguir.

As etapas são:

1. O Azure Pipelines se prepara para implantar uma fase de pipeline e requer acesso a um recurso protegido
2. Ele insere um loop interno no qual:

• 2.1. O Azure Pipelines invoca a verificação da 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 da resposta da Função do Azure não atender aos critérios de êxito definidos e o Tempo entre as avaliações for diferente de zero, o Azure Pipelines reagendará outra avaliação de verificação após o 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, certifique-se de que você:

• Selecionou ApiResponse para o Evento de conclusão em Avançado
• Especificou os critérios de êxito que definem quando aprovar a verificação com base no corpo da resposta da verificação
• Definir Tempo entre avaliações como 0 em Opções de controle
• Definiu o Tempo Limite pelo qual você deseja esperar que uma verificação seja bem-sucedida. Se não houver uma decisão positiva e o Tempo limite for atingido, a fase de pipeline correspondente será ignorada

A configuração Tempo entre avaliações define por quanto tempo a decisão de verificação será válida. Um valor de 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 taxa entre os valores Timeout e Time entre avaliações. Recomendamos que você verifique se essa taxa é no máximo 10.

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

Ao configurar a verificação, você pode especificar as informações de execução de pipeline que deseja enviar para sua verificação da Função do Azure/API REST. Por padrão, o Azure Pipeline adiciona as seguintes informações no Headers da chamada HTTP que ele 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, pois provavelmente fará com que sua verificação leve mais de 3 segundos para responder, de modo que a verificação falhará.

Tratamento de erros

No momento, o Azure Pipelines avalia uma única instância de vezes, no máximo, 2.000 vezes.

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

Vamos examinar alguns casos de uso de exemplo e quais são os tipos recomendados de verificações a serem usadas.

As informações externas devem estar corretas

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

• Você adiciona uma verificação assíncrona da Função do Azure que verifica a exatidão do tíquete do 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 as informações estiverem incorretas, a verificação retornará uma decisão negativa. Suponha este resultado
  • A fase de pipeline falha
  • Você atualiza as informações no tíquete do ServiceNow
  • Você reinicia a fase com falha
  • A verificação é executada novamente e desta vez é bem-sucedida
  • A execução do pipeline continua

A aprovação externa deve ser concedida

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

• Você adiciona uma verificação assíncrona da Função do Azure que verifica se o tíquete do 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 do ServiceNow não for aprovado, a Função do Azure enviará uma atualização para o Azure Pipelines e será reagendada para verificar o estado do tíquete em 15 minutos
  • Depois que o tíquete for aprovado, a verificação fará um retorno de chamada para o Azure Pipelines com uma decisão positiva
  • A execução do pipeline continua

O processo de desenvolvimento foi seguido

Digamos que você tenha uma Conexão de Serviço com um recurso de produção e deseja garantir que o acesso a ele seja permitido somente se a cobertura de código estiver acima de 80%. Nesse caso, o fluxo seria o seguinte:

• Você grava seu pipeline de forma que falhas de fase causem uma falha no build
• Você adiciona uma verificação assíncrona da Função do Azure 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 de código não for atendida, a verificação retornará uma decisão negativa. Suponha este resultado
  • A falha de verificação faz com que a fase falhe, o que faz com que a execução do pipeline falhe
• A equipe de engenharia adiciona os testes de unidade necessários para atingir 80% de cobertura de código
• Uma nova execução de pipeline é disparada e, desta vez, a verificação é aprovada
  • A execução do pipeline continua

Os critérios de desempenho devem ser atendidos

Digamos que você implante novas versões do sistema em várias etapas, começando com uma implantação canário. Convém garantir que o desempenho da implantação canário seja adequado. Nesse caso, o fluxo seria o seguinte:

• Você adiciona 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ário
  • A verificação agenda vários pontos de verificação de avaliação para ver como o desempenho evoluiu
  • Depois que você ganhar confiança suficiente no desempenho da implantação canário, sua Função do Azure fará um retorno de chamada para o Azure Pipelines com uma decisão positiva
  • A execução do pipeline 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 queira garantir que o acesso a ele ocorra apenas para builds enfileirados manualmente. Nesse caso, o fluxo seria o seguinte:

• Você adiciona uma verificação síncrona da Função do Azure que verifica se o Build.Reason para a execução do pipeline é Manual
• Você configura a verificação da Função do Azure para aprovar o Build.Reason no Headers
• Você definiu o Tempo entre avaliações da verificação como 0. Portanto, a falha ou aprovação é final e nenhuma reavaliação será 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 essas 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 precisa ser 0.

• Verificações síncronas (modo ApiResponse): o número máximo de 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. Porém, se você configurar o tempo limite para 100 e definir o intervalo de tempo entre as avaliações como 2, sua verificação não será compatível porque você está solicitando 50 tentativas. A relação entre o tempo limite e o intervalo de tempo entre as avaliações deve ser menor que ou igual a 10.

Saiba mais sobre a implantação da conformidade de verificações.

Várias verificações

Antes que o Azure Pipelines implante uma fase 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. Uma fase pode usar vários recursos protegidos. O Azure Pipelines coleta todas as verificações associadas a cada recurso protegido usado em uma fase e as avalia simultaneamente.

Uma execução de pipeline tem permissão para ser implantada em uma fase somente quando todas as verificações são aprovadas ao mesmo tempo. Uma única decisão negativa final faz com que o acesso ao pipeline seja negado e causa a falha da fase.

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.

Confira a seção Várias Aprovações e Verificações para obter exemplos.

Saiba mais

• Aprovações e verificações
• Tarefa de Invocação da Função do Azure
• Tarefa de Invocação da API REST