Вызов проверки функции Azure или REST API

Статья
11/09/2024

Проверка функции Azure или REST API позволяет писать код, чтобы определить, разрешен ли определенный этап конвейера получить доступ к защищенному ресурсу или нет. Эти проверки могут выполняться в двух режимах:

Асинхронный (рекомендуемый): режим принудительной отправки, в котором Azure DevOps ожидает реализации Функции Azure или REST API для обратного вызова в Azure DevOps с решением о доступе к этапу
Синхронный режим опроса: режим опроса, в котором Azure DevOps периодически вызывает функцию Azure или REST API для получения решения о доступе к этапу

В остальной части этого руководства мы ссылаемся на функции Azure или проверки REST API, просто как проверки.

Рекомендуемый способ использования проверок находится в асинхронном режиме. Этот режим обеспечивает высокий уровень контроля над логикой проверки, позволяет легко подумать о состоянии системы и отделить Azure Pipelines от реализации проверок, обеспечивая оптимальную масштабируемость. Все синхронные проверки можно реализовать с помощью асинхронного режима проверок.

Асинхронные проверки

В асинхронном режиме Azure DevOps выполняет вызов функции Azure или REST API и ожидает обратного вызова с решением о доступе к ресурсам. Нет открытого HTTP-подключения между Azure DevOps и реализацией проверки в течение периода ожидания.

Остальная часть этого раздела рассказывает о проверках функций Azure, но если не указано иное, руководство также применяется к проверкам REST API вызова.

Передача сведений о выполнении конвейера для проверок

При настройке проверки можно указать сведения о выполнении конвейера, которые вы хотите отправить на проверку. Как минимум, следует отправить следующее:

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

Эти пары "ключ-значение" задаются по умолчанию в Headers вызове REST, сделанном Azure Pipelines.

Вы должны использовать AuthToken для выполнения вызовов в Azure DevOps, например при проверке обратного вызова с решением.

Вызов в Azure DevOps

Чтобы принять решение, может потребоваться информация о текущем запуске конвейера, который не может быть передан в проверку, поэтому проверка должна получить его. Представьте, что проверка проверяет выполнение конвейера определенной задачи, например статической задачи анализа. Проверка должна вызвать Azure DevOps и получить список уже выполненных задач.

Чтобы вызвать Azure DevOps, рекомендуется использовать маркер доступа задания, выданный для выполнения проверки, а не личный маркер доступа (PAT). Маркер уже предоставляется для проверок по умолчанию в заголовке AuthToken .

По сравнению с PATs маркер доступа задания менее подвержен регулированию, не требует ручного обновления и не привязан к личная учетная запись. Маркер действителен в течение 48 часов.

Использование маркера доступа к заданию все, но удаляет проблемы регулирования REST API Azure DevOps. При использовании PAT вы используете один и тот же PAT для всех запусков конвейера. При выполнении большого количества конвейеров ПАТ получает регулирование. Это меньше проблемы с маркером доступа к заданию, так как новый маркер создается для каждого выполнения проверки.

Маркер выдан для удостоверения сборки, используемого для запуска конвейера, например службы сборки FabrikamFiberChat (FabrikamFiber). Другими словами, маркер можно использовать для доступа к тем же репозиториям или конвейерам, которые может выполнять конвейер узла. Если вы включили защиту доступа к репозиториям в конвейерах YAML, его область также ограничена только репозиториями, на которые ссылается в ходе выполнения конвейера.

Если проверка должна получить доступ к связанным ресурсам, не связанным с конвейерами, например к пользовательским историям Boards, необходимо предоставить такие разрешения удостоверениям сборки конвейеров. Если проверка может быть активирована из нескольких проектов, убедитесь, что все конвейеры во всех проектах могут получить доступ к необходимым ресурсам.

Отправка решения обратно в Azure DevOps

Реализация проверки должна использовать вызов REST API post event для передачи решения обратно в Azure Pipelines. Убедитесь, что указаны следующие свойства:

Headers: Bearer {AuthToken}
Body:

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

Отправка обновлений состояния в Azure DevOps из проверок

Вы можете предоставлять обновления состояния пользователям Azure Pipelines из проверки с помощью REST API Azure Pipelines. Эта функция полезна, например, если вы хотите сообщить пользователям, что проверка ожидает внешнего действия, например, кто-то должен утвердить билет ServiceNow.

Ниже приведены действия по отправке обновлений состояния.

Все вызовы REST API должны проходить проверку подлинности.

Примеры

Базовая проверка функции Azure

В этом базовом примере функция Azure проверяет, выполняется CmdLine ли вызывающий конвейер задачу перед предоставлением ему доступа к защищенному ресурсу.

Функция Azure выполняет следующие действия.

Подтверждает получение полезных данных проверки
Отправляет обновление состояния в Azure Pipelines, запущенное при проверке
Используется {AuthToken} для обратного вызова в Azure Pipelines для получения записи временной шкалы выполнения конвейера
Проверяет, содержит ли временная шкала задачу с "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (идентификатором CmdLine задачи)
Отправляет обновление состояния с результатом поиска
Отправляет решение проверки в Azure Pipelines

Этот пример можно скачать из GitHub.

Чтобы использовать эту проверку функции Azure, необходимо указать следующее Headers при настройке проверки:

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

Расширенная проверка функций Azure

В этом расширенном примере функция Azure проверяет, что рабочий элемент Azure Boards, на который ссылается сообщение фиксации, которое активировало выполнение конвейера, находится в правильном состоянии.

Функция Azure выполняет следующие действия.

Подтверждает получение полезных данных проверки
Отправляет обновление состояния в Azure Pipelines, запущенное при проверке
Используется {AuthToken} для обратного вызова в Azure Pipelines для получения состояния рабочего элемента Azure Boards, на который ссылается сообщение о фиксации, которое вызвало запуск конвейера.
Проверяет, находится ли рабочий Completed элемент в состоянии
Отправляет обновление состояния с результатом проверки
Если рабочий элемент не в Completed состоянии, он перепланирует другую оценку за 1 минуту.
Когда рабочий элемент находится в правильном состоянии, он отправляет положительное решение в Azure Pipelines

Этот пример можно скачать из GitHub.

Чтобы использовать эту проверку функции Azure, необходимо указать следующее Headers при настройке проверки:

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

Обработка ошибок

В настоящее время Azure Pipelines оценивает один экземпляр проверки не более 2000 раз.

Если проверка не вызывается в Azure Pipelines в течение настроенного времени ожидания, связанный этап пропускается. Этапы в зависимости от нее пропускаются.

Синхронные проверки

В синхронном режиме Azure DevOps вызывает функцию Azure или REST API, чтобы получить немедленное решение о том, разрешен ли доступ к защищенному ресурсу или нет.

Реализация режима синхронизации для одной проверки функции Azure показана на следующей схеме.

Схема, демонстрирующая реализацию режима синхронизации для одной проверки функции Azure.

Вот что нужно сделать:

Azure Pipelines готовится к развертыванию этапа конвейера и требует доступа к защищенному ресурсу
Он вводит внутренний цикл, в котором:

2.1. Azure Pipelines вызывает соответствующую проверку функции Azure и ожидает принятия решения.
2.2. Функция Azure оценивает условия, необходимые для разрешения доступа и возврата решения
2.3. Если текст ответа функции Azure не соответствует заданным критериям успешности и времени между оценками не равен нулю, Azure Pipelines перепланирует еще одну проверку после времени между оценками.

Настройка синхронных проверок

Чтобы использовать синхронный режим для функции Azure или REST API, на панели проверки конфигурации убедитесь, что вы:

Выбранный ApiResponse для события завершения в разделе "Дополнительно"
Указан критерий успешности, определяющий время передачи проверки на основе текста ответа проверки.
Установка времени между оценками 0 в разделе "Управление"
Задайте время ожидания , чтобы ждать успешной проверки. Если положительное решение и время ожидания не достигнуто, соответствующий этап конвейера пропускается

Время между параметрами оценки определяет, сколько времени принимается решение проверки. Значение 0 означает, что решение является окончательным. Значение, отличное от нуля, означает, что проверка будет извлечена после настроенного интервала, когда его решение отрицательно. При выполнении нескольких утверждений и проверок проверка выполняется, проверка выполняется независимо от решения.

Максимальное количество вычислений определяется соотношением времени ожидания и времени между значениями оценки. Мы рекомендуем убедиться, что это соотношение составляет не более 10.

Передача сведений о выполнении конвейера для проверок

При настройке проверки можно указать сведения о выполнении конвейера, которые вы хотите отправить в функцию Azure или проверку REST API. По умолчанию Azure Pipeline добавляет в вызов HTTP следующие сведения Headers .

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

Мы не рекомендуем выполнять вызовы в Azure DevOps в синхронном режиме, так как это, скорее всего, приведет к тому, что проверка займет более 3 секунд, чтобы ответить, поэтому проверка завершается ошибкой.

Обработка ошибок

В настоящее время Azure Pipelines оценивает один экземпляр проверки не более 2000 раз.

Использование асинхронных и синхронных проверок

Рассмотрим некоторые примеры вариантов использования и рекомендуемый тип проверок.

Внешние данные должны быть правильными

Предположим, что у вас есть подключение к рабочему ресурсу, и вы хотите убедиться, что доступ к нему разрешен только в том случае, если информация в билете ServiceNow правильна. В этом случае поток будет следующим образом:

Вы добавите асинхронную проверку функции Azure, которая проверяет правильность запроса ServiceNow
Когда конвейер, который хочет использовать подключение к службе, выполняется:
- Azure Pipelines вызывает функцию проверки
- Если информация неправильная, проверка возвращает отрицательное решение. Предположим, что этот результат
- Сбой этапа конвейера
- Вы обновляете сведения в билете ServiceNow
- Перезапуск этапа сбоя
- Проверка выполняется снова, и на этот раз она завершается успешно
- Выполнение конвейера продолжается

Должно быть предоставлено внешнее утверждение

Предположим, что у вас есть подключение к рабочему ресурсу, и вы хотите убедиться, что доступ к нему разрешен только после того, как администратор одобрил билет ServiceNow. В этом случае поток будет следующим образом:

Вы добавите асинхронную проверку функции Azure, проверяющую утверждение билета ServiceNow
Когда конвейер, который хочет использовать подключение к службе, выполняется:
- Azure Pipelines вызывает функцию проверки.
- Если билет ServiceNow не утвержден, функция Azure отправляет обновление в Azure Pipelines и перепланирует себя, чтобы проверить состояние билета в течение 15 минут.
- После утверждения билета проверка обратно в Azure Pipelines с положительным решением
- Выполнение конвейера продолжается

Был выполнен процесс разработки

Предположим, что у вас есть подключение к рабочему ресурсу, и вы хотите убедиться, что доступ к нему разрешен только в том случае, если покрытие кода превышает 80 %. В этом случае поток будет следующим образом:

Вы записываете конвейер таким образом, чтобы сбои этапа привели к сбою сборки
Вы добавите асинхронную проверку функции Azure, которая проверяет покрытие кода для связанного запуска конвейера.
Когда конвейер, который хочет использовать подключение к службе, выполняется:
- Azure Pipelines вызывает функцию проверки
- Если условие покрытия кода не выполнено, проверка возвращает отрицательное решение. Предположим, что этот результат
- Сбой проверки приводит к сбою этапа, что приводит к сбою запуска конвейера.
Команда инженеров добавляет необходимые модульные тесты для достижения 80% покрытия кода
Запуск нового конвейера активируется, и на этот раз проверка проходит
- Выполнение конвейера продолжается

Критерии производительности должны соответствовать

Предположим, что вы развертываете новые версии системы на нескольких шагах, начиная с канарского развертывания. Вы хотите убедиться, что производительность канаречного развертывания является достаточной. В этом случае поток будет следующим образом:

Добавлена асинхронная проверка функции Azure
Когда конвейер, который хочет использовать подключение к службе, выполняется:
- Azure Pipelines вызывает функцию проверки
- Проверка запускает монитор производительности канарского развертывания.
- Проверка планирует несколько контрольных точек оценки, чтобы узнать, как производительность изменилась
- После получения достаточной уверенности в производительности канарского развертывания функция Azure возвращается в Azure Pipelines с положительным решением.
- Выполнение конвейера продолжается

Причина развертывания должна быть допустимой

Предположим, что у вас есть подключение к ресурсу рабочей среды, и вы хотите убедиться, что доступ к нему происходит только для сборок в очереди вручную. В этом случае поток будет следующим образом:

Вы добавляете синхронную проверку функции Azure, которая проверяет, является ли Build.Reason выполнение конвейера Manual
Вы настраиваете проверку функции Azure для передачи Build.Reason в нее Headers
Вы устанавливаете время проверки между оценками 0, поэтому сбой или передача является окончательным, и повторное вычисление не требуется
Когда конвейер, который хочет использовать подключение к службе, выполняется:
- Azure Pipelines вызывает функцию проверки
- Если причина отличается, Manualпроверка завершается ошибкой, и выполнение конвейера завершается сбоем.

Проверка соответствия

Вызов проверки функции Azure и REST API теперь включают правила для сопоставления рекомендуемого использования. Проверки должны соответствовать этим правилам в зависимости от режима и количества повторных попыток:

Асинхронные проверки (режим обратного вызова): Azure Pipelines не повторяет асинхронные проверки. Результат следует предоставить асинхронно при окончательной оценке. Чтобы асинхронные проверки считались соответствующими, интервал времени между оценками должен быть 0.
Синхронные проверки (режим ApiResponse): максимальное количество повторных попыток для проверки — 10. Можно задать несколько способов. Например, можно настроить время ожидания до 20 и интервал времени между оценками до 2. Кроме того, можно настроить время ожидания до 100 и интервал времени между оценками до 10. Но если настроить время ожидания до 100 и задать интервал времени между оценками 2, проверка не будет соответствовать требованиям, так как запрос на 50 повторных попыток. Соотношение времени ожидания к интервалу времени между оценками должно быть меньше или равно 10.

Дополнительные сведения о выпуске проверки соответствия.

Несколько проверок

Прежде чем Azure Pipelines развертывает этап в выполнении конвейера, может потребоваться пройти несколько проверок. Защищенный ресурс может быть связан с одним или несколькими проверками. Этап может использовать несколько защищенных ресурсов. Azure Pipelines собирает все проверки, связанные с каждым защищенным ресурсом, используемым на этапе, и оценивает их одновременно.

Запуск конвейера разрешено развертывать на стадии, только если все проверки проходят одновременно. Одно окончательное отрицательное решение приводит к отказу конвейера в доступе, а этап завершится ошибкой.

При использовании проверок рекомендуется (асинхронный, с конечными состояниями) принимает окончательные решения о доступе и упрощает понимание состояния системы.

Примеры см. в разделе " Несколько утверждений и проверок ".

Поделиться через

Вызов проверки функции Azure или REST API

Асинхронные проверки

Рекомендуемая реализация асинхронных проверок

Рекомендуемая конфигурация для асинхронных проверок

Передача сведений о выполнении конвейера для проверок

Вызов в Azure DevOps

Отправка решения обратно в Azure DevOps

Отправка обновлений состояния в Azure DevOps из проверок

Примеры

Базовая проверка функции Azure

Расширенная проверка функций Azure

Обработка ошибок

Синхронные проверки

Настройка синхронных проверок

Передача сведений о выполнении конвейера для проверок

Обработка ошибок

Использование асинхронных и синхронных проверок

Внешние данные должны быть правильными

Должно быть предоставлено внешнее утверждение

Был выполнен процесс разработки

Критерии производительности должны соответствовать

Причина развертывания должна быть допустимой

Проверка соответствия

Несколько проверок

Подробнее

Обратная связь

Дополнительные ресурсы