Prise en main des API REST

  • Article

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

Intégrez votre application à Azure DevOps à l’aide des API REST fournies dans cet article.

Les API suivent un modèle courant, comme l’exemple suivant.

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

Conseil

À mesure que les API évoluent, nous vous recommandons d’inclure une version d’API dans chaque requête. Cette pratique peut vous aider à éviter des modifications inattendues dans l’API qui pourraient s’interrompre.

Azure DevOps Services

Pour Azure DevOps Services, instance c’est et collection c’est dev.azure.com/{organization} DefaultCollectionpourquoi le modèle ressemble à l’exemple suivant.

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

L’exemple suivant montre comment obtenir une liste de projets dans une organisation.

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

Si vous souhaitez fournir le jeton d’accès personnel (PAT) via un en-tête HTTP, vous devez d’abord le convertir en chaîne Base64. L’exemple suivant montre comment effectuer une conversion en Base64 à l’aide de C#. La chaîne résultante peut ensuite être fournie en tant qu’en-tête HTTP au format.

Authorization: Basic BASE64PATSTRING

L’exemple suivant montre C# à l’aide de la 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());
	}
}

La plupart de nos exemples utilisent des PAT, car ils sont un exemple compact pour l’authentification auprès du service. Toutefois, il existe différents mécanismes d’authentification disponibles pour Azure DevOps Services, notamment la bibliothèque d’authentification Microsoft (MSAL), OAuth et les jetons de session. Pour plus d’informations, consultez les conseils d’authentification pour vous aider à déterminer celui qui convient le mieux à votre scénario.

Azure DevOps Server

Pour Azure DevOps Server, instance est {server:port}. Le port par défaut d’une connexion non SSL est 8080.

La collection par défaut est DefaultCollection, mais vous pouvez utiliser n’importe quelle collection.

Voici comment obtenir la liste des projets à partir d’Azure DevOps Server à l’aide du port et de la collection par défaut sur SSL :

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

Pour obtenir la même liste sur une connexion non SSL :

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

Ces exemples utilisent des PAT, qui nécessitent la création d’un protocole PAT.

Réponses

Vous devez obtenir une réponse comme celle-ci.

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

La réponse est JSON, qui est généralement ce que vous récupérez à partir des API REST, bien qu’il existe quelques exceptions, comme les objets blob Git.

À présent, vous pouvez examiner les zones d’API spécifiques telles que le suivi des éléments de travail ou Git et accéder aux ressources dont vous avez besoin. Continuez à lire pour en savoir plus sur les modèles généraux utilisés dans ces API.

Verbes HTTP

Verbe Utilisé pour...
GET Obtenir une ressource ou une liste de ressources
POST Créer une ressource, obtenir une liste de ressources à l’aide d’une requête plus avancée
PUT Créez une ressource s’il n’existe pas ou, si c’est le cas, mettez-la à jour
PATCH Mettre à jour une ressource
DELETE Supprimer une ressource

En-têtes de requête et contenu de requête

Lorsque vous fournissez le corps de la demande (généralement avec les verbes POST, PUT et PATCH), incluez des en-têtes de requête qui décrivent le corps. Par exemple,

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

Content-Type: application/json

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

Remplacement de méthode HTTP

Certains proxys web peuvent uniquement prendre en charge les verbes HTTP GET et POST, mais pas des verbes HTTP plus modernes tels que PATCH et DELETE. Si vos appels peuvent passer par l’un de ces proxys, vous pouvez envoyer le verbe réel à l’aide d’une méthode POST, avec un en-tête pour remplacer la méthode. Par exemple, vous pouvez mettre à jour un élément de travail (PATCH _apis/wit/workitems/3), mais vous devrez peut-être passer par un proxy qui autorise uniquement GET ou POST. Vous pouvez passer le verbe approprié (PATCH dans ce cas) en tant que paramètre d’en-tête de requête HTTP et utiliser POST comme méthode HTTP réelle.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Codes de réponse

Response Notes
200 Réussite, et il y a un corps de réponse.
201 Réussite, lors de la création de ressources. Certaines API retournent 200 lors de la création d’une ressource. Examinez les documents de l’API que vous utilisez pour être sûr.
204 Réussite, et il n’y a pas de corps de réponse. Par exemple, vous obtenez cette réponse lorsque vous supprimez une ressource.
400 Les paramètres de l’URL ou du corps de la demande ne sont pas valides.
401 Échec de l'authentification. Souvent, cette réponse est due à un en-tête d’autorisation manquant ou mal formé.
403 L’utilisateur authentifié n’est pas autorisé à effectuer l’opération.
404 La ressource n’existe pas ou l’utilisateur authentifié n’a pas l’autorisation de voir qu’elle existe.
409 Il existe un conflit entre la requête et l’état des données sur le serveur. Par exemple, si vous tentez d’envoyer une demande de tirage (pull request) et qu’il existe déjà une demande de tirage pour les validations, le code de réponse est 409.

Partage des ressources cross-origin (CORS)

Azure DevOps Services prend en charge CORS, qui permet au code JavaScript servi à partir d’un domaine autre que dev.azure.com/* d’effectuer des requêtes Ajax aux API REST Azure DevOps Services. Chaque demande doit fournir des informations d’identification (les jetons d’accès OAuth et les jetons d’accès OAuth sont les deux options prises en charge). Exemple :

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

(remplacer par myPatToken un jeton d’accès personnel)

Contrôle de version

Les API REST Azure DevOps sont mises à jour pour garantir que les applications et les services continuent de fonctionner à mesure que les API évoluent.

Consignes

  • Spécifiez la version de l’API avec chaque requête (obligatoire).
  • Mettre en forme les versions d’API comme suit : {major}. {minor}-{stage}. {resource-version}. Par exemple 1.0, 1.1, 1.2-preview, 2.0.
  • Spécifiez une révision particulière de l’API lorsqu’elle est en préversion, en utilisant le format de version suivant : 1.0-preview.1, 1.0-preview.2. Une fois qu’une API est publiée, la version 1.0, par exemple, sa préversion (1.0-preview) est déconseillée et peut être désactivée au bout de 12 semaines.
  • Effectuez une mise à niveau vers la version publiée de l’API. Une fois qu’une API en préversion est désactivée, les demandes qui spécifient la -preview version sont rejetées.

Utilisation

Spécifiez la version de l’API dans l’en-tête de la requête HTTP ou en tant que paramètre de requête d’URL.

En-tête de requête HTTP :

Accept: application/json;api-version=1.0

Paramètre de requête :

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

Versions prises en charge

Pour plus d’informations sur les versions prises en charge, consultez gestion des versions de l’API REST, versions prises en charge.