Jira — jak używać: integracje

Jira API pozwala wymieniać dane między Jirą a innymi aplikacjami. Jira REST API służy do tej komunikacji przez żądania HTTP. Korzystanie z Jira API jest bezpłatne i nie wiąże się z dodatkową opłatą.¹
Ten artykuł wyjaśnia, jak uwierzytelniać żądania, pracować ze zgłoszeniami i rozpoznawać błędy. Plan Jira Cloud Free obejmuje maksymalnie 10 użytkowników; sam dostęp do REST API nie wymaga płatnego planu².

Czym jest Jira API i jakie daje możliwości?

Jira API pozwala odczytywać i zmieniać dane Jiry za pomocą żądań HTTP. Wśród obsługiwanych zasobów są issue, czyli zgłoszenie, oraz project, czyli projekt.
Żądanie można ograniczyć do potrzebnych danych, zamiast pobierać pełną odpowiedź³.

Resource expansion rozwija wskazane części odpowiedzi. Ich nazwy przekazuje się w parametrze expand Jira REST API.¹ Pagination, czyli stronicowanie, korzysta z parametru startAt, który wskazuje indeks pierwszego wyniku na stronie w Jira Cloud REST API.⁴
W Jira Data Center REST API parametr maxResults określa liczbę wyników na stronie.⁵ Domyślna wartość startAt to 0, więc stronicowanie zaczyna się od pierwszego wyniku⁶.

Wyniki można też sortować. Parametr orderBy=name ustawia w Jira Cloud REST API kolejność rosnącą według nazwy.⁴
Poniższa tabela pokazuje, którą częścią odpowiedzi steruje każdy z tych parametrów³.

Jak uwierzytelnić żądania w Jira API?

Metodę uwierzytelnienia żądania dobierz do instancji Jira i sposobu integracji. OAuth 2.0 (3LO) pozwala użytkownikowi udzielić aplikacji dostępu do konta. Uwierzytelnienie wskazuje konto lub aplikację, ale o dostępie do danych decydują uprawnienia konta.
Token dostępu uzyskany przez OAuth 2.0 (3LO) pozostaje ważny przez godzinę, czyli 3600 sekund⁷.

• Metoda uwierzytelnienia musi pasować do konfiguracji instancji Jira i klienta API.
• Żądanie HTTP musi zawierać dane uwierzytelniające w formacie wymaganym przez wybraną metodę.
• Uprawnienia konta muszą obejmować projekt i operację, której dotyczy żądanie.

Poprawne uwierzytelnienie nie daje dostępu do wszystkich danych. Żądanie nadal podlega uprawnieniom użytego konta³.

Jakie zasoby i endpointy udostępnia Jira API?

Jira API grupuje endpointy według zasobów i dostępnych na nich operacji. Endpoint jest adresem operacji, pod który klient wysyła żądanie.
Tabela przedstawia zasoby Jira Data Center REST API i przykładowe ścieżki^5,8.

Jira Cloud REST API pozwala pobierać wersje projektu, także w postaci stronicowanej.⁹ Udostępnia również liczbę zgłoszeń powiązanych z wersją oraz liczbę zgłoszeń nierozwiązanych.⁹
Pracę powiązaną z wersją można tworzyć, aktualizować i usuwać.⁹ Liczby zgłoszeń zwracają osobne endpointy: GET /rest/api/3/version/{id}/relatedIssueCounts oraz GET /rest/api/3/version/{id}/unresolvedIssueCount⁹.

Jakie wersje Jira API są dostępne?

Dokumentację Jira API wybierz odpowiednio do platformy: Jira Cloud albo Jira Data Center. Od tego zależy też wybór endpointu. Przywołana dokumentacja Jira Cloud platform REST API dotyczy wersji 2.⁴
Numer wersji API określa zestaw endpointów, a nie wersję projektu prowadzonego w Jirze. Dokumentacja Jira Cloud platform REST API obejmuje wersje 2 i 3 interfejsu⁴.

Jak pobierać, tworzyć i aktualizować zgłoszenia przez Jira API?

Praca ze zgłoszeniami przez Jira API zaczyna się od wyboru operacji i wskazania projektu lub zgłoszenia. Potem trzeba przekazać wymagane pola. JQL to język zapytań Jiry używany do wyszukiwania zgłoszeń przez Jira REST API.¹⁰
W Jira Data Center REST API można ograniczyć zwracane pola i uporządkować wyniki wyszukiwania.¹¹ Bez parametru maxResults wyszukiwanie JQL zwraca tam domyślnie do 50 zgłoszeń¹².

• Pobieranie zgłoszeń wymaga wskazania konkretnego zgłoszenia albo przygotowania zapytania JQL do wyszukania pasujących rekordów.
• Tworzenie zgłoszenia wymaga danych projektu, typu zgłoszenia i pól wymaganych przez jego konfigurację.
• Edycja zgłoszenia w Jira Data Center REST API pozwala zmienić wiele pól jednym żądaniem, w tym dodać komponent i usunąć inny.¹¹
• Komentarz do zgłoszenia można dodać w Jira Data Center REST API wraz z poziomem jego zabezpieczeń, używając jednego żądania.¹¹

Jira API pozwala wyszukiwać zgłoszenia, a następnie je tworzyć lub aktualizować. Dostępny zakres działań zależy od endpointu i uprawnień¹³.

Czym jest diagnostyka żądań i błędów Jira API?

Diagnostykę Jira API oprzyj na adresie zasobu, tożsamości użytkownika i odpowiedzi serwera. Jira Cloud REST API wskazuje wynik żądania standardowymi kodami statusu HTTP.⁴
Kod odczytuj razem z adresem żądania i tożsamością użytkownika. Tabela objaśnia klasy kodów¹⁴.

Jak sprawdzić dostęp do API i uprawnienia konta?

Dostęp do Jira API sprawdzisz, wysyłając żądanie do zasobu dostępnego dla danego konta i odczytując odpowiedź. Nagłówek X-AUSERNAME wskazuje nazwę uwierzytelnionego użytkownika albo wartość anonymous.⁵
Nagłówek pozwala ustalić, czy serwer potraktował żądanie jako zalogowane, czy anonimowe. W Jira Data Center GET /rest/api/2/myself zwraca 200 po poprawnym uwierzytelnieniu, a 401 bez uwierzytelnienia¹⁵.

• Tożsamość żądania ustal na podstawie nagłówka odpowiedzi, zanim ocenisz uprawnienia konta.
• Uprawnienie Jira sprawdź dla konkretnej operacji i zasobu wskazanego w żądaniu.
• Anonimowy dostęp do operacji Jira Cloud REST API działa tylko wtedy, gdy wymagane uprawnienie Jira ma grupa Public.⁴

Wynik sprawdzenia pozwala odróżnić problem z tożsamością żądania od braku dostępu do zasobu.
Udany odczyt własnego konta przez GET /rest/api/2/myself daje HTTP 200. Brak poprawnego uwierzytelnienia skutkuje HTTP 401¹⁵.

Co oznaczają kody błędów 401, 403, 404 i 429?

Kody błędów HTTP 401, 403, 404 i 429 wskazują odpowiednio problem z uwierzytelnieniem, odmowę dostępu, brak zasobu i ograniczenie liczby żądań. Kod interpretuj w kontekście adresu i operacji: możliwość odczytu zgłoszenia nie oznacza prawa do jego edycji.
Nagłówek Retry-After w odpowiedzi 429 podaje w sekundach czas oczekiwania przed ponowieniem żądania¹⁶.

Tabela łączy kody odpowiedzi Jira API z sygnalizowanym problemem i tym, co warto sprawdzić. HTTP 400 Bad Request oznacza błędne dane wejściowe – sprawdź wtedy pola żądania, a nie uwierzytelnienie¹³.

Tożsamość żądania ustal przed interpretacją kodu HTTP. Kod podpowie, czy sprawdzić uwierzytelnienie, uprawnienia, adres, czy tempo wywołań.
Odpowiedź HTTP 429 wymaga odczytania czasu oczekiwania z nagłówka Retry-After, który podaje go w sekundach¹⁶.

Pierwsze kroki: od tokenu do żądania w Jira API

Przed użyciem Jira API wskaż instancję i wybierz operację. Następnie przygotuj żądanie z odpowiednimi danymi uwierzytelniającymi. Tworzenie zgłoszenia wymaga określenia projektu, typu zgłoszenia i wymaganych pól.
Sposób przygotowania danych zależy od platformy: Jira Cloud albo Jira Data Center. Pomyślne utworzenie zgłoszenia przez POST /rest/api/3/issue potwierdza odpowiedź HTTP 201 Created¹³.

Jak korzystać z interfejsów API Jira?

Interfejsy API Jira pozwalają wywoływać operacje dotyczące wybranego zasobu. Najpierw określ cel, na przykład odczyt danych lub utworzenie zgłoszenia, a potem dobierz operację i metodę HTTP. Przygotuj wymagane dane wejściowe i odczytaj odpowiedź serwera.
Po pomyślnym usunięciu zgłoszenia Jira Cloud zwraca HTTP 204 No Content, czyli odpowiedź bez treści¹³.

• Instancja Jira określa środowisko, do którego wysyłasz żądanie.
• Operacja API wskazuje zasób, który odczytasz lub zmienisz.
• Odpowiedź API zawiera wynik żądania i dane zwrócone przez serwer.

W jednym żądaniu do Jira API spotykają się adres instancji, operacja, uwierzytelnienie i dane wejściowe.

Jak utworzyć zgłoszenie za pomocą API Jira?

Jira Data Center REST API pozwala utworzyć zgłoszenie, podając klucz projektu i nazwy pól. Można też użyć identyfikatorów projektu oraz typu zgłoszenia.¹¹
Przed wysłaniem żądania pobierz dostępne w API metadane projektów, typów zgłoszeń i pól potrzebnych do utworzenia zgłoszenia.¹¹

• Projekt i typ zgłoszenia wybierz z metadanych, a ich właściwe wartości umieść w danych żądania.
• Pola zgłoszenia wypełnij zgodnie z wymaganiami wybranego typu zgłoszenia.
• Podzadanie i czas pracy można uwzględnić przy tworzeniu zgłoszenia w Jira Data Center REST API: interfejs pozwala utworzyć podzadanie i dodać wpis czasu pracy.¹¹

Dane w żądaniu utworzenia zgłoszenia muszą odpowiadać konfiguracji wybranego projektu i typu zgłoszenia.

Jak wygenerować token API Jira?

Token API wygeneruj na koncie Atlassian, którego używasz do Jira Cloud. Token jest potrzebny do uwierzytelnienia skryptu lub innego procesu w Jira Cloud.¹
Po utworzeniu skopiuj go w bezpieczne miejsce. Przekaż go skryptowi jako dane uwierzytelniające, zamiast wpisywać bezpośrednio w kodzie.

Token API identyfikuje konto używane przez proces. Ogranicz więc dostęp do tokenu do osób i systemów, które wykonują żądania.

Jak przygotować pierwsze żądanie do API Jira?

Pierwsze żądanie do Jira Cloud API przygotuj jako operację odczytu. Wybierz adres zasobu i sposób przekazania danych uwierzytelniających. Przy opisanym użyciu Basic Auth nagłówek powstaje przez zakodowanie ciągu useremail:api_token w Base64.¹
Base64 koduje dane, ale ich nie szyfruje. Nie zapisuj tak przygotowanej wartości w publicznym kodzie.

• Adres żądania musi wskazywać właściwą instancję Jira Cloud i zasób przeznaczony do odczytu.
• Nagłówek uwierzytelniający musi zawierać wartość przygotowaną dla wybranej metody uwierzytelnienia.
• Odpowiedź serwera odczytaj razem z kodem HTTP, aby ustalić wynik żądania.

Pierwszy odczyt pozwala sprawdzić adres i uwierzytelnienie, zanim przygotujesz operację zapisującą dane.

Wywołania API ad hoc: pojedyncze żądania bez budowania integracji

Wywołanie Jira API ad hoc to ręcznie uruchomione żądanie, które sprawdza operację bez budowania stałej integracji. Możesz wysłać je za pomocą curl, narzędzia wiersza poleceń obsługującego żądania HTTP.
Tak odczytasz odpowiedź dla wybranego zasobu przed napisaniem skryptu. Możesz na przykład sprawdzić, czy GET /rest/api/2/myself zwraca HTTP 200 zamiast 401.

Żądanie ad hoc zawiera adres operacji, metodę HTTP i wymagane nagłówki. Jeśli operacja zapisuje dane, potrzebna jest także treść żądania.
O wyniku decyduje odpowiedź serwera, nie samo uruchomienie polecenia.

Wywołanie przez curl pomaga oddzielić problem z żądaniem od błędu w kodzie planowanej integracji. Ręczne polecenie sprawdza operację; powtarzalną wymianę danych między systemami prowadzi skrypt lub integracja.

Konto Jira Cloud i klient API: przygotowanie do pracy

Jira Cloud wymaga konta z dostępem do właściwej instancji. Klient API, czyli program wysyłający żądania, musi znać jej adres. Przykład integracji klienta Jira podaje 3 dane potrzebne do połączenia: nazwę użytkownika, hasło i adres instancji.¹⁷
To opis konkretnego klienta, a nie instrukcja przekazywania hasła w żądaniach do Jira Cloud.

Ten przykład klienta Jira obejmuje 5 czynności na zgłoszeniu: utworzenie, zmianę opisu, głosowanie, komentowanie i usunięcie.¹⁷
Przed użyciem klienta określ, które operacje ma wykonywać konto i do jakiego projektu potrzebuje dostępu.

Jak utworzyć konto Jira Cloud?

Konto Jira Cloud przygotuj, zakładając konto Atlassian i uzyskując dostęp do instancji Jira, w której będziesz pracować. Użyj adresu e-mail przeznaczonego do pracy z Jirą. Potem zaloguj się do właściwej instancji i sprawdź dostęp do projektu objętego żądaniami API.
Plan Jira Cloud Free obejmuje maksymalnie 10 użytkowników.

Dostęp do projektu jest potrzebny, by konto mogło wykonywać planowane operacje klienta API. Samo założenie konta nie daje uprawnień do każdego projektu.

Przygotowanie do pracy z Jira API kończy się ustaleniem adresu instancji oraz uprawnień konta do potrzebnych projektów i operacji.

Adresy URL Jira: jak wskazać instancję i zasób

Adres URL Jira API składa się z adresu instancji i ścieżki operacji na wybranym zasobie. Pierwsza część kieruje żądanie do właściwego środowiska, druga wskazuje dane, których dotyczy wywołanie.
Przykładowa ścieżka zasobu w Jira Data Center to /rest/api/2/.

Jira Cloud REST API stosuje różne struktury adresów dla aplikacji Connect i aplikacji korzystających z OAuth 2.0 (3LO).⁴
Przygotuj więc adres zgodnie ze sposobem, w jaki aplikacja uzyskuje dostęp do API.

Poprawny URL prowadzi do zamierzonej instancji i operacji, w strukturze adresu właściwej dla używanej aplikacji³.

Ceny i warunki sprawdzone u źródeł: październik 2026.