Referência da API REST do Azure DevOps Services

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ê:

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.

Conteúdo relacionado

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

• Diretrizes de autenticação
• Amostras

Bibliotecas de cliente

Descubra as bibliotecas de cliente para essas APIs REST.

• Documentação conceitual do .NET e documentação de referência do .NET
• Go
• Node.js
• Python
• Swagger 2.0
• SDK de Extensões da Web

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.