Публикация API с помощью DevOps и CI/CD

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Благодаря стратегическому значению API на предприятии внедрение методов DevOps для непрерывной интеграции (CI) и развертывания (CD) стало важным аспектом разработки API. В этой статье рассматриваются решения, которые необходимо принять для интеграции принципов DevOps с системами управления API.

API DevOps состоят из трех частей:

Схема: поток API DevOps.

Каждая часть конвейера API DevOps рассматривается ниже.

Определение API

Разработчик API записывает определение API, предоставляя спецификацию, параметры (такие как ведение журнала, диагностика и параметры серверной части) и политики, применяемые к API. Определение API предоставляет сведения, необходимые для подготовки API в службе "Управление API" Azure. Спецификация может быть основана на стандартной спецификации API (например, WSDL, OpenAPI или GraphQL) или может быть определена с помощью API Azure Resource Manager (ARM), например шаблона ARM, описывающего API и операции. Определение API будет меняться со временем и должно рассматриваться как "исходный код". Убедитесь, что определение API хранится в системе управления исходным кодом и проходит соответствующую проверку перед внедрением.

Существует несколько инструментов, которые облегчают создание определения API.

  • Azure APIOps Toolkit обеспечивает рабочий процесс, созданный на основе системы управления исходным кодом Git (например, GitHub или Azure Repos). Он использует средство извлечения для создания определения API, которое затем применяется к целевой службе Управление API издателем. APIOps поддерживает API REST и GraphQL в настоящее время.
  • Инструмент dotnet-apim преобразует правильно сформированное определение YAML в шаблон ARM для последующего развертывания. Это средство предназначено для REST API.
  • Terraform — это альтернатива Azure Resource Manager для настройки ресурсов в Azure. Можно создать конфигурацию Terraform (вместе с политиками), которая позволяет реализовать API так же, как создается шаблон ARM.

Вы также можете использовать средства для редакторов на основе интегрированной среды разработки (IDE), такие как Visual Studio Code, чтобы создать артефакты, необходимые для определения API. Например, в Marketplace для Visual Studio Code существует более 30 подключаемых модулей для редактирования файлов спецификаций OpenAPI. Генераторы кода также можно использовать для создания артефактов. Язык CADL позволяет легко создавать высокоуровневые стандартные блоки, а затем компилировать их в стандартный формат определения API, например OpenAPI.

Утверждение API

Создав определение API, разработчик отправляет его для проверки и утверждения. Если используется система управления исходным кодом на основе Git (например, GitHub или Azure Repos), отправка может выполняться с помощью запроса на вытягивание. Запрос на вытягивание сообщает другим пользователям об изменениях, предлагаемых для определения API. Когда шлюзы утверждения будут подтверждены, утверждающий включит запрос на вытягивание в основной репозиторий, чтобы указать, что определение API можно развернуть в рабочей среде. Процесс запроса на вытягивание позволяет разработчику устранить все проблемы, обнаруженные в процессе утверждения.

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

  • Анализаторы кода спецификации API, такие как Spectral, чтобы обеспечить соответствие определения стандартам API, установленным организацией.
  • Обнаружение критических изменений с помощью таких средств, как openapi-diff.
  • Средства аудита и оценки безопасности. OWASP поддерживает список средств для проверки безопасности.
  • Автоматизированные платформы тестирования API, такие как Newman, средство тестирования для коллекций Postman.

Примечание.

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

Когда автоматизированные средства отработают, определение API проверяет человек. Инструменты не смогут обнаружить все проблемы. Рецензент-человек гарантирует, что определение API соответствует критериям организации для API, включая соблюдение рекомендаций по обеспечению безопасности, конфиденциальности и согласованности.

Публикация API

Определение API будет опубликовано в службе" Управление API" через конвейер выпуска. Средства, используемые для публикации определения API, зависят от того, какими средствами было создано определение API.

  • При использовании набор средств Azure APIOps набор средств включает издателя, который записывает определение API в целевую службу.
  • При использовании dotnet-apim определение API представлено как шаблон ARM. Задачи по развертыванию шаблона ARM доступны для Azure Pipelines и GitHub Actions.
  • При использовании Terraform за развертывание определения API в службе будут отвечать средства CLI. Доступны задачи для Azure Pipelines и GitHub Actions.

Можно ли использовать другие системы управления исходным кодом и CI/CD?

Да. Описанный процесс работает с любой системой управления исходным кодом (хотя для APIOps требуется, чтобы система управления исходным кодом была основана на Git). Аналогичным образом можно использовать любую платформу CI/CD, если она может быть активирована при проверке и запуске программ командной строки, взаимодействующих с Azure.

Рекомендации

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

  • Azure Repos хранит определения API в репозитории Git.
  • Azure Pipelines запускает автоматизированные процессы утверждения и публикации API.
  • Azure APIOps Toolkit предоставляет средства и рабочие процессы для публикации API.

Мы наблюдали за клиентами, которые наиболее успешно осуществили развертывание, и рекомендуем следующие методики:

  • Настройте GitHub или Azure Repos в качестве системы управления исходным кодом. Этот выбор также определит выбор средства выполнения конвейера. GitHub может использовать Azure Pipelines или GitHub Actions, тогда как служба Azure Repos должна использовать Azure Pipelines.
  • Настройте службу "Управление API" Azure для каждого разработчика API, чтобы он мог проектировать определения API вместе со службой API. Используйте номер SKU потребления или разработчика при создании службы.
  • Используйте фрагменты политики, чтобы сократить новую политику, которую разработчики должны писать для каждого API.
  • Используйте именованные значения и серверные серверы, чтобы гарантировать, что политики являются универсальными и могут применяться к любому Управление API экземпляру.
  • Используйте Azure APIOps Toolkit, чтобы извлечь рабочее определение API из службы разработчика.
  • Настройте процесс утверждения API, который выполняется при каждом запросе на вытягивание. Процесс утверждения API должен включать обнаружение критических изменений, анализ кода и автоматическое тестирование API.
  • Используйте издатель Azure APIOps Toolkit для публикации API в рабочей службе "Управление API".

Подробные сведения о настройке и запуске конвейера развертывания CI/CD с помощью APIOps см. в разделе Автоматизированное развертывание API с помощью APIOps в Центре архитектуры Azure.

Ссылки

  • Azure DevOps Services включает Azure Repos и Azure Pipelines.
  • Azure APIOps Toolkit предоставляет рабочий процесс для DevOps Управления API.
  • Spectral обеспечивает анализатор кода для спецификаций OpenAPI.
  • openapi-diff предоставляет детектор критических изменений для определений OpenAPI версии 3.
  • Newman обеспечивает автоматическое средство тестирования для коллекций Postman.