Справочник по REST API Azure DevOps Services

Добро пожаловать в справочник по REST API Azure DevOps Services/Azure DevOps Server.

REST API — это конечные точки службы, которые поддерживают набор операций HTTP (методов), предоставляющих доступ на создание, получение, обновление или удаление ресурсов сервера. В этой статье описаны следующие операции.

  • Основные компоненты пары запросов и ответов REST API.
  • Общие сведения о создании и отправке запроса REST и обработке ответа.

Большинство ИНТЕРФЕЙСов REST API доступны через наши клиентские библиотеки, которые можно использовать для значительной упрощения клиентского кода.

Компоненты пары запросов и ответов REST API

Пару запроса-ответа API REST можно разделить на пять компонентов:

  1. Универсальный код ресурса (URI) запроса в следующей форме:VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • экземпляр: Azure DevOps Services организации или сервера TFS, на который отправляется запрос. Они структурированы следующим образом:
      • Azure DevOps Services:dev.azure.com/{organization}
      • TFS: {server:port}/tfs/{collection} (порт по умолчанию — 8080, а значение для коллекции должно быть, но может быть DefaultCollection любой коллекцией).
    • Путь к ресурсу: путь к ресурсу выглядит следующим образом: _apis/{area}/{resource} Например, _apis/wit/workitems.
    • api-version: каждый запрос API должен включать версию API, чтобы избежать разрыва приложения или службы по мере развития API. Версии API имеют следующий формат: например: {major}.{minor}[-{stage}[.{resource-version}]]
      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

    Примечание. Область и командный проект являются необязательными в зависимости от запроса API. Ознакомьтесь с матрицей сопоставления версий TFS с REST API ниже, чтобы узнать, какие версии REST API применяются к вашей версии TFS.

  2. Поля заголовка сообщения HTTP-запроса :

    • Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции запрашивается. REST API Azure поддерживают методы GET, HEAD, PUT, POST и PATCH.
    • Необязательные дополнительные поля заголовка, требуемые для указанного URI и метода HTTP. Например, заголовок авторизации, предоставляющий маркер носителя, содержащий сведения о авторизации клиента для запроса.
  3. Необязательные поля текста сообщения запроса HTTP для поддержки URI и операции HTTP. Например, операции POST содержат объекты в кодировке MIME, которые передаются как сложные параметры.

    • Для операций POST или PUT тип кодирования MIME для основного текста также должен быть указан в заголовке запроса типа контента. Для некоторых служб необходимо использовать конкретный тип MIME, например application/json.
  4. Поля заголовка сообщения ответа HTTP:

    • Код состояния HTTP— от кодов успешного выполнения 2xx до кодов ошибок 4xx или 5xx. Кроме того, может быть возвращен определяемый службой код состояния, как указано в документации по API.
    • Необязательные дополнительные поля заголовка, как требуется для поддержки ответа запроса, такие как заголовок ответа Content-type.
  5. Необязательные поля текста сообщения ответа HTTP:

    • Объекты ответа в кодировке MIME могут быть возвращены в тексте ответа HTTP, например ответ от метода GET, возвращающего данные. Как правило, эти объекты возвращаются в структурированном виде, например JSON или XML, как указано в заголовке ответа Content-type. Например, при запросе маркера доступа из Azure AD он будет возвращен в тексте ответа в качестве access_token элемента, одного из нескольких парных объектов имени и значения в коллекции данных. В этом примере также включен заголовок Content-Type: application/json ответа.

Создание запроса

Authenticate

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

Тип приложения Описание пример Механизм аутентификации Примеры кода
Интерактивная клиентская часть Клиентское приложение, позволяющее взаимодействовать с пользователем, вызывать Azure DevOps Services REST API Консольное приложение, перечисляющее проекты в организации Библиотека проверки подлинности Майкрософт (MSAL) Образец
Интерактивный JavaScript Приложение JavaScript на основе графического пользовательского интерфейса Одностраничное приложение AngularJS, отображающее сведения о проекте для пользователя MSAL Образец
Неинтерактивная клиентская сторона Только клиентское клиентское приложение без текста Консольное приложение, отображающее все ошибки, назначенные пользователю Профиль устройства Образец
Интерактивный веб-сайт Веб-приложение на основе графического пользовательского интерфейса Настраиваемая веб-панель мониторинга, отображающая сводки по сборке OAuth Образец
Приложение TFS Приложение TFS с помощью клиентской библиотеки OM Расширение TFS, отображающее панели мониторинга ошибок команды Клиентские библиотеки Образец
Расширение Azure DevOps Services расширение Azure DevOps Services Примеры расширений Azure DevOps Пакет SDK веб-расширения VSS Пример пошагового руководства

Примечание: Дополнительные сведения о проверке подлинности можно найти на странице рекомендаций по проверке подлинности.

Сборка запроса

Azure DevOps Services

Для Azure DevOps Services экземпляр имеет следующий dev.azure.com/{organization}вид:

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

Например, вот как получить список командных проектов в Azure DevOps Services организации.

curl -u {username}[:{personalaccesstoken}] https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

Если вы хотите предоставить личный маркер доступа через заголовок HTTP, необходимо сначала преобразовать его в строку Base64 (в следующем примере показано, как преобразовать в Base64 с помощью C#). (Некоторые средства, такие как Postman, применяют кодировку Base64 по умолчанию. Если вы пытаетесь использовать API с помощью таких средств, кодировка Base64 PAT не требуется) Результирующая строка может быть предоставлена в виде заголовка HTTP в формате:

Authorization: Basic BASE64PATSTRING

В C# используется [класс HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

public static async void GetProjects()
{
	try
	{
		var personalaccesstoken = "PAT_FROM_WEBSITE";

		using (HttpClient client = new HttpClient())
		{
			client.DefaultRequestHeaders.Accept.Add(
				new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

			client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
				Convert.ToBase64String(
					System.Text.ASCIIEncoding.ASCII.GetBytes(
						string.Format("{0}:{1}", "", personalaccesstoken))));

			using (HttpResponseMessage response = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

Большинство примеров на этом сайте используют личные маркеры доступа, так как они являются компактным примером проверки подлинности со службой. Однако существуют различные механизмы проверки подлинности, доступные для Azure DevOps Services включая маркеры MSAL, OAuth и сеанса. Ознакомьтесь с разделом "Проверка подлинности" , чтобы ознакомиться с рекомендациями, которые лучше всего подходят для вашего сценария.

TFS

Для TFS instance используется {server:port}/tfs/{collection} порт 8080 и по умолчанию. Коллекция по умолчанию — DefaultCollectionэто коллекция, но может быть любой коллекцией.

Вот как получить список командных проектов из TFS с помощью порта и коллекции по умолчанию.

curl -u {username}[:{personalaccesstoken}] https://{server}:8080/tfs/DefaultCollection/_apis/projects?api-version=2.0

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

Обработка ответа

Вы должны получить ответ, как показано ниже.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

Ответ — JSON. Как правило, это то, что вы вернетесь из REST API, хотя есть несколько исключений, таких как BLOB-объекты Git.

Теперь вы сможете просмотреть определенные области API, такие как отслеживание рабочих элементов или Git , и получить доступ к нужным ресурсам. Продолжайте читать, чтобы узнать больше об общих шаблонах, используемых в этих API.

Сопоставление версий API и TFS

Ниже приведено быстрое сопоставление версий REST API и их соответствующих выпусков TFS. Все версии API будут работать с указанной версией сервера, а также с более поздними версиями.

Версия TFS Версия REST API Версия сборки
Azure DevOps Server vNext 7.1
Azure DevOps Server 2020 6,0 versions >= 18.170.30525.1
Azure DevOps Server 2019 5,0 versions >= 17.143.28621.4
TFS 2018 с обновлением 3 4.1 versions >= 16.131.28106.2
TFS 2018 с обновлением 2 4.1 versions >= 16.131.27701.1
TFS 2018 с обновлением 1 4,0 versions >= 16.122.27409.2
TFS 2018 RTW 4,0 versions >= 16.122.27102.1
TFS 2017 с обновлением 2 3.2 versions >= 15.117.26714.0
TFS 2017 с обновлением 1 3.1 versions >= 15.112.26301.0
TFS 2017 RTW 3,0 versions >= 15.105.25910.0
TFS 2015 с обновлением 4 2.3 versions >= 14.114.26403.0
TFS 2015 с обновлением 3 2.3 versions >= 14.102.25423.0
TFS 2015 с обновлением 2 2.2 versions >= 14.95.25122.0
TFS 2015 с обновлением 1 2.1 versions >= 14.0.24712.0
TFS 2015 RTW 2,0 versions >= 14.0.23128.0

Ознакомьтесь с документацией по интеграции примеров и вариантов использования REST API.

Клиентские библиотеки

Ознакомьтесь с клиентскими библиотеками для этих ИНТЕРФЕЙСов REST API.

Где находятся более ранние версии REST API? (До 4.1)

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

Если вы работаете в TFS или ищете более старые версии REST API, ознакомьтесь с документацией по REST API до версии 4.1.