Referência da API REST do Azure DevOps Services

  • Artigo

Bem-vindo à Referência da API REST Azure DevOps Services/Azure DevOps Server.

As APIs REST (Transferência de Estado Representacional) são pontos de extremidade de serviço que dão suporte a conjuntos de operações HTTP (métodos), que fornecem acesso de criação, recuperação, atualização ou exclusão para recursos de serviço. Este artigo orienta você sobre:

  • Os componentes básicos de um par de solicitação/resposta da API REST.
  • Visões gerais de criação e envio de uma solicitação REST e manipulação da resposta.

A maioria das APIs REST é acessível por meio de nossas bibliotecas de clientes, que podem ser usadas para simplificar muito o código do cliente.

Componentes de um par de solicitação/resposta da API REST

Um par de solicitação/resposta da API REST pode ser separado em cinco componentes:

  1. O URI da solicitação, no seguinte formato: VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • instância: o Azure DevOps Services organização ou servidor TFS para o qual você está enviando a solicitação. Eles são estruturados da seguinte maneira:
      • Azure DevOps Services:dev.azure.com/{organization}
      • TFS: {server:port}/tfs/{collection} (a porta padrão é 8080 e o valor da coleção deve ser DefaultCollection , mas pode ser qualquer coleção)
    • caminho do recurso: o caminho do recurso é o seguinte: _apis/{area}/{resource}. Por exemplo, _apis/wit/workitems.
    • api-version: cada solicitação de API deve incluir uma versão da API para evitar que seu aplicativo ou serviço interrompa à medida que as APIs evoluem. as versões de api estão no seguinte formato: {major}.{minor}[-{stage}[.{resource-version}]], por exemplo:
      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

    Observação: a área e o projeto de equipe são opcionais, dependendo da solicitação de API. Confira a matriz de mapeamento de versão do TFS para a API REST abaixo para encontrar quais versões da API REST se aplicam à sua versão do TFS.

  2. Campos de cabeçalho de mensagem de solicitação HTTP:

    • Um método HTTP obrigatório (também conhecido como uma operação ou um verbo), que indica ao serviço que tipo de operação está sendo solicitada. As APIs REST do Azure dão suporte aos métodos GET, HEAD, PUT, POST e PATCH.
    • Campos de cabeçalho adicionais opcionais, conforme exigido pelo URI e método HTTP especificados. Por exemplo, um cabeçalho authorization que fornece um token de portador que contém informações de autorização do cliente para a solicitação.

  3. Campos opcionais de corpo da mensagem de solicitação HTTP, para dar suporte à operação de URI e HTTP. Por exemplo, as operações POST contêm objetos codificado em MIME que são passados como parâmetros complexos.

    • Para operações POST ou PUT, o tipo de codificação MIME para o corpo também deve ser especificado no cabeçalho de solicitação Tipo de conteúdo. Alguns serviços exigem o uso de um tipo MIME específico, como application/json.

  4. Campos de cabeçalho da mensagem de resposta HTTP:

    • Um código de status HTTP, que varia de códigos de sucesso 2xx a códigos de erro 4xx ou 5xx. Como alternativa, um código de status definido pelo serviço pode ser retornado, conforme indicado na documentação da API.
    • Campos de cabeçalho adicionais opcionais, conforme necessário, para dar suporte à resposta da solicitação, como um cabeçalho de resposta Content-type.

  5. Campos opcionais de corpo da mensagem de resposta HTTP:

    • Objetos de resposta codificados em MIME podem ser retornados no corpo da resposta HTTP, como uma resposta de um método GET que está retornando dados. Normalmente, esses objetos são retornados em um formato estruturado como JSON ou XML, conforme indicado pelo cabeçalho de resposta Content-type. Por exemplo, quando você solicita um token de acesso de Azure AD, ele será retornado no corpo da resposta como o access_token elemento , um dos vários objetos emparelhados nome/valor em uma coleção de dados. Neste exemplo, um cabeçalho de resposta de Content-Type: application/json também está incluído.

Criar a solicitação

Authenticate

Há várias maneiras de autenticar seu aplicativo ou serviço com Azure DevOps Services ou TFS. A tabela a seguir é uma excelente maneira de decidir qual método é o melhor para você:

Tipo de aplicativo Descrição exemplo Mecanismo de autenticação Exemplos de código
Lado interativo do cliente Aplicativo cliente, que permite a interação do usuário, chamando Azure DevOps Services APIs REST Aplicativo de console enumerando projetos em uma organização MSAL (Biblioteca de Autenticação da Microsoft) sample
JavaScript interativo Aplicativo JavaScript baseado em GUI Aplicativo de página única angularJS exibindo informações do projeto para um usuário MSAL sample
Lado do cliente não interativo Aplicativo do lado do cliente somente texto sem periférito Aplicativo de console exibindo todos os bugs atribuídos a um usuário Perfil do Dispositivo sample
Web interativa Aplicativo Web baseado em GUI Web dashboard personalizada exibindo resumos de build OAuth sample
Aplicativo TFS Aplicativo TFS usando a biblioteca de OM do Cliente Extensão do TFS exibindo painéis de bugs da equipe Bibliotecas de cliente sample
Extensão Azure DevOps Services Extensão Azure DevOps Services Exemplos de extensão do Azure DevOps SDK da Extensão web do VSS passo a passo de exemplo

Nota: Você pode encontrar mais informações sobre autenticação em nossa página de diretrizes de autenticação.

Montar a solicitação

Azure DevOps Services

Para Azure DevOps Services, a instância é dev.azure.com/{organization}, portanto, o padrão tem esta aparência:

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

Por exemplo, veja como obter uma lista de projetos de equipe em uma organização Azure DevOps Services.

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

Se você quiser fornecer o token de acesso pessoal por meio de um cabeçalho HTTP, primeiro converta-o em uma cadeia de caracteres Base64 (o exemplo a seguir mostra como converter em Base64 usando C#). (Determinadas ferramentas como o Postman aplicam uma codificação Base64 por padrão. Se você estiver experimentando a API por meio dessas ferramentas, a codificação Base64 do PAT não será necessária) A cadeia de caracteres resultante poderá ser fornecida como um cabeçalho HTTP no formato:

Authorization: Basic BASE64PATSTRING

Aqui está em C# usando a [classe 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());
	}
}

A maioria dos exemplos neste site usa Tokens de Acesso Pessoal, pois eles são um exemplo compacto para autenticação com o serviço. No entanto, há uma variedade de mecanismos de autenticação disponíveis para Azure DevOps Services incluindo MSAL, OAuth e Tokens de Sessão. Consulte a seção Autenticação para obter diretrizes sobre qual delas é mais adequada para seu cenário.

TFS

Para TFS, instance é {server:port}/tfs/{collection} e, por padrão, a porta é 8080. A coleção padrão é DefaultCollection, mas pode ser qualquer coleção.

Veja como obter uma lista de projetos de equipe do TFS usando a porta e a coleção padrão.

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

Os exemplos acima usam tokens de acesso pessoal, o que exige que você crie um token de acesso pessoal.

Processar a resposta

Você deve receber uma resposta como esta.

{
    "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
}

A resposta é JSON. Geralmente, isso é o que você receberá das APIs REST, embora haja algumas exceções, como blobs git.

Agora você deve ser capaz de examinar as áreas de API específicas, como acompanhamento de itens de trabalho ou Git , e acessar os recursos necessários. Continue lendo para saber mais sobre os padrões gerais usados nessas APIs.

Mapeamento de versão da API e do TFS

Abaixo, você encontrará um mapeamento rápido das versões da API REST e suas versões de TFS correspondentes. Todas as versões da API funcionarão na versão do servidor mencionada, bem como em versões posteriores.

Versão do TFS Versão da API REST Versão da compilação
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 Atualização 3 4.1 versions >= 16.131.28106.2
TFS 2018 Atualização 2 4.1 versions >= 16.131.27701.1
TFS 2018 Atualização 1 4,0 versions >= 16.122.27409.2
TFS 2018 RTW 4,0 versions >= 16.122.27102.1
TFS 2017 Atualização 2 3.2 versions >= 15.117.26714.0
TFS 2017 Atualização 1 3.1 versions >= 15.112.26301.0
TFS 2017 RTW 3,0 versions >= 15.105.25910.0
TFS 2015 Atualização 4 2.3 versions >= 14.114.26403.0
TFS 2015 Atualização 3 2.3 versions >= 14.102.25423.0
TFS 2015 Atualização 2 2,2 versions >= 14.95.25122.0
TFS 2015 Atualização 1 2.1 versions >= 14.0.24712.0
TFS 2015 RTW 2,0 versions >= 14.0.23128.0

Conteúdo relacionado

Confira a documentação Integrar para exemplos de API REST e casos de uso.

Bibliotecas de cliente

Descubra as bibliotecas de cliente para essas APIs REST.

Onde estão as versões anteriores das APIs REST? (Antes da 4.1)

Recentemente, fizemos uma alteração em nosso sistema de engenharia e no processo de geração de documentação; fizemos essa alteração para fornecer uma documentação mais clara, mais detalhada e mais precisa para todos que tentam usar essas APIs REST. Devido a restrições técnicas, só podemos documentar a API versão 4.1 e mais recente usando esse método. Acreditamos que a documentação da API versão 4.1 e mais recente será mais fácil de usar devido a essa alteração.

Se você estiver trabalhando no TFS ou estiver procurando as versões mais antigas das APIs REST, poderá dar uma olhada na Visão geral da API REST para TFS 2015, 2017 e 2018.