Начало работы с REST API

Сервисы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

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

В этой статье рассматриваются основные понятия и шаблоны для Azure DevOps REST API. Примеры практической реализации см. в примерах REST API.

Структура URL-адресов

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

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Аутентификация

Azure DevOps REST API поддерживают несколько методов проверки подлинности:

• Microsoft Entra ID — рекомендуется для рабочих приложений
• Личные маркеры доступа (PATs) — простая проверка подлинности для сценариев и тестирования
• OAuth 2.0 — для приложений, отличных от Майкрософт
• Принципы обслуживания — для автоматизированных сценариев

Формат ответа

Azure DevOps REST API обычно возвращают ответы JSON. Ниже приведен пример структуры ответов:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Team Foundation Version Control projects"
        }
    ],
    "count": 1
}

Ответ JSON, который обычно возвращается из ИНТЕРФЕЙСов REST API, хотя существует несколько исключений, например BLOB-объектов Git.

Методы и операции HTTP

Azure DevOps REST API используют стандартные методы HTTP:

Заголовки запросов и содержимое

Если вы предоставляете текст запроса (обычно с POST, PUT и PATCH), включите соответствующие заголовки:

Content-Type: application/json

Для операций PATCH с рабочими элементами используйте:

Content-Type: application/json-patch+json

Переопределение метода HTTP

Некоторые веб-прокси могут поддерживать только HTTP-команды GET и POST, но не более современные HTTP-команды, такие как PATCH и DELETE. Если вызовы могут проходить через один из этих прокси-серверов, можно отправить фактическую команду с помощью метода POST с заголовком для переопределения метода. Например, может потребоваться обновить рабочий элемент (PATCH _apis/wit/workitems/3), но может потребоваться пройти через прокси-сервер, который разрешает только GET или POST. Вы можете передать соответствующую команду (PATCH в этом случае) в качестве параметра заголовка HTTP-запроса и использовать POST в качестве фактического метода HTTP.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Коды ответа

Общие сведения о кодах ответов HTTP помогают правильно обрабатывать ответы API:

Управление версиями API

Azure DevOps REST API версионируются, чтобы приложения продолжали работать по мере развития API.

Руководящие принципы

• Всегда указывайте версию API с каждым запросом (обязательным)
• Форматирование версий API следующим образом: {major}.{minor} или {major}.{minor}-{stage} (например, 7.2) 7.2-preview
• Используйте определенные предварительные версии при наличии: 7.2-preview.17.2-preview.2
• Обновление до выпущенных версий, когда предварительные API устаревают

Использование

Укажите версию API в качестве параметра запроса URL-адреса:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Или в заголовке запроса:

Accept: application/json;api-version=7.2

Сведения о поддерживаемых версиях см. в разделе "Управление версиями REST API".

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

Инструкции по практической реализации и полные примеры кода см. в следующих примерах:

• примеры API REST — полные примеры проверки подлинности Microsoft Entra ID
• Руководство по проверке подлинности . Подробные параметры проверки подлинности
• Управление версиями REST API — сведения о жизненном цикле API
• OAuth 2.0 — сведения о реализации OAuth

Использование ИИ для создания вызовов REST API

Если у вас есть Azure DevOps MCP Server подключен к агенту ИИ в режиме агента, можно использовать запросы естественного языка для создания и устранения неполадок вызовов REST API.

Дальнейшие шаги