Compartir vía

Comprobaciones de Invocar Función de Azure / API REST.

  • Artículo

Las comprobaciones de Invocar Función de Azure / API REST permiten escribir código para decidir si una fase de canalización específica tiene permiso para acceder a un recurso protegido o no. Estas comprobaciones se pueden ejecutar de dos modos:

  • Asincrónico (recomendado): modo de inserción, en el que Azure DevOps espera la implementación de Función de Azure / API REST para volver a llamar a Azure DevOps con una decisión de acceso de fase.
  • Sincrónico: modo de sondeo, en el que Azure DevOps llama periódicamente a Función de Azure / API REST para obtener una decisión de acceso a fase.

En el resto de esta guía, nos referimos a las comprobaciones de Función de Azure / API REST simplemente como comprobaciones.

La manera recomendada de utilizar las comprobaciones es en modo asincrónico. Este modo le ofrece el mayor nivel de control sobre la lógica de comprobación, facilita la razón sobre el estado en el que se encuentra el sistema y desacopla Azure Pipelines de la implementación de comprobaciones, lo que proporciona la mejor escalabilidad. Todas las comprobaciones sincrónicas se pueden implementar mediante el modo de comprobaciones asincrónicas.

Comprobaciones asincrónicas

En modo asincrónico, Azure DevOps realiza una llamada a la comprobación de Función de Azure / API REST y espera una devolución de llamada con la decisión de acceso a los recursos. No hay ninguna conexión HTTP abierta entre Azure DevOps y la implementación de las comprobaciones durante el período de espera.

En el resto de esta sección se describen las comprobaciones de Función de Azure, pero a menos que se indique lo contrario, las instrucciones también se aplican a las comprobaciones de Invocar API REST.

El modo asincrónico recomendado tiene dos pasos de comunicación:

  1. Entrega de la carga de comprobación. Azure Pipelines realiza una llamada HTTP a Función de Azure / API REST solo para entregar la carga de comprobación y no para recibir una decisión de inmediato. La función solo debe confirmar la recepción de la información y finalizar la conexión HTTP con Azure DevOps. La implementación de comprobación debe procesar la solicitud HTTP en un plazo de 3 segundos.
  2. Entrega de la decisión de acceso mediante una devolución de llamada. Debe ejecutar la comprobación de forma asincrónica, evaluar la condición necesaria para que la canalización acceda al recurso protegido (posiblemente realizando varias evaluaciones en diferentes momentos). Una vez que llegue a una decisión final, Función de Azure realiza una llamada HTTP REST a Azure DevOps para comunicar la decisión. En cualquier momento, debe haber una única conexión HTTP abierta entre Azure DevOps y la implementación de comprobación. Al hacerlo, se ahorran recursos tanto en el lado de Función de Azure como en el de Azure Pipelines.

Si se supera una comprobación, la canalización puede acceder a un recurso protegido, y la implementación de la fase puede continuar. Si se produce un error en una comprobación, se produce un error en la fase. Si hay varias comprobaciones en una sola fase, se deben superar todas antes de permitir el acceso a los recursos protegidos, pero un único error es suficiente para producir un error en la fase.

En el diagrama siguiente se muestra la implementación recomendada del modo asincrónico para una única comprobación de Función de Azure.

Diagrama que muestra la implementación recomendada del modo asincrónico para una única comprobación de Función de Azure.

Los pasos del diagrama son:

  1. Comprobación de la entrega. Azure Pipelines se prepara para implementar una fase de canalización y requiere acceso a un recurso protegido. Invoca la comprobación de Función de Azure correspondiente y espera la confirmación de recepción, mediante la llamada que termina con un código de estado HTTP 200. La implementación de la fase está en pausa, pendiente de una decisión.
  2. Comprobación de la evaluación. Este paso se produce dentro de la implementación de Función de Azure, que se ejecuta en sus propios recursos de Azure y cuyo código está bajo su total control. Se recomienda que la función de Azure siga estos pasos:
    • 2.1 Iniciar una tarea asincrónica y devolver código de estado HTTP 200.
    • 2.2 Escribir un bucle interno, en el que puede realizar varias evaluaciones de condición.
    • 2.3 Evaluar las condiciones de acceso.
    • 2.4 Si no se puede llegar a una decisión final, volver a programar una reevaluación de las condiciones para un momento posterior e ir luego al paso 2.3.
  3. Comunicación de decisión. Función de Azure vuelve a llamar a Azure Pipelines con la decisión de acceso. La implementación de la fase puede continuar.

Al usar la implementación recomendada, la página de detalles de ejecución de canalización muestra el registro de comprobación más reciente.

Captura de pantalla de los detalles de ejecución de la canalización con la información de comprobación.

En el panel de configuración de comprobaciones de Función de Azure / API REST, asegúrese de:

  • Seleccionar Devolución de llamada para Evento de finalización.
  • Establecido Tiempo entre evaluaciones (minutos) en 0.

Establecer Tiempo entre evaluaciones en un valor distinto a cero significa que la decisión de comprobación (aprobación / error) no es final. La comprobación se vuelve a evaluar hasta que todas las demás aprobaciones y comprobaciones alcancen un estado final.

Pasar información de ejecución de canalización a comprobaciones

Al configurar la comprobación, puede especificar la información de ejecución de la canalización que desea enviar a la comprobación. Como mínimo, debe enviar:

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

Estos pares clave-valor se establecen de forma predeterminada en Headers de la llamada REST realizada por Azure Pipelines.

Debe usar AuthToken para realizar llamadas a Azure DevOps, como cuando vuelve a comprobar las llamadas con una decisión.

Llamada a Azure DevOps

Para tomar una decisión, es posible que la comprobación necesite información sobre la ejecución de canalización actual que no se puede pasar a la comprobación, por lo que la comprobación debe recuperarla. Imagine que la comprobación comprueba que una ejecución de canalización ha ejecutado una tarea determinada, por ejemplo, una tarea de análisis estático. La comprobación debe llamar a Azure DevOps y obtener la lista de tareas ya ejecutadas.

Para llamar a Azure DevOps, se recomienda usar el token de acceso del trabajo emitido para la ejecución de la comprobación, en lugar de un token de acceso personal (PAT). El token ya se ha proporcionado a las comprobaciones de forma predeterminada, en el encabezado AuthToken.

En comparación con los tokens de acceso personal, el token de acceso del trabajo es menos propenso a limitarse, no necesita actualización manual y no está vinculado a una cuenta personal. El token es válido durante 48 horas.

El uso del token de acceso del trabajo elimina prácticamente los problemas de limitaciones de la API REST de Azure DevOps. Cuando se utiliza un PAT, se usa el mismo PAT para todas las ejecuciones de la canalización. Si ejecuta un gran número de canalizaciones, el PAT se limita. Esto es menos un problema con el token de acceso del trabajo, ya que se genera un nuevo token para cada ejecución de comprobación.

El token se emite para la identidad de compilación que se utiliza para ejecutar una canalización, por ejemplo, el servicio de compilación FabrikamFiberChat (FabrikamFiber). En otras palabras, el token se puede usar para acceder a los mismos repositorios o ejecuciones de canalización que a los que pueda acceder la canalización de host. Si ha habilitado Proteger el acceso a los repositorios en canalizaciones YAML, su ámbito solo se restringe a los repositorios a los que se hace referencia en la ejecución de la canalización.

Si la comprobación necesita acceder a recursos relacionados que no sean canalizaciones, por ejemplo, casos de usuario de Boards, debe conceder dichos permisos a identidades de compilación de canalizaciones. Si la comprobación se puede desencadenar desde varios proyectos, asegúrese de que todas las canalizaciones de todos los proyectos puedan acceder a los recursos necesarios.

Envío de una decisión a Azure DevOps

La implementación de comprobación debe usar la llamada a la API REST Post Event para comunicar una decisión a Azure Pipelines. Asegúrese de especificar las siguientes propiedades:

  • Headers: Bearer {AuthToken}
  • Body:
{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

Envío de actualizaciones de estado a Azure DevOps desde comprobaciones

Puede proporcionar actualizaciones de estado a los usuarios de Azure Pipelines desde las comprobaciones mediante las API REST de Azure Pipelines. Esta funcionalidad es útil, por ejemplo, si desea informar a los usuarios de que la comprobación está esperando una acción externa, como cuando alguien debe aprobar un vale de ServiceNow.

Los pasos para enviar actualizaciones de estado son:

  1. Creación de una lista de tareas
  2. Anexión al registro de tareas
  3. Actualización del registro de escala de tiempo

Todas las llamadas API REST deben autenticarse.

Ejemplos

Comprobación básica de Función de Azure

En este ejemplo básico, Función de Azure comprueba que la canalización de invocación ha ejecutado una tarea CmdLine antes de concederle acceso a un recurso protegido.

Función de Azure sigue estos pasos:

  1. Confirma la recepción de la carga de comprobación.
  2. Envía una actualización de estado a Azure Pipelines de que se ha iniciado la comprobación.
  3. Se utiliza {AuthToken} para realizar una devolución de llamada a Azure Pipelines a fin de recuperar la entrada Escala de tiempo de la ejecución de la canalización.
  4. Comprueba si la escala de tiempo contiene una tarea con "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (el identificador de la tarea CmdLine)
  5. Envía una actualización de estado con el resultado de la búsqueda.
  6. Envía una decisión de comprobación a Azure Pipelines

Puede descargar este ejemplo desde GitHub.

Para usar esta comprobación de Función de Azure, debe especificar los siguientes Headers al configurar la comprobación:

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

Comprobación de Función de Azure avanzada

En este ejemplo avanzado, Función de Azure comprueba que el elemento de trabajo de Azure Boards al que se hace referencia en el mensaje de confirmación que ha desencadenado la ejecución de la canalización está en el estado correcto.

Función de Azure sigue estos pasos:

  1. Confirma la recepción de la carga de comprobación.
  2. Envía una actualización de estado a Azure Pipelines de que se ha iniciado la comprobación.
  3. Usa {AuthToken} para realizar una devolución de llamada a Azure Pipelines a fin de recuperar el estado del elemento de trabajo de Azure Boards al que se hace referencia en el mensaje de confirmación que ha desencadenado la ejecución de la canalización.
  4. Comprueba si el elemento de trabajo está en el estado Completed.
  5. Envía una actualización de estado con el resultado de la comprobación.
  6. Si el elemento de trabajo no está en el estado Completed, vuelve a programar otra evaluación en 1 minuto.
  7. Una vez que el elemento de trabajo está en el estado correcto, envía una decisión positiva a Azure Pipelines.

Puede descargar este ejemplo desde GitHub.

Para usar esta comprobación de Función de Azure, debe especificar los siguientes Headers al configurar la comprobación:

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

Control de errores

Actualmente, Azure Pipelines evalúa una única instancia de comprobación 2000 veces como máximo.

Si la comprobación no vuelve a llamar a Azure Pipelines en el tiempo de espera configurado, se omite la fase asociada. También se omiten las fases que dependen de ella.

Comprobaciones sincrónicas

En el modo sincrónico, Azure DevOps realiza una llamada a la comprobación de Función de Azure / API REST para obtener una decisión inmediata de si se permite o no el acceso a un recurso protegido.

La implementación del modo sincrónico para una única comprobación de Función de Azure se muestra en el diagrama siguiente.

Diagrama que muestra la implementación del modo sincrónico para una única comprobación de Función de Azure.

Los pasos son:

  1. Azure Pipelines se prepara para implementar una fase de canalización y requiere acceso a un recurso protegido.
  2. Entra en un bucle interno en el que:
  • 2.1. Azure Pipelines invoca la comprobación de Función de Azure correspondiente y espera una decisión.
  • 2.2. Función de Azure evalúa las condiciones necesarias para permitir el acceso y devuelve una decisión.
  • 2.3. Si el cuerpo de la respuesta de Función de Azure no cumple los Criterios de éxito definidos y Tiempo entre evaluaciones es distinto de cero, Azure Pipelines vuelve a programar otra evaluación de comprobación después de Tiempo entre evaluaciones.

Configuración de comprobaciones sincrónicas

Para usar el modo sincrónico para Función de Azure / API REST, en el panel de configuración de comprobaciones, asegúrese de:

  • Seleccionar ApiResponse para el evento Completion en Avanzado.
  • Especificar Criterios de éxito que definen cuándo se debe pasar la comprobación en función del cuerpo de la respuesta de la comprobación.
  • Establecer Tiempo entre evaluaciones en 0 en Opciones de control.
  • Establecer Tiempo de espera en cuánto tiempo desea esperar a que una comprobación se realice correctamente. Si no hay ninguna decisión positiva y se alcanza el Tiempo de espera, se omite la fase de canalización correspondiente.

La opción Tiempo entre evaluaciones define cuánto tiempo es válida la decisión de la comprobación. Un valor de 0 significa que la decisión es final. Un valor distinto de cero significa que la comprobación se reintentará después del intervalo configurado, cuando la decisión sea negativa. Si se están ejecutando varias aprobaciones y comprobaciones, se reintenta la comprobación independientemente de la decisión.

El número máximo de evaluaciones se define mediante la relación entre los valores Tiempo de espera y Tiempo entre evaluaciones. Se recomienda asegurarse de que esta relación sea como máximo de 10.

Pasar información de ejecución de canalización a comprobaciones

Al configurar la comprobación, puede especificar la información de ejecución de la canalización que desea enviar a la comprobación de Función de Azure / API REST. De forma predeterminada, Azure Pipeline agrega la siguiente información en los elementos Headers de la llamada HTTP que realiza.

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

No se recomienda realizar llamadas a Azure DevOps en modo sincrónico, ya que lo más probable es que la comprobación tarde más de 3 segundos en responder, por lo que se produce un error en la comprobación.

Control de errores

Actualmente, Azure Pipelines evalúa una única instancia de comprobación 2000 veces como máximo.

Cuándo usar comprobaciones asincrónicas en lugar de sincrónicas

Veamos algunos casos de uso de ejemplo y cuál es el tipo de comprobación recomendado que se va a usar.

La información externa debe ser correcta

Supongamos que tiene una conexión de servicio a un recurso de producción y desea asegurarse de que el acceso a él solo está permitido si la información de un vale de ServiceNow es correcta. En este caso, el flujo sería el siguiente:

  • Agregue una comprobación asincrónica de Función de Azure que compruebe la exactitud del vale de ServiceNow.
  • Cuando se ejecuta una canalización que quiere usar la conexión de servicio:
    • Azure Pipelines llama a la función de comprobación.
    • Si la información es incorrecta, la comprobación devuelve una decisión negativa. Asuma este resultado.
    • Se produce un error en la fase de canalización.
    • La información se actualiza en el vale de ServiceNow.
    • Reinicie la fase con errores.
    • La comprobación se vuelve a ejecutar y esta vez se realiza correctamente.
    • La ejecución de la canalización continúa.

La aprobación externa debe estar concedida

Supongamos que tiene una conexión de servicio a un recurso de producción y desea asegurarse de que el acceso a él solo está permitido después de que un administrador haya aprobado un vale de ServiceNow. En este caso, el flujo sería el siguiente:

  • Agregue una comprobación asincrónica de Función de Azure que compruebe que se ha aprobado el vale de ServiceNow.
  • Cuando se ejecuta una canalización que quiere usar la conexión de servicio:
    • Azure Pipelines llama a la función de comprobación.
    • Si no se aprueba el vale de ServiceNow, Función de Azure envía una actualización a Azure Pipelines y se vuelve a programar para comprobar el estado del vale en 15 minutos.
    • Una vez aprobado el vale, la comprobación vuelve a llamar a Azure Pipelines con una decisión positiva.
    • La ejecución de la canalización continúa.

Se ha seguido el proceso de desarrollo

Supongamos que tiene una conexión de servicio a un recurso de producción y desea asegurarse de que el acceso a él solo está permitido si la cobertura de código es superior al 80 %. En este caso, el flujo sería el siguiente:

  • La canalización se escribe de tal manera que los errores de fase provocan un error en la compilación.
  • Agregue una comprobación asincrónica de Función de Azure que compruebe la cobertura de código para la ejecución de la canalización asociada.
  • Cuando se ejecuta una canalización que quiere usar la conexión de servicio:
    • Azure Pipelines llama a la función de comprobación.
    • Si no se cumple la condición de cobertura de código, la comprobación devuelve una decisión negativa. Asuma este resultado.
    • El error de comprobación hace que se produzca un error en la fase, lo que provoca un error en la ejecución de la canalización.
  • El equipo de ingeniería agrega las pruebas unitarias necesarias para alcanzar el 80 % de la cobertura de código
  • Se desencadena una nueva ejecución de canalización y, esta vez, se supera la comprobación.
    • La ejecución de la canalización continúa.

Se deben cumplir los criterios de rendimiento

Supongamos que implementa nuevas versiones del sistema en varios pasos, comenzando por una implementación controlada. Quiere asegurarse de que el rendimiento de la implementación controlada es adecuado. En este caso, el flujo sería el siguiente:

  • Agregue una comprobación de Función de Azure asincrónica.
  • Cuando se ejecuta una canalización que quiere usar la conexión de servicio:
    • Azure Pipelines llama a la función de comprobación.
    • La comprobación inicia un monitor del rendimiento de la implementación controlada.
    • La comprobación programa varios puntos de control de evaluación para ver cómo ha evolucionado el rendimiento.
    • Una vez que adquiera suficiente confianza en el rendimiento de la implementación controlada, Función de Azure vuelve a llamar a Azure Pipelines con una decisión positiva.
    • La ejecución de la canalización continúa.

El motivo de implementación debe ser válido

Supongamos que tiene una conexión de servicio a un recurso de entorno de producción y desea asegurarse de que el acceso a él solo se produce para compilaciones que se han puesto en cola de forma manual. En este caso, el flujo sería el siguiente:

  • Agregue una comprobación sincrónica de Función de Azure que compruebe que Build.Reason para la ejecución de la canalización sea Manual.
  • Configure la comprobación de Función de Azure para pasar Build.Reason en sus Headers.
  • Establezca Tiempo entre evaluaciones de la comprobación en 0, por lo que el error o la aprobación sean finales y no sea necesario volver a evaluar.
  • Cuando se ejecuta una canalización que quiere usar la conexión de servicio:
    • Azure Pipelines llama a la función de comprobación.
    • Si el motivo es distinto de Manual, se produce un error en la comprobación y otro en la ejecución de la canalización.

Comprobar cumplimiento

La invocación de la función de Azure y las comprobaciones de la API de REST ahora incluyen reglas para que coincidan con el uso recomendado. Las comprobaciones deben seguir estas reglas según el modo y el número de reintentos:

  • Comprobaciones asíncronas (modo de devolución de llamada): Azure Pipelines no reintenta las comprobaciones asíncronas. Debe proporcionar un resultado de forma asíncrona cuando una evaluación sea final. Para que las comprobaciones asíncronas se consideren conformes, el intervalo de tiempo entre evaluaciones debe ser 0.

  • Comprobaciones sincrónicas (modo ApiResponse): el número máximo de reintentos de la comprobación es 10. Puede establecerlo de varias maneras. Por ejemplo, puede configurar el tiempo de expiración en 20 y el intervalo de tiempo entre evaluaciones en 2. O bien, puede configurar el tiempo de expiración en 100 y el intervalo de tiempo entre evaluaciones en 10. No obstante, si configura el tiempo de expiración en 100 y establece el intervalo de tiempo entre evaluaciones en 2, la comprobación no será conforme porque solicita 50 reintentos. La relación entre el tiempo de expiración y el intervalo de tiempo entre evaluaciones debe ser menor o igual que 10.

Obtenga más información sobre el lanzamiento del cumplimiento de las comprobaciones.

Varias comprobaciones

Antes de que Azure Pipelines implemente una fase en una ejecución de canalización, es posible que tenga que superar varias comprobaciones. Un recurso protegido puede tener una o varias comprobaciones asociadas. Una fase puede usar varios recursos protegidos. Azure Pipelines recopila todas las comprobaciones asociadas a cada recurso protegido utilizado en una fase y las evalúa simultáneamente.

Una ejecución de canalización solo se puede implementar en una fase cuando se superan todas las comprobaciones al mismo tiempo. Una única decisión negativa final hace que se deniegue el acceso a la canalización y se produzca un error en la fase.

Cuando se utilizan comprobaciones en el modo recomendado (asincrónico, con estados finales), las decisiones de acceso son finales y se facilita la comprensión del estado del sistema.

Consulte la sección Varias aprobaciones y comprobaciones para ver ejemplos.

Más información