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

Статья
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Интеграция приложения с Azure DevOps с помощью REST API, предоставляемых в этой статье.

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

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

Совет

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

Azure DevOps Services

Для Azure DevOps Services instance используется и collection находится DefaultCollectiondev.azure.com/{organization} шаблон, поэтому шаблон выглядит так, как показано в следующем примере.

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

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

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

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

Authorization: Basic BASE64PATSTRING

В следующем примере показан C# с помощью класса HttpClient.

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 = client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects").Result)
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

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

Azure DevOps Server

Для Azure DevOps Server используется instance {server:port}. Порт по умолчанию для подключения, отличного от SSL, — 8080.

Коллекция по умолчанию — DefaultCollectionэто, но вы можете использовать любую коллекцию.

Вот как получить список проектов из Azure DevOps Server, используя порт и коллекцию по протоколу SSL по умолчанию:

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

Чтобы получить один и тот же список через подключение, отличное от SSL, выполните следующие действия.

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

В этих примерах используются PATs, которые требуют создания PAT.

Отклики

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

{
    "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"
            },
            "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"
            },
            "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, хотя существует несколько исключений, таких как большие двоичные объекты Git.

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

HTTP-команды

Команда	Используется для...
GET	Получение ресурса или списка ресурсов
POST	Создание ресурса, получение списка ресурсов с помощью более расширенного запроса
PUT	Создайте ресурс, если он не существует или, если он есть, обновите его.
PATCH	Обновление ресурса
DELETE	Удаление ресурса

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

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

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

Переопределение метода 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)
}

Коды откликов

Response	Примечания
200	Успех, и есть текст ответа.
201	Успешное создание ресурсов. Некоторые API возвращают 200 при успешном создании ресурса. Ознакомьтесь с документацией по API, которую вы используете, чтобы убедиться.
204	Успех, и нет текста ответа. Например, при удалении ресурса вы получите этот ответ.
400	Параметры в URL-адресе или тексте запроса недопустимы.
401	Не удалось пройти проверку подлинности. Часто этот ответ возникает из-за отсутствия или неправильно сформированного заголовка авторизации.
403	У пользователя, прошедшего проверку подлинности, нет разрешения на выполнение операции.
404	Ресурс не существует, или у пользователя, прошедшего проверку подлинности, нет разрешения на то, что он существует.
409	Существует конфликт между запросом и состоянием данных на сервере. Например, если вы пытаетесь отправить запрос на вытягивание и уже есть запрос на вытягивание для фиксаций, код ответа равен 409.

Azure DevOps Services поддерживает CORS, который позволяет коду JavaScript обслуживаться из домена, отличного dev.azure.com/* от выполнения запросов Ajax к REST API Azure DevOps Services. Каждый запрос должен предоставить учетные данные (маркеры доступа PATs и OAuth являются поддерживаемыми вариантами). Пример:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(замените myPatToken личным маркером доступа)

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

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

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

Укажите версию API в заголовке HTTP-запроса или в качестве параметра ЗАПРОСА URL-адреса.

Заголовок HTTP-запроса:

Accept: application/json;api-version=1.0

Параметр запроса:

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

Поддерживаемые версии

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

Поделиться через

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

Azure DevOps Services

Azure DevOps Server

Отклики

HTTP-команды

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

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

Коды откликов

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

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

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

Поддерживаемые версии

Обратная связь

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

Поделиться через

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

Azure DevOps Services

Azure DevOps Server

Отклики

HTTP-команды

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

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

Коды откликов

Общий доступ к ресурсам независимо от источника (CORS)

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

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

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

Поддерживаемые версии

Обратная связь

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