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

Для 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 будут работать в указанной версии сервера, а также в более поздних версиях.

См. также

Ознакомьтесь с документацией по интеграции для примеров и вариантов использования 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.