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

Статья
01/10/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: Basic: {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 проверка показана на следующей схеме.

Diagram that shows the implementation of the sync mode for a single Azure Function check.

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы добавляете синхронную функцию Azure проверка, которая проверяет, является ли Build.Reason выполнение конвейераManual
Вы настраиваете функцию Azure, проверка передать Build.Reason ееHeaders
Вы устанавливаете время проверка между оценками0, поэтому сбой или передача является окончательным, и повторное вычисление не требуется
Если конвейер, который хочет использовать службу Подключение ion, выполняется:
- 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 проверка

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

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

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

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

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

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

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

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

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

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

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

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

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

Подробнее

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

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

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