Compartilhar via

Introdução às APIs REST

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Integre seu aplicativo ao Azure DevOps usando as APIs REST fornecidas neste artigo.

As APIs seguem um padrão comum, como o exemplo a seguir.

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

Dica

À medida que as APIs evoluem, recomendamos que você inclua uma versão da API em cada solicitação. Essa prática pode ajudá-lo a evitar alterações inesperadas na API que podem ser interrompidas.

Azure DevOps Services

Para os Serviços de DevOps do Azure, é dev.azure.com/{organization} e collection é DefaultCollection, portanto, instance o padrão se parece com o exemplo a seguir.

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

O exemplo a seguir mostra como obter uma lista de projetos em uma organização.

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

Se você deseja fornecer o token de acesso pessoal (PAT) por meio de um cabeçalho HTTP, você deve primeiro convertê-lo em uma cadeia de caracteres Base64. O exemplo a seguir mostra como converter para Base64 usando C#. A cadeia de caracteres resultante pode então ser fornecida como um cabeçalho HTTP no formato.

Authorization: Basic BASE64PATSTRING

O exemplo a seguir mostra C# usando a classe 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());
	}
}

A maioria de nossas amostras usa PATs, pois eles são um exemplo compacto para autenticação com o serviço. No entanto, há vários mecanismos de autenticação disponíveis para os Serviços de DevOps do Azure, incluindo MSAL (Biblioteca de Autenticação da Microsoft), OAuth e Tokens de Sessão. Para obter mais informações, consulte Diretrizes de autenticação, para ajudá-lo a determinar qual é o mais adequado para o seu cenário.

Azure DevOps Server

Para o Servidor de DevOps do Azure, instance é {server:port}. A porta padrão para uma conexão não-SSL é 8080.

A coleção padrão é DefaultCollection, mas você pode usar qualquer coleção.

Veja como obter uma lista de projetos do Servidor de DevOps do Azure usando a porta e a coleção padrão em SSL:

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

Para obter a mesma lista em uma conexão não-SSL:

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

Esses exemplos usam PATs, que exigem que você crie um PAT.

Respostas

Você deve obter 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"
            },
            "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
}

A resposta é JSON, que geralmente é o que você obtém das APIs REST, embora haja algumas exceções, como blobs Git.

Agora, você pode examinar as áreas específicas da API, como rastreamento de item de trabalho ou Git, e acessar os recursos necessários. Continue lendo para saber mais sobre os padrões gerais que são usados nessas APIs.

Verbos HTTP

Verbo Usado para...
GET Obter um recurso ou uma lista de recursos
POSTAR Criar um recurso, Obter uma lista de recursos usando uma consulta mais avançada
PUT Criar um recurso se ele não existir ou, se existir, atualizá-lo
PATCH Atualizar um recurso
DELETE Excluir um recurso

Cabeçalhos de solicitação e conteúdo de solicitação

Quando você fornece o corpo da solicitação (geralmente com os verbos POST, PUT e PATCH), inclua cabeçalhos de solicitação que descrevam o corpo. Por exemplo,

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

Content-Type: application/json

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

Substituição do método HTTP

Alguns proxies da Web podem suportar apenas os verbos HTTP GET e POST, mas não verbos HTTP mais modernos, como PATCH e DELETE. Se suas chamadas passarem por um desses proxies, você poderá enviar o verbo real usando um método POST, com um cabeçalho para substituir o método. Por exemplo, talvez você queira atualizar um item de trabalho (PATCH _apis/wit/workitems/3), mas talvez precise passar por um proxy que permita apenas GET ou POST. Você pode passar o verbo apropriado (PATCH neste caso) como um parâmetro de cabeçalho de solicitação HTTP e usar POST como o método HTTP real.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Códigos de resposta

Resposta Observações
200 Sucesso, e há um corpo de resposta.
201 Sucesso, ao criar recursos. Algumas APIs retornam 200 ao criar um recurso com êxito. Olhe para os documentos da API que você está usando para ter certeza.
204 Sucesso, e não há corpo de resposta. Por exemplo, você obtém essa resposta quando exclui um recurso.
400 Os parâmetros na URL ou no corpo da solicitação não são válidos.
401 Falha na autenticação. Muitas vezes, essa resposta é devido a um cabeçalho de autorização ausente ou malformado.
403 O usuário autenticado não tem permissão para fazer a operação.
404 O recurso não existe ou o usuário autenticado não tem permissão para ver que ele existe.
409 Há um conflito entre a solicitação e o estado dos dados no servidor. Por exemplo, se você tentar enviar uma solicitação pull e já houver uma solicitação pull para as confirmações, o código de resposta será 409.

Compartilhamento de recursos entre origens (CORS)

Os Serviços de DevOps do Azure dão suporte ao CORS, que permite que o código JavaScript servido de um domínio diferente de dev.azure.com/* fazer solicitações Ajax para APIs REST dos Serviços de DevOps do Azure. Cada solicitação deve fornecer credenciais (PATs e tokens de acesso OAuth são opções com suporte). Exemplo:

    $( 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 );
        });
    });

(substitua myPatToken por um token de acesso pessoal)

Controle de versão

As APIs REST do Azure DevOps são versionadas para garantir que os aplicativos e serviços continuem a funcionar à medida que as APIs evoluem.

Diretrizes

  • Especifique a versão da API com cada solicitação (obrigatório).
  • Formate as versões da API da seguinte maneira: {major}. {menor}-{estágio}. {resource-version}. Por exemplo, 1.0, 1.1, 1.2-preview, 2.0.
  • Especifique uma revisão específica da API quando ela estiver em visualização, usando o seguinte formato de versão: 1.0-preview.1, 1.0-preview.2. Depois que uma API é lançada (1.0, por exemplo), sua versão prévia (1.0-preview) é preterida e pode ser desativada após 12 semanas.
  • Atualize para a versão lançada da API. Depois que uma API de visualização é desativada, as solicitações que especificam -preview a versão são rejeitadas.

Uso

Especifique a versão da API no cabeçalho da solicitação HTTP ou como um parâmetro de consulta de URL.

Cabeçalho de solicitação HTTP:

Accept: application/json;api-version=1.0

Parâmetro de consulta:

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

Versões suportadas

Para obter informações sobre versões com suporte, consulte Controle de versão da API REST, Versões com suporte.