Partager via

Démarrer avec les API REST

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

Les API REST Azure DevOps fournissent un accès programmatique puissant aux éléments de travail, référentiels, builds, versions, etc. Que vous créez des intégrations personnalisées, automatisez des flux de travail ou étendez des fonctionnalités Azure DevOps, il est essentiel de comprendre les modèles et concepts fondamentaux pour réussir l’implémentation.

Conseil / Astuce

Vous êtes prêt à commencer à coder ? Passez aux exemples d’API REST pour obtenir des exemples de travail complets avec des modèles d’authentification modernes.

Cet article décrit les concepts fondamentaux et les modèles des API REST Azure DevOps. Pour obtenir des exemples d’implémentation pratiques, consultez les exemples d’API REST.

Structure d’URL

Les API suivent un modèle courant, comme illustré dans l’exemple suivant :

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

Conseil / Astuce

À 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 est dev.azure.com/{organization} et collection est DefaultCollection, donc le modèle ressemble à l'exemple suivant :

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

Exemple de point de terminaison :

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Serveur Azure DevOps

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.

Exemples :

  • SSL : https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • Non SSL : http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Authentification

Les API REST Azure DevOps prennent en charge plusieurs méthodes d’authentification :

  • ID Microsoft Entra - Recommandé pour les applications de production
  • Jetons d’accès personnels (PAT) - Authentification simple pour les scripts et les tests
  • OAuth 2.0 - Pour les applications non-Microsoft
  • Principaux de service - Pour les scénarios automatisés

Importante

L’authentification Microsoft Entra ID est l’approche recommandée pour les applications de production. Pour obtenir des exemples d’implémentation et suivre des instructions d’authentification complètes, consultez les exemples d’API REST et les conseils d’authentification.

Format de la réponse

Les API REST Azure DevOps retournent généralement des réponses JSON. Voici un exemple de structure de réponse :

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects"
        }
    ],
    "count": 1
}

La réponse est un JSON, généralement ce que l'on obtient des API REST, bien qu'il existe quelques exceptions, comme les blobs Git.

Conseil / Astuce

Pour obtenir des exemples de travail complets montrant comment analyser ces réponses, consultez les exemples d’API REST.

Méthodes et opérations HTTP

Les API REST Azure DevOps utilisent des méthodes HTTP standard :

Méthode Utilisé pour... Exemple :
GET Obtenir une ressource ou une liste de ressources Obtenir des projets, des éléments de travail
PUBLIER Créer une ressource ou obtenir des ressources à l’aide de requêtes avancées Créer des éléments de travail, interroger des éléments de travail
PUT Créer ou remplacer complètement une ressource Créer/mettre à jour un élément de travail
PATCH Mettre à jour des champs spécifiques d’une ressource Mettre à jour les champs d’élément de travail
Supprimer Supprimer une ressource Supprimer un élément de travail

Conseil / Astuce

Pour obtenir des exemples pratiques de chaque méthode HTTP avec des exemples de code complets, consultez les exemples d’API REST.

En-têtes de requête et contenu

Lorsque vous fournissez un corps de requête (généralement avec POST, PUT et PATCH), incluez les en-têtes appropriés :

Content-Type: application/json

Pour les opérations PATCH sur les éléments de travail, utilisez :

Content-Type: application/json-patch+json

Remplacement de la 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

Comprendre les codes de réponse HTTP vous aide à gérer les réponses d’API de manière appropriée :

Réponse Signification Remarques
200 Succès Le corps de la réponse contient les données demandées
201 Créé Ressource créée avec succès
204 Succès Aucun corps de réponse (fréquent avec DELETE)
400 Demande incorrecte Paramètres ou corps de requête non valides
401 Non autorisée Échec ou absence de l’authentification
4:03 Interdit L’utilisateur n’a pas d’autorisation pour l’opération
404 Introuvable La ressource n’existe pas ou n’est pas autorisée à afficher
409 Conflit La requête est en conflit avec l'état actuel de la ressource.

Contrôle de version d’API

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

Lignes directrices

  • Spécifiez toujours la version de l’API avec chaque requête (obligatoire)
  • Mettre en forme les versions d’API en tant que : {major}.{minor} ou {major}.{minor}-{stage} (par exemple, 7.2, 7.2-preview)
  • Utilisez des révisions en préversion spécifiques quand elles sont disponibles : 7.2-preview.1, 7.2-preview.2
  • Mettez à niveau vers les versions publiées lorsque les API de préversion sont obsolètes

Utilisation

Spécifiez la version de l’API en tant que paramètre de requête d’URL :

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Ou dans l’en-tête de requête :

Accept: application/json;api-version=7.2

Pour connaître les versions prises en charge, consultez gestion des versions de l’API REST.

Plus de ressources

Pour obtenir des conseils pratiques sur l’implémentation et des exemples de code complets, consultez :

Étapes suivantes

Essayer des exemples d’API REST

  • Last updated on