Справочник по 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}

   • instance: 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-versions имеют следующий формат: {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 для текста также должен быть указан в заголовке запроса Content-type. Для некоторых служб необходимо использовать конкретный тип 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 с использованием библиотеки клиентской модели	Расширение 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 имеет значение {server:port}/tfs/{collection} и instance по умолчанию используется порт 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 2022 г.	7,0	versions >= 19.205.33122.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.

• Концептуальная документация по .NET и справочная документация по .NET
• GO
• Node.js
• Python
• Swagger 2.0
• Пакет SDK для веб-расширений

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

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

Если вы работаете в TFS или ищете более старые версии REST API, ознакомьтесь с обзором REST API для TFS 2015, 2017 и 2018.