Referencia de la API rest de Azure DevOps Services

Le damos la bienvenida a la referencia de la API rest de Azure DevOps Services/Azure DevOps Server.

Las API de transferencia de estado representacional (REST) son puntos de conexión de servicio que admiten una serie de operaciones HTTP (métodos), que proporcionan acceso de creación, recuperación, actualización o eliminación del acceso a los recursos del servicio. Este artículo le enseñará a:

• Los componentes básicos de un par de solicitud/respuesta de la API rest.
• Información general sobre cómo crear y enviar una solicitud REST y controlar la respuesta.

La mayoría de las API REST son accesibles a través de nuestras bibliotecas cliente, que se pueden usar para simplificar considerablemente el código de cliente.

Componentes de un par de solicitud y respuesta de la API rest

Un par de solicitud/respuesta de una API de REST puede dividirse en cinco componentes:

1. El URI de solicitud, en el siguiente formato: VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instance: el Azure DevOps Services organización o servidor TFS al que va a enviar la solicitud. Se estructuran de la siguiente manera:
     • Azure DevOps Services:dev.azure.com/{organization}
     • TFS: {server:port}/tfs/{collection} (el puerto predeterminado es 8080 y el valor de la colección debe ser DefaultCollection pero puede ser cualquier colección).
   • ruta de acceso del recurso: la ruta de acceso del recurso es la siguiente: _apis/{area}/{resource}. Por ejemplo, _apis/wit/workitems.
   • api-version: todas las solicitudes de API deben incluir una versión de API para evitar que la aplicación o el servicio se interrumpan a medida que evolucionan las API. las versiones de api tienen el siguiente formato: {major}.{minor}[-{stage}[.{resource-version}]], por ejemplo:
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   Nota: el área y el proyecto de equipo son opcionales, según la solicitud de API. Consulte la matriz de asignación de versiones de la API REST de TFS a continuación para averiguar qué versiones de la API REST se aplican a la versión de TFS.

2. Campos de encabezado del mensaje de solicitud HTTP:

   • Método HTTP obligatorio (también denominado " operación" o "verbo"), que indica al servicio qué tipo de operación se está solicitando. Las API REST de Azure admiten métodos GET, HEAD, PUT, POST y PATCH.
   • Campos de encabezado adicionales y opcionales, según necesite el método HTTP y el URI especificados. Por ejemplo, un encabezado Authorization que proporciona un token de portador que contiene información de autorización de cliente para la solicitud.

3. Campos de cuerpo de mensaje de solicitudes HTTP opcionales para admitir la operación HTTP y el URI. Por ejemplo, las operaciones POST contienen objetos codificados con MIME que se pasan como parámetros complejos.

   • Para las operaciones POST o PUT, el tipo de codificación MIME para el cuerpo también debe especificarse en el encabezado de solicitud Tipo de contenido. Algunos servicios requieren que se use un tipo MIME concreto, como application/json.

4. Campos de encabezado de mensaje de respuesta HTTP:

   • Un código de estado HTTP, que puede ser 2xx para los códigos correctos y 4xx o 5xx para los códigos de error. Como alternativa se puede devolver un código de estado definido por el servicio, como se indica en la documentación de la API.
   • Campos de encabezado adicionales y opcionales, según sea necesario para admitir la respuesta a la solicitud, como un encabezado de respuesta Content-type.

5. Campos de cuerpo del mensaje de respuesta HTTP opcionales:

   • Los objetos de respuesta codificados en MIME se pueden devolver en el cuerpo de la respuesta HTTP, como una respuesta de un método GET que devuelve datos. Normalmente, estos objetos se devuelven en un formato estructurado como JSON o XML, tal y como se indica en el encabezado de respuesta Content-type. Por ejemplo, cuando se solicita un token de acceso desde Azure AD, se devolverá en el cuerpo de la respuesta como elemento access_token , uno de varios objetos emparejados de nombre y valor en una colección de datos. En este ejemplo, también se incluye un encabezado de respuesta de Content-Type: application/json .

Creación de la solicitud

Authenticate

Hay muchas maneras de autenticar la aplicación o el servicio con Azure DevOps Services o TFS. La tabla siguiente es una excelente manera de decidir qué método es el mejor para usted:

Tipo de aplicación	Descripción	ejemplo	Mecanismo de autenticación	Ejemplos de código
Lado cliente interactivo	Aplicación cliente, que permite la interacción del usuario, la llamada a Azure DevOps Services API REST	Aplicación de consola que enumera proyectos en una organización	Biblioteca de autenticación de Microsoft (MSAL)	sample
JavaScript interactivo	Aplicación JavaScript basada en GUI	Aplicación de página única de AngularJS que muestra información del proyecto para un usuario	MSAL	sample
Lado cliente no interactivo	Aplicación del lado cliente solo de texto sin encabezado	Aplicación de consola que muestra todos los errores asignados a un usuario	Perfil de dispositivo	sample
Web interactiva	Aplicación web basada en GUI	Panel web personalizado que muestra resúmenes de compilación	OAuth	sample
Aplicación TFS	Aplicación TFS mediante la biblioteca de OM de cliente	Extensión de TFS que muestra paneles de errores del equipo	Bibliotecas de cliente	sample
extensión de Azure DevOps Services	extensión de Azure DevOps Services	Ejemplos de extensión de Azure DevOps	SDK de extensión web de VSS	Tutorial de ejemplo

Nota: Puede encontrar más información sobre la autenticación en nuestra página de instrucciones de autenticación.

Ensamblar la solicitud

Azure DevOps Services

Para Azure DevOps Services, la instancia es dev.azure.com/{organization}, por lo que el patrón tiene el siguiente aspecto:

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

Por ejemplo, aquí se muestra cómo obtener una lista de proyectos de equipo en una organización de Azure DevOps Services.

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

Si desea proporcionar el token de acceso personal a través de un encabezado HTTP, primero debe convertirlo en una cadena Base64 (en el ejemplo siguiente se muestra cómo convertir a Base64 mediante C#). (Algunas herramientas como Postman aplican una codificación Base64 de forma predeterminada. Si está probando la API a través de estas herramientas, no es necesaria la codificación Base64 del PAT). La cadena resultante se puede proporcionar como un encabezado HTTP en el formato:

Authorization: Basic BASE64PATSTRING

Aquí está en C# mediante la [clase 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());
	}
}

La mayoría de los ejemplos de este sitio usan tokens de acceso personal, ya que son un ejemplo compacto para autenticarse con el servicio. Sin embargo, hay una variedad de mecanismos de autenticación disponibles para Azure DevOps Services, incluidos MSAL, OAuth y tokens de sesión. Consulte la sección Autenticación para obtener instrucciones sobre cuál es la más adecuada para su escenario.

TFS

Para TFS, instance es {server:port}/tfs/{collection} y de forma predeterminada el puerto es 8080. La colección predeterminada es DefaultCollection, pero puede ser cualquier colección.

Aquí se muestra cómo obtener una lista de proyectos de equipo de TFS mediante el puerto y la colección predeterminados.

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

En los ejemplos anteriores se usan tokens de acceso personal, lo que requiere que cree un token de acceso personal.

Procesamiento de la respuesta

Debería obtener una respuesta 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
}

La respuesta es JSON. Por lo general, eso es lo que obtendrá de las API REST, aunque hay algunas excepciones, como los blobs de Git.

Ahora debería poder buscar en torno a las áreas de API específicas, como el seguimiento de elementos de trabajo o Git , y acceder a los recursos que necesita. Siga leyendo para obtener más información sobre los patrones generales que se usan en estas API.

Asignación de versiones de API y TFS

A continuación encontrará una asignación rápida de las versiones de la API REST y sus versiones de TFS correspondientes. Todas las versiones de API funcionarán en la versión del servidor mencionada, así como en versiones posteriores.

Versión de TFS	Versión de la API REST	Versión de compilación
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 Update 3	4,1	versions >= 16.131.28106.2
TFS 2018 Update 2	4,1	versions >= 16.131.27701.1
TFS 2018 Update 1	4.0	versions >= 16.122.27409.2
TFS 2018 RTW	4.0	versions >= 16.122.27102.1
TFS 2017 Update 2	3.2	versions >= 15.117.26714.0
TFS 2017 Update 1	3.1	versions >= 15.112.26301.0
TFS 2017 RTW	3.0	versions >= 15.105.25910.0
TFS 2015 Update 4	2.3	versions >= 14.114.26403.0
TFS 2015 Update 3	2.3	versions >= 14.102.25423.0
TFS 2015 Update 2	2.2	versions >= 14.95.25122.0
TFS 2015 Update 1	2.1	versions >= 14.0.24712.0
TFS 2015 RTW	2.0	versions >= 14.0.23128.0

Contenido relacionado

Consulte la documentación integración de ejemplos de API REST y casos de uso.

• Guía de autenticación
• Muestras

Bibliotecas de cliente

Descubra las bibliotecas cliente para estas API REST.

• Documentación conceptual de .NET y documentación de referencia de .NET
• Go
• Node.js
• Python
• Swagger 2.0
• SDK de extensiones web

¿Dónde están las versiones anteriores de las API REST? (Antes de la versión 4.1)

Recientemente hicimos un cambio en nuestro sistema de ingeniería y proceso de generación de documentación; hemos realizado este cambio para proporcionar documentación más clara, detallada y precisa para todos los usuarios que intentan usar estas API REST. Debido a las restricciones técnicas, solo podemos documentar la versión 4.1 de la API y versiones posteriores mediante este método. Creemos que la documentación de la versión 4.1 de la API y versiones más recientes será más fácil de usar debido a este cambio.

Si está trabajando en TFS o busca las versiones anteriores de las API REST, puede echar un vistazo a la información general de la API REST para TFS 2015, 2017 y 2018.