Qu'est-ce que l'API REST de Jira : comment exploiter l'API REST et sécuriser la clé API Jira
Utilisation de l'API REST de Jira : un guide complet
Jira, la plateforme polyvalente de gestion de projets et de suivi des problèmes d'Atlassian, est devenue un outil indispensable pour d'innombrables équipes de développement dans le monde entier. Si son interface conviviale facilite la gestion des projets et le suivi des problèmes, la véritable puissance de Jira réside dans ses nombreuses options de personnalisation et ses capacités d'intégration. Au cœur de tout cela se trouve l'API REST de Jira, qui ouvre un monde de possibilités pour automatiser les tâches, créer des applications personnalisées et intégrer de manière transparente Jira à d'autres outils de votre écosystème de développement. Dans ce guide complet, nous allons plonger dans l'API REST de Jira, explorer ses capacités et passer en revue des exemples pratiques pour vous aider à démarrer.
Principaux plats à emporter: L'API REST de Jira est un outil polyvalent permettant d'automatiser des tâches, de créer des applications personnalisées et d'intégrer Jira à d'autres outils de développement dans les versions Cloud et Server/Data Center. Elle offre un large éventail de fonctionnalités, notamment la gestion des problèmes, les opérations groupées et la création de rapports personnalisés, avec prise en charge de fonctionnalités avancées telles que la pagination et l'extension des données. Bien qu'il existe certaines différences entre les versions, les fonctionnalités de base de l'API restent cohérentes, ce qui permet aux équipes de personnaliser efficacement Jira en fonction de leurs besoins spécifiques et de l'intégrer de manière transparente à leur écosystème de développement.
Vous pouvez essayer Jira sans utiliser l'API sur Latenode
Qu'est-ce que l'API Jira ?
À la base, une API (Application Programming Interface) est un ensemble de protocoles et d'outils qui spécifient la manière dont les composants logiciels doivent interagir. Dans le contexte de Jira, l'API permet aux applications externes d'interagir avec Jira par programmation, permettant la récupération et la manipulation de données, ainsi que l'exécution d'actions dans Jira. Jira propose deux types d'API :
Qu'est-ce que l'API Java
L'API Java Jira est un outil puissant pour les développeurs qui créent des applications ou des plugins Jira personnalisés. Elle fournit un accès direct aux objets et méthodes Java sous-jacents du serveur Jira, ce qui permet une intégration et une personnalisation approfondies. Cependant, ce niveau d'accès n'est disponible que pour les installations Jira sur site (serveur ou centre de données) où vous avez un accès direct au serveur. Si vous travaillez avec Jira Cloud ou créez une intégration autonome, l'API REST est la solution idéale.
Qu'est-ce que l'API REST
REST (Representational State Transfer) est un style architectural qui définit un ensemble de contraintes pour la création de services Web. Une API REST expose un ensemble de points de terminaison HTTP accessibles en envoyant des requêtes avec des méthodes HTTP spécifiques (GET, POST, PUT, DELETE) pour effectuer des opérations sur des ressources.
L'API REST de Jira suit cette architecture, fournissant un ensemble complet de points de terminaison pour interagir avec presque tous les aspects de Jira, des problèmes et projets aux tableaux de bord et tableaux de bord agiles. Elle renvoie des données au format JSON et prend en charge diverses méthodes d'authentification pour garantir un accès sécurisé.
L'un des principaux avantages de l'API REST est son indépendance vis-à-vis de la plateforme : vous pouvez appeler l'API à partir de n'importe quel appareil ou application capable d'effectuer des requêtes HTTP, quel que soit le langage de programmation utilisé. Cela en fait le choix idéal pour créer des intégrations entre Jira et d'autres outils, ou pour créer des scripts d'interactions avec Jira à partir de la ligne de commande.
Que pouvez-vous faire avec l’API REST Jira ?
Les possibilités sont presque infinies. Voici quelques exemples de ce que vous pouvez réaliser avec l'API REST de Jira :
- Automatiser la création de problèmes:Intégrez Jira à votre système de suivi des erreurs ou à votre outil de support client pour créer automatiquement des problèmes dans Jira lorsque certains événements se produisent, avec tous les détails pertinents.
- Synchroniser les données entre les systèmes: Gardez Jira synchronisé avec d'autres outils de votre pipeline de développement, tels que les systèmes de contrôle de source, les outils CI/CD ou les suites de gestion des tests. L'API vous permet de refléter les modifications apportées dans Jira sur d'autres systèmes et vice versa.
- Opérations en vrac:Vous devez mettre à jour un grand nombre de problèmes à la fois ? L'API REST prend en charge les opérations de création, de mise à jour et de suppression en masse, ce qui vous permet d'économiser d'innombrables heures de travail manuel.
- Tableaux de bord et rapports personnalisés:Récupérez des données de Jira et utilisez-les pour créer des tableaux de bord, des rapports ou des visualisations de données personnalisés adaptés aux besoins spécifiques de votre équipe.
- Étendez les fonctionnalités de Jira:Créez des applications et des intégrations personnalisées qui étendent les capacités de Jira, ajoutent de nouvelles fonctionnalités ou rationalisent les flux de travail spécifiques à votre organisation.
- Migrer les données:Vous passez d'un autre système de suivi des problèmes à Jira ? Utilisez l'API pour importer par programmation vos données existantes dans Jira.
- Sauvegarde et archivage:Configurez des scripts pour sauvegarder régulièrement vos données Jira ou archiver d'anciens projets et problèmes.
Ce ne sont là que quelques exemples : l'API REST de Jira fournit un ensemble complet de points de terminaison qui couvrent presque toutes les fonctionnalités et fonctions disponibles dans l'interface utilisateur de Jira. Si vous pouvez le faire dans Jira, il y a de fortes chances que vous puissiez le faire via l'API.
Différences clés entre l'API REST Jira Cloud et l'API REST Data Center
Bien que l'API REST Jira offre en grande partie les mêmes fonctionnalités sur Jira Cloud, Server et Data Center, il existe quelques différences clés à prendre en compte :
- Authentification:Jira Cloud utilise OAuth 2.0 ou des jetons API pour l'authentification, offrant ainsi une méthode sécurisée et normalisée pour accorder l'accès à l'API. Jira Data Center, quant à lui, utilise principalement l'authentification de base ou les cookies de session.
- Gestion des versions d'API: L'API REST Jira Cloud est versionnée (actuellement en version 3), ce qui permet à Atlassian de faire évoluer et d'améliorer l'API au fil du temps sans interrompre les intégrations existantes. Jira Data Center, cependant, ne dispose pas de versionnage explicite : l'API est liée à la version spécifique de Jira.
- Limitation du débit:Pour garantir une utilisation équitable et maintenir les performances, Jira Cloud applique des limites de débit plus strictes sur les requêtes API par rapport à Data Center. Les intégrations doivent être conçues en tenant compte de ces limites et mettre en œuvre une limitation et une gestion des erreurs appropriées.
- Format d'URLLes URL des points de terminaison de l'API REST diffèrent légèrement entre Cloud et Data Center. Pour Jira Cloud, l'URL de base est au format suivant : https://your-domain.atlassian.net/rest/api/3/, tandis que pour les centres de données, c'est https://your-jira-instance.com/rest/api/latest/.
Malgré ces différences, les concepts de base et les modèles d'utilisation de l'API REST restent en grande partie les mêmes d'un déploiement à l'autre. Les compétences et les connaissances acquises en travaillant avec une version de l'API seront facilement transférables à d'autres.
De quoi avez-vous besoin pour travailler avec l’API REST Jira ?
Pour démarrer avec l'API REST Jira, vous aurez besoin de :
- Une instance Jira:Il peut s'agir d'un site Jira Cloud ou d'une instance Jira Server ou Data Center auto-hébergée. Vous aurez besoin d'un accès administrateur pour configurer et gérer vos intégrations d'API.
- Identifiants d'authentification:Selon votre déploiement Jira, il peut s'agir d'un jeton OAuth 2.0, d'un jeton API ou d'informations d'identification d'authentification de base (nom d'utilisateur et mot de passe).
- Client API:Pour effectuer des requêtes HTTP vers l'API, vous aurez besoin d'un client API. Il peut s'agir d'un outil de test d'API dédié comme Postman, d'un outil de ligne de commande comme cURL ou de la bibliothèque HTTP dans le langage de programmation de votre choix (par exemple, la bibliothèque de requêtes de Python ou l'API fetch de JavaScript).
- Référence de la documentation de l'API Jira:Atlassian fournit une documentation complète sur l'API REST Jira, détaillant chaque point de terminaison, ses paramètres et des exemples de requêtes et de réponses. Gardez-la à portée de main lorsque vous explorez l'API.
Une fois ces éléments en place, vous êtes prêt à commencer à effectuer vos premières requêtes API.
Comment utiliser l'API REST de Jira
Examinons un exemple pratique d'utilisation de l'API REST Jira pour créer, récupérer, mettre à jour et rechercher des problèmes. Nous utiliserons Postman pour nos exemples, mais les principes s'appliquent à n'importe quel client API.
Étape 1 : créer un compte Jira Cloud
Si vous ne disposez pas encore d'une instance Jira avec laquelle travailler, le moyen le plus simple de commencer est de vous inscrire à une instance Jira Cloud gratuite sur https://www.atlassian.com/software/jiraUne fois votre site configuré, créez un nouveau projet avec lequel travailler.
Étape 2 : générer un jeton d'API Jira
Pour authentifier nos requêtes API, nous utiliserons un jeton API. Voici comment en générer un :
- Connectez-vous à votre compte Atlassian et accédez à https://id.atlassian.com/manage-profile/security/api-tokens.
- Cliquez sur « Créer un jeton API », donnez à votre jeton une étiquette descriptive et cliquez sur « Créer ».
- Copiez le jeton généré et stockez-le en toute sécurité. Vous ne pourrez plus le consulter après avoir quitté cette page.
Étape 3 : effectuez votre première requête API avec Postman
Commençons par récupérer les détails d’un problème existant :
- Ouvrez Postman et créez une nouvelle demande.
- Définissez la méthode HTTP sur GET et saisissez l'URL du point de terminaison des détails du problème, en remplaçant votre-domaine par le domaine de votre site Jira et ISSUE-KEY par la clé d'un problème de votre projet : https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
- Sous l'onglet « Autorisation », sélectionnez « Authentification de base » comme type. Saisissez l'adresse e-mail de votre compte Atlassian comme nom d'utilisateur et collez votre jeton API comme mot de passe.
- Cliquez sur « Envoyer ». Si tout est correctement configuré, vous devriez voir une réponse JSON avec tous les détails du problème spécifié, y compris ses champs, commentaires, pièces jointes, etc.
Étape 4 : Créer un problème
Créons maintenant un nouveau problème via l'API :
- Dans Postman, modifiez la méthode HTTP en POST et mettez à jour l'URL vers le point de terminaison de création de problème : https://your-domain.atlassian.net/rest/api/3/issue
- Sous l'onglet « En-têtes », ajoutez une nouvelle paire clé-valeur : « Content-Type » et « application/json ». Cela indique à Jira que nous envoyons une charge utile JSON.
Passez à l'onglet « Corps », sélectionnez le bouton radio « brut » et saisissez le JSON suivant, en remplaçant les valeurs project.key, issuetype.name, summary et description selon le cas :
json
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {
<span class="hljs-string">"key"</span>: <span class="hljs-string">"YOUR_PROJECT_KEY"</span>
},
<span class="hljs-string">"issuetype"</span>: {
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Task"</span>
},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue created via REST API"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"This is a test issue created using the Jira REST API."</span>
}
]
}
]
}
}
}
3. Cliquez sur « Envoyer ». Jira répondra avec un statut 201 Créé et les détails complets du problème nouvellement créé.
Étape 5 : Mettre à jour un problème
Pour mettre à jour un problème existant, nous utilisons la méthode PUT :
- Modifiez la méthode HTTP en PUT et mettez à jour l'URL pour qu'elle pointe vers le problème que vous souhaitez mettre à jour : https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
Dans le corps de la requête, incluez les champs que vous souhaitez mettre à jour, par exemple :
json
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Updated summary"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"This issue has been updated via the REST API."</span>
}
]
}
]
}
}
}
2. Cliquez sur « Envoyer ». Jira répondra avec un statut 204 Aucun contenu pour indiquer que la mise à jour a réussi.
Étape 6 : Rechercher des problèmes à l’aide de JQL
Les puissantes capacités de recherche de Jira sont également accessibles via l'API REST à l'aide de JQL (Jira Query Language) :
- Modifiez la méthode HTTP pour revenir à POST et mettez à jour l'URL vers le point de terminaison de recherche : https://your-domain.atlassian.net/rest/api/3/search
Dans le corps de la requête, incluez une requête JQL et tous les paramètres supplémentaires :
<span class="hljs-type">json</span>
<span class="hljs-keyword">Copy</span>
{
"jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
"fields": ["summary", "status", "assignee"],
"maxResults": <span class="hljs-number">10</span>
}
Cette requête renverra les 10 problèmes les plus récemment créés avec le statut « À faire » à partir du projet spécifié, y compris uniquement les champs de résumé, de statut et de responsable.
- Cliquez sur « Envoyer ». Jira répondra avec un tableau JSON de problèmes correspondant à vos critères de recherche.
Ces exemples ne sont qu'un aperçu de ce qu'il est possible de faire avec l'API REST de Jira. À mesure que vous vous familiariserez avec les points de terminaison et les paramètres disponibles, vous serez en mesure de créer des intégrations de plus en plus complexes et puissantes.
Vous pouvez automatiser Jira sans utiliser l'API sur Latenode
Comment automatiser la création et les mises à jour des problèmes dans Jira à l'aide de Latenode
L'une des applications les plus puissantes de l'API REST de Jira est l'automatisation de la création et de la mise à jour des tâches. Avec Latenode, vous pouvez configurer des workflows sophistiqués qui créent et mettent à jour automatiquement des tâches dans Jira en fonction de données provenant de sources externes ou de déclencheurs spécifiques. Cela garantit que les informations de votre système de gestion de projet restent à jour et opportunes, améliorant ainsi l'efficacité de l'équipe.
Par exemple, vous pouvez créer un workflow qui crée automatiquement une nouvelle tâche dans Jira lorsqu'un message d'erreur est reçu d'un système de surveillance, en remplissant tous les champs nécessaires et en attribuant la tâche au développeur approprié. Au fur et à mesure que les mises à jour arrivent, la tâche peut être automatiquement mise à jour et, une fois le problème résolu, elle peut être fermée. Cette approche simplifiée améliore non seulement le suivi des problèmes, mais fait également gagner du temps à votre équipe, lui permettant de se concentrer sur la résolution des problèmes plutôt que sur leur administration.
Vous pouvez en apprendre davantage sur ce script et l'intégration avec Latenode dans cet article. L'intégration avec Latenode offre quelques avantages clés :
- Simplicité d’utilisation Latenode simplifie le processus d'utilisation de l'API de Jira, permettant aux utilisateurs non techniques d'automatiser plus facilement les tâches de gestion de projet.
- Tarification flexible Les utilisateurs peuvent choisir entre différents plans Latenode, avec des coûts et des fonctionnalités variables, pour répondre au mieux à leurs besoins.
- Solutions complètes L'intégration de Latenode avec Jira donne accès à une large gamme de fonctionnalités de gestion de projet et de suivi des problèmes.
- Personnalisation Les utilisateurs peuvent personnaliser les intégrations Jira pour répondre à leurs besoins spécifiques, permettant ainsi des solutions d'automatisation sur mesure alignées sur les objectifs commerciaux.
Imaginez que chaque e-mail important d'un client se transforme automatiquement en tâche dans Jira. Avec Latenode, cela devient une réalité. Notre plateforme assure la création d'une nouvelle tâche dans le bon projet avec des champs renseignés en fonction du contenu de l'e-mail, garantissant qu'aucune demande importante ne soit manquée.
Voici un exemple de la manière dont un workflow Latenode automatise la création et les mises à jour de tâches Jira en fonction des données de courrier électronique entrantes provenant d'une source externe.
Cette image montrerait une représentation visuelle du flux de travail dans l'interface de Latenode, avec des nœuds connectés représentant chaque étape du processus, de la réception de l'e-mail à la création de la tâche Jira.
Ce n'est qu'un exemple de la façon dont Latenode peut transformer votre approche de l'utilisation de l'API Jira grâce à une automatisation puissante. En fait, les capacités de la plateforme sont pratiquement illimitées : vous pouvez créer tous les scénarios d'automatisation nécessaires pour améliorer l'efficacité de votre entreprise. Qu'il s'agisse de distribution automatique de tâches, d'envoi de notifications, de suivi des indicateurs de performance clés ou de toute autre tâche, Latenode fournit les outils pour leur donner vie.
En tirant parti du générateur de flux de travail visuel de Latenode et de l'intégration transparente avec l'API REST Jira, vous pouvez facilement concevoir et mettre en œuvre des scénarios d'automatisation complexes, augmentant ainsi l'efficacité de la gestion de projet et accélérant les flux de travail de votre équipe.
Si vous avez besoin d'aide ou de conseils pour créer votre propre script ou si vous souhaitez reproduire celui-ci, contactez notre communauté Discord, où se trouvent les experts en automatisation Low-code.
Pagination, extension et classement de l'API REST Jira
À mesure que vous commencez à travailler avec des ensembles de données plus volumineux dans Jira, vous devez savoir comment l'API REST gère la pagination, l'extension des ressources imbriquées et le classement des résultats.
Expansion
De nombreuses ressources Jira contiennent des références à d'autres ressources imbriquées. Par exemple, un ticket contient des références à son projet, son type de ticket, son créateur, son rapporteur, son responsable, ses commentaires, ses pièces jointes, etc. Par défaut, ces ressources imbriquées sont renvoyées sous forme de stubs, contenant uniquement quelques champs de base et un lien automatique vers la ressource complète.
Si vous avez besoin des détails complets d'une ressource imbriquée, vous pouvez utiliser le paramètre de requête expand pour demander à Jira d'inclure la ressource complète dans la réponse. Par exemple, pour inclure les détails complets du projet et du responsable d'un problème :
<span class="hljs-built_in">GET</span> <span class="hljs-built_in">..</span>./rest/api/3/issue/ISSUE-KEY?<span class="hljs-attribute">expand</span>=project,assignee
Vous pouvez étendre plusieurs ressources en les séparant par des virgules. Sachez que les extensions peuvent augmenter considérablement la taille de la charge utile de la réponse, alors utilisez-les judicieusement.
Pagination
Les requêtes susceptibles de renvoyer un grand nombre de résultats (comme les recherches JQL) sont paginées par défaut. L'API renverra un nombre maximal de résultats par page (par défaut 50, mais personnalisable jusqu'à 100) ainsi que des liens vers les pages suivantes et précédentes.
Vous pouvez contrôler la pagination à l'aide des paramètres startAt et maxResults :
- startAt : l'index du premier résultat à renvoyer (basé sur 0)
- maxResults : le nombre maximal de résultats à renvoyer par page
Par exemple, pour récupérer la deuxième page de résultats avec une taille de page de 20 :
<span class="hljs-built_in">GET</span> <span class="hljs-built_in">..</span>./rest/api/3/search?<span class="hljs-attribute">jql</span>=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20
Votre application devra gérer plusieurs requêtes pour récupérer toutes les pages de résultats.
Passation de commande
Vous pouvez contrôler l'ordre des résultats à l'aide du paramètre orderBy, qui accepte une liste de champs séparés par des virgules pour le tri. Chaque champ peut être préfixé par un - pour indiquer l'ordre décroissant.
Par exemple, pour classer les problèmes par date de création décroissante, puis par priorité croissante :
OBTENIR .../rest/api/3/search?jql=project=VOTRE_CLÉ_DE_PROJET&orderBy=-created,priority
Tous les champs ne prennent pas en charge la commande : reportez-vous à la documentation du point de terminaison spécifique pour voir ce qui est disponible.
Exemples d'utilisation de l'API Jira
Voici quelques exemples plus avancés démontrant la puissance de l’API REST Jira pour les opérations en masse.
Création/mise à jour en masse de problèmes à partir d'un fichier CSV
Supposons que vous ayez un fichier CSV contenant des données pour plusieurs tickets que vous souhaitez créer ou mettre à jour dans Jira. Vous pouvez utiliser un outil comme Postman pour automatiser ce processus :
- Dans Postman, créez une nouvelle demande pour le point de terminaison de création ou de mise à jour du problème.
Dans l'onglet Corps, sélectionnez le bouton radio « brut » et saisissez un modèle pour vos données de problème, en utilisant des variables pour les champs qui proviendront de votre CSV :
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"{{project_key}}"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{issue_type}}"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"{{summary}}"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"{{description}}"</span>
}
]
}
]
},
<span class="hljs-string">"assignee"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{assignee}}"</span>},
<span class="hljs-string">"priority"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"{{priority}}"</span>}
}
}
2. Passez à l'onglet « Script de pré-requête » et ajoutez du code pour lire votre fichier CSV et définir les variables correspondantes :
const csvFile = pm.iterationData.readCSV();
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'project_key'</span>, csvFile[0]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'issue_type'</span>, csvFile[1]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'summary'</span>, csvFile[2]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'description'</span>, csvFile[3]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'assignee'</span>, csvFile[4]);
pm.variables.<span class="hljs-built_in">set</span>(<span class="hljs-string">'priority'</span>, csvFile[5]);
3. Dans la fenêtre « Runner », sélectionnez votre fichier CSV comme fichier de données et démarrez l'exécution. Postman créera une nouvelle requête pour chaque ligne de votre fichier CSV, en remplaçant les variables du fichier.
Il s'agit d'une technique puissante pour importer en masse des données dans Jira à partir de sources externes.
Problèmes de création/mise à jour en masse à partir de JSON
Si vos données sources sont déjà au format JSON, vous pouvez utiliser le point de terminaison de création/mise à jour en masse pour traiter plusieurs problèmes dans une seule requête :
POSTEZ https://your-domain.atlassian.net/rest/api/3/issue/bulk
Le corps de la requête doit contenir un tableau d'objets de création/mise à jour de problème, chacun suivant le même format qu'une seule demande de création/mise à jour de problème :
{
<span class="hljs-string">"issueUpdates"</span>: [
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"PROJ1"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"Task"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue 1"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"First issue created via bulk update"</span>
}
]
}
]
}
}
},
{
<span class="hljs-string">"fields"</span>: {
<span class="hljs-string">"project"</span>: {<span class="hljs-string">"key"</span>: <span class="hljs-string">"PROJ2"</span>},
<span class="hljs-string">"issuetype"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"Bug"</span>},
<span class="hljs-string">"summary"</span>: <span class="hljs-string">"Issue 2"</span>,
<span class="hljs-string">"description"</span>: {
<span class="hljs-string">"type"</span>: <span class="hljs-string">"doc"</span>,
<span class="hljs-string">"version"</span>: <span class="hljs-number">1</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"paragraph"</span>,
<span class="hljs-string">"content"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"text"</span>,
<span class="hljs-string">"text"</span>: <span class="hljs-string">"Second issue created via bulk update"</span>
}
]
}
]
},
<span class="hljs-string">"priority"</span>: {<span class="hljs-string">"name"</span>: <span class="hljs-string">"High"</span>},
<span class="hljs-string">"labels"</span>: [<span class="hljs-string">"bulk-import"</span>, <span class="hljs-string">"api-test"</span>]
}
}
]
}
Cela créera deux problèmes dans une seule demande : une tâche dans le projet PROJ1 et un bogue dans le projet PROJ2. Vous pouvez inclure jusqu'à 50 problèmes dans une seule demande groupée.
Le point de terminaison en masse est également utile pour effectuer des transitions, des mises à jour et des suppressions en masse. Par exemple, pour faire passer plusieurs problèmes au statut « Terminé » :
{
"<span class="hljs-attribute">transition</span>": {
"id": <span class="hljs-string">"31"</span>
},
"issues": [
{"key": <span class="hljs-string">"ISSUE-1"</span>},
{"key": <span class="hljs-string">"ISSUE-2"</span>},
{"key": <span class="hljs-string">"ISSUE-3"</span>}
]
}
Cela suppose que « 31 » est l'ID de votre transition « Terminé » ; vous pouvez trouver les transitions disponibles pour un type de problème via le point de terminaison /rest/api/3/issue/{issueIdOrKey}/transitions.
Résumé
L'API REST de Jira est un outil extrêmement puissant pour intégrer Jira à d'autres systèmes, automatiser des tâches et étendre les capacités de Jira. Dans ce guide, nous avons abordé les principes fondamentaux de l'API, notamment :
- La différence entre les API Java et REST, et quand utiliser chacune d'elles
- Principales différences entre les API Cloud et Server/Data Center
- Comment s'authentifier auprès de l'API à l'aide de jetons API ou de l'authentification de base
- Effectuer vos premières requêtes API avec Postman
- Créer, récupérer, mettre à jour et rechercher des problèmes
- Gestion de la pagination, de l'expansion et du classement des résultats
- Cas d'utilisation avancés tels que la création/mise à jour en masse à partir de données CSV et JSON
Mais nous n'avons fait qu'effleurer la surface. L'API REST de Jira fournit des points de terminaison pour travailler avec presque tous les aspects de Jira, des projets et des tableaux aux utilisateurs et aux autorisations. Au fur et à mesure que vous créez vos intégrations, assurez-vous de vous référer à la documentation officielle d'Atlassian pour obtenir les informations les plus récentes et les plus complètes.
Avec l'API REST Jira dans votre boîte à outils, les possibilités de Jira sont quasiment infinies. Que vous souhaitiez créer un tableau de bord de reporting personnalisé, synchroniser des données avec un autre système ou automatiser des workflows complexes, l'API vous offre la flexibilité et la puissance dont vous avez besoin pour y parvenir.
Vous pouvez essayer Jira sans utiliser l'API sur Latenode
QFP
Quelles méthodes d’authentification sont prises en charge par l’API REST Jira ?
Jira Cloud prend en charge OAuth 2.0 et les jetons API pour l'authentification. Pour OAuth, vous devez enregistrer votre application dans la console développeur d'Atlassian pour obtenir un ID client et un secret. Les jetons API sont une option plus simple pour les scripts et les intégrations personnelles. Jira Server et Data Center prennent en charge l'authentification de base (nom d'utilisateur et mot de passe) et l'authentification basée sur la session à l'aide de cookies.
L'API REST Jira est-elle différente entre Jira Cloud et Jira Data Center ?
Bien que les principaux points de terminaison et fonctionnalités soient en grande partie les mêmes, il existe quelques différences clés :
- L'URL de base de l'API est différente - Cloud utilise https://your-domain.atlassian.net/rest/api/3/, tandis que Serveur/Centre de données utilise https://your-jira-instance.com/rest/api/latest/.
- Le cloud applique des limites de débit plus strictes et exige une authentification pour toutes les demandes, tandis que le serveur/centre de données a des valeurs par défaut plus indulgentes.
- Certaines fonctionnalités avancées, telles que les API Agile et Service Desk, présentent des différences dans les points de terminaison disponibles et les formats de demande/réponse entre Cloud et Server/Data Center.
Reportez-vous toujours à la documentation spécifique à votre déploiement Jira pour vous assurer que vous utilisez les URL et les paramètres corrects.
Comment gérer la limitation du débit des API ?
Jira Cloud applique des limites de débit pour garantir la stabilité et les performances du service. Si vous dépassez la limite de débit, vous recevrez une réponse 429 Too Many Requests.
Pour éviter d’atteindre les limites de débit :
- Mettez les données en cache lorsque cela est possible pour éviter de faire des demandes répétitives.
- Utilisez la pagination pour récupérer de grands ensembles de résultats sur plusieurs requêtes au lieu d'essayer de tout récupérer en même temps.
- Implémentez un backoff exponentiel dans votre code client pour augmenter progressivement le délai entre les tentatives lorsqu'une limite de débit est atteinte.
- Si vous avez un besoin légitime d'une limite de débit plus élevée, contactez le support Atlassian pour discuter de vos options.
Les déploiements de serveur et de centre de données ont la limitation de débit désactivée par défaut, mais les administrateurs peuvent choisir d'activer et de configurer des limites de débit si nécessaire.
Puis-je utiliser l'API REST Jira pour le serveur/centre de données ?
Oui, Jira Server et Data Center disposent d'une API REST qui est en grande partie similaire à l'API Jira Cloud. Les principales différences sont les suivantes :
- L'URL de base utilise /rest/api/latest/ au lieu de /rest/api/3/.
- Certains points de terminaison peuvent avoir des paramètres ou des formats de réponse légèrement différents.
- L'authentification s'effectue généralement via l'authentification de base ou des cookies de session plutôt que via des jetons OAuth ou API.
Reportez-vous à la documentation de l'API REST spécifique au serveur/centre de données pour obtenir les informations les plus précises pour votre version de Jira.
L'API REST de Jira est un moyen puissant et flexible d'intégrer Jira à votre flux de travail de développement. Que vous travailliez dans le cloud ou que vous gériez votre propre serveur, l'API fournit les outils dont vous avez besoin pour automatiser, personnaliser et étendre Jira afin de répondre aux besoins uniques de votre équipe. Avec un peu d'exploration et d'expérimentation, vous pourrez exploiter tout le potentiel de Jira et faire passer votre gestion de projet au niveau supérieur.
