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

  • Статья

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.

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

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 с каждым запросом (обязательным).
  • Форматирование версий API следующим образом: {major}. {minor}-{stage}. {resource-version}. Например, 1.0, 1.1, 1.2-preview. 2.0
  • Укажите определенную редакцию API при предварительной версии, используя следующий формат версии: 1.0-preview.1, 1.0-preview.2. После выпуска API (например, 1.0) его предварительная версия (например, 1.0-preview) становится нерекомендуемой и может быть отключена через 12 недель.
  • Обновите выпущенную версию API. После деактивации API предварительной версии запросы, указывающие -preview отклонение версии.

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

Укажите версию 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" и "Поддерживаемые версии".