Informations de référence sur l’API REST Azure DevOps Services

Bienvenue dans la référence de l’API REST Azure DevOps Services/Azure DevOps Server.

Les API REST (Representational State Transfer) sont des points de terminaison de service prenant en charge des ensembles d’opérations HTTP (méthodes) qui fournissent, créent, récupèrent, mettent à jour ou suppriment l’accès aux ressources du service. Cet article vous guide tout au long des procédures suivantes :

• Composants de base d’une paire demande/réponse d’API REST.
• Vue d’ensemble de la création et de l’envoi d’une requête REST et de la gestion de la réponse.

La plupart des API REST sont accessibles via nos bibliothèques clientes, qui peuvent être utilisées pour simplifier considérablement votre code client.

Composants d’une paire demande/réponse d’API REST

Une paire demande/réponse d’API REST peut être divisée en cinq composants :

1. URI de requête, sous la forme suivante :VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instance : serveur Azure DevOps Services organization ou TFS auquel vous envoyez la demande. Ils sont structurés comme suit :
     • Azure DevOps Services :dev.azure.com/{organization}
     • TFS : {server:port}/tfs/{collection} (le port par défaut est 8080, et la valeur de la collection doit être DefaultCollection mais peut être n’importe quelle collection)
   • chemin de ressource : le chemin de la ressource est le suivant : _apis/{area}/{resource}. Par exemple, _apis/wit/workitems.
   • api-version : chaque demande d’API doit inclure une version d’API pour éviter que votre application ou service ne s’interrompe à mesure que les API évoluent. api-versions sont au format suivant : {major}.{minor}[-{stage}[.{resource-version}]], par exemple :
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   Remarque : la zone et le projet d’équipe sont facultatifs, en fonction de la demande d’API. Consultez la matrice de mappage des versions de l’API TFS vers REST ci-dessous pour déterminer quelles versions d’API REST s’appliquent à votre version de TFS.

2. Champs d’en-tête de message de requête HTTP :

   • Méthode HTTP obligatoire (également appelée opération ou verbe), qui indique au service le type d’opération que vous demandez. Les API REST Azure prennent en charge les méthodes GET, HEAD, PUT, POST et PATCH.
   • Des champs d’en-tête supplémentaires facultatifs, suivant l’URI et la méthode HTTP spécifiés. Par exemple, un en-tête d’autorisation qui fournit un jeton du porteur contenant des informations d’autorisation client pour la demande.

3. Des champs du corps de message de demande HTTP, pour prendre en charge l’URI et l’opération HTTP. Par exemple, les opérations POST contiennent des objets codés au format MIME qui sont passés comme paramètres complexes.

   • Pour les opérations POST ou PUT, le type d’encodage MIME pour le corps doit également être spécifié dans l’en-tête de requête Content-type. Certains services vous obligent à utiliser un type MIME spécifique, tel que application/json.

4. Champs d’en-tête du message de réponse HTTP :

   • Un code d’état HTTP, compris entre 2xx (opérations réussies) et 4xx ou 5xx (erreur). Ou bien un code d’état défini par le service peut être retourné, comme indiqué dans la documentation de l’API.
   • Des champs d’en-tête supplémentaires facultatifs, nécessaires à la prise en charge de la réponse de la demande, tels qu’un en-tête de réponse Content-type.

5. Champs du corps du message de réponse HTTP facultatifs :

   • Les objets de réponse encodés en MIME peuvent être retournés dans le corps de la réponse HTTP, par exemple une réponse d’une méthode GET qui retourne des données. En règle générale, ces objets sont retournés dans un format structuré tel que JSON ou XML, comme indiqué par l’en-tête de réponse Content-type. Par exemple, lorsque vous demandez un jeton d’accès auprès d’Azure AD, il est retourné dans le corps de la access_token réponse en tant qu’élément, l’un des objets associés nom/valeur dans une collection de données. Dans cet exemple, un en-tête de réponse de Content-Type: application/json est également inclus.

Créer la requête

Authenticate

Il existe de nombreuses façons d’authentifier votre application ou votre service avec Azure DevOps Services ou TFS. Le tableau suivant est un excellent moyen de déterminer la méthode qui vous convient le mieux :

Note: Vous trouverez plus d’informations sur l’authentification sur notre page d’aide sur l’authentification.

Assembler la requête

Azure DevOps Services

Par Azure DevOps Services, instance est dev.azure.com/{organization}, le modèle ressemble à ceci :

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

Par exemple, voici comment obtenir la liste des projets d’équipe dans un Azure DevOps Services organization.

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 via un en-tête HTTP, vous devez d’abord le convertir en chaîne Base64 (l’exemple suivant montre comment convertir en Base64 à l’aide de C#). (Certains outils comme Postman appliquent un encodage Base64 par défaut. Si vous essayez l’API via ces outils, l’encodage en Base64 du PAT n’est pas obligatoire) La chaîne résultante peut ensuite être fournie en tant qu’en-tête HTTP au format :

Authorization: Basic BASE64PATSTRING

Ici, il est en C# à l’aide de la [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());
	}
}

La plupart des exemples de ce site utilisent des jetons d’accès personnels, car il s’agit d’un exemple compact pour l’authentification auprès du service. Toutefois, il existe divers mécanismes d’authentification disponibles pour Azure DevOps Services, notamment MSAL, OAuth et jetons de session. Reportez-vous à la section Authentification pour obtenir des conseils sur celle qui convient le mieux à votre scénario.

TFS

Pour TFS, est {server:port}/tfs/{collection} et, par défaut, instance le port est 8080. La collection par défaut est DefaultCollection, mais peut être n’importe quelle collection.

Voici comment obtenir la liste des projets d’équipe à partir de TFS à l’aide du port et de la collection par défaut.

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

Les exemples ci-dessus utilisent des jetons d’accès personnels, ce qui vous oblige à créer un jeton d’accès personnel.

Traiter la réponse

Vous devriez 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/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 réponse est JSON. C’est généralement ce que vous obtiendrez des API REST, bien qu’il existe quelques exceptions, comme les objets blob Git.

Vous devez maintenant être en mesure d’examiner les zones d’API spécifiques, telles que le suivi des éléments de travail ou Git , et d’accéder aux ressources dont vous avez besoin. Poursuivez votre lecture pour en savoir plus sur les modèles généraux utilisés dans ces API.

Mappage de version d’API et de TFS

Vous trouverez ci-dessous un mappage rapide des versions de l’API REST et de leurs versions TFS correspondantes. Toutes les versions d’API fonctionnent sur la version du serveur mentionnée, ainsi que sur les versions ultérieures.

Contenu associé

Consultez la documentation d’intégration pour les exemples d’API REST et les cas d’usage.

• Conseils d’authentification
• Exemples

Bibliothèques clientes

Découvrez les bibliothèques clientes pour ces API REST.

• Documentation conceptuelle .NET et documentation de référence .NET
• Go
• Node.JS
• Python
• Swagger 2.0
• Kit de développement logiciel (SDK) Web Extensions

Où se trouvent les versions antérieures des API REST ? (Avant la version 4.1)

Nous avons récemment apporté une modification à notre système d’ingénierie et à notre processus de génération de documentation; Nous avons apporté cette modification pour fournir une documentation plus claire, plus détaillée et plus précise à tous ceux qui tentent d’utiliser ces API REST. En raison de contraintes techniques, nous pouvons uniquement documenter l’API version 4.1 et ultérieure à l’aide de cette méthode. Nous pensons que la documentation de l’API version 4.1 et ultérieure sera plus facile à utiliser en raison de ce changement.

Si vous travaillez dans TFS ou si vous recherchez les anciennes versions des API REST, vous pouvez consulter la vue d’ensemble de l’API REST pour TFS 2015, 2017 et 2018.