Share via

Introdução às APIs REST

  • Artigo

Serviços de DevOps do Azure | 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}

Gorjeta

À 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 quebrar.

Serviços de DevOps do Azure

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ê quiser fornecer o token de acesso pessoal (PAT) através 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 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 dos nossos exemplos 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 a Biblioteca de Autenticação da Microsoft (MSAL), OAuth e Tokens de Sessão. Para obter mais informações, consulte Diretrizes de autenticação, para ajudá-lo a determinar qual é mais adequado para o seu cenário.

Azure DevOps Server

Para o Azure DevOps Server, 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 padrão e a coleção em SSL:

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

Para obter a mesma lista através de uma conexão não-SSL:

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

Estes 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ê recebe de volta das APIs REST, embora haja algumas exceções, como blobs Git.

Agora, você pode olhar em torno das áreas específicas da API, como rastreamento de item de trabalho ou Git, e obter os recursos de que precisa. Continue lendo para saber mais sobre os padrões gerais usados nessas APIs.

Verbos HTTP

Verbo Usado para...
GET Obter um recurso ou uma lista de recursos
POST 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 Eliminar um recurso

Solicitar cabeçalhos e solicitar conteúdo

Quando você fornecer 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 podem passar por um desses proxies, você pode 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 seja necessário passar por um proxy que permita apenas GET ou POST. Você pode passar o verbo adequado (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

Response Notas
200 Sucesso, e há um corpo de resposta.
201 Sucesso, na criação de 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ê recebe essa resposta quando exclui um recurso.
400 Os parâmetros no 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 se 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.

Partilha de recursos transversais à origem (CORS)

Os Serviços de DevOps do Azure dão suporte ao CORS, que permite que o código JavaScript servido a partir 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 suportadas). 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 );
        });
    });

(substituir myPatToken por um token de acesso pessoal)

Controlo 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 forma: {major}. {menor}-{estágio}. {resource-version}. Por exemplo, 1.0, , 1.1, 2.01.2-preview.
  • 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 do lançamento de uma API (por exemplo, 1.0), a versão de pré-visualização (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.

Utilização

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

Cabeçalho da 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 as versões suportadas, consulte Controle de versão da API REST, Versões suportadas.