В этом посте мы рассмотрим Jira Rest API. Мы объясним, как вы можете использовать Jira API для создания пользовательского отчета о времени. Кроме того, это хороший повод для написания кода на Python.
Вступление
В настоящее время многие компании используют Jira для поддержки своих процессов Scrum или Kanban. Могут быть установлены дополнения для расширения функциональности Jira. Некоторые из них бесплатны, другие необходимо приобрести. Jira доступна в двух версиях: облачная и серверная (локальная). Количество надстроек для Jira Cloud очень ограничено и предназначено для небольших групп. Jira Server имеет гораздо больше надстроек и предназначено для крупных организаций.
Количество надстроек и то, хотите ли вы сами нести ответственность за техническое обслуживание, могут быть решающими факторами для выбора версии. Однако обе версии также поддерживают API. Это довольно расширенный API и дает вам возможность писать свои собственные скрипты, расширяющие функциональность Jira. Например, вы можете создать интерфейс между вашей системой управления службами и Jira для передачи билетов от поддержки 1-й линии (работа с системой Service Management) к поддержке 2-й линии (работа с Jira).
Достаточно для этого введения, давайте начнем использовать API! Мы разработаем скрипт Python, который будет генерировать пользовательский отчет о времени для конкретного проекта Jira. Мы используем Python 3.7.5 и версию 2 Jira API. Источники можно найти на GitHub .
Вы также можете быть заинтересованы в: Является ли JIRA контрпродуктивным программным обеспечением для управления проектами на современном рынке?
Создать учетную запись Jira Cloud
Прежде всего, нам понадобится работающий экземпляр Jira, чтобы выполнить некоторые интеграционные тесты. Перейдите на сайт Jira и перейдите к нижней части страницы. Мы выбираем бесплатный план Jira Cloud.
На следующем шаге вам необходимо создать учетную запись и выбрать имя сайта. Мы выбираем mydeveloperplanet.atlassian.netназвание сайта.
Последнее, что нужно сделать, это создать доску Scrum, и тогда мы все готовы к работе. Нам потребовалось менее 5 минут, чтобы начать работу с Jira Cloud.
Создайте несколько пользовательских историй с подзадачами, запустите спринт и запишите некоторые работы в подзадачи. Мы также можем использовать Jira API для этого, но это может быть что-то для другого поста.
Jira API
Поскольку мы используем Jira Cloud, нам нужно сначала создать токен API. Нажмите на свой аватар в левом нижнем углу и выберите «Настройки аккаунта».
Перейдите на вкладку Безопасность и создайте токен API.
Теперь давайте взглянем на документацию Jira Rest API: https://developer.atlassian.com/cloud/jira/platform/rest/v2/
API хорошо документирован и содержит примеры того, как вызывать API с помощью curl, Node.js, Java, Python и PHP. Ожидаемый ответ на запрос также предоставляется. Итак, вся документация доступна, основная задача — выяснить, какие запросы вам нужны для вашего приложения.
Помните, что для Jira Server API также доступна документация . Он содержит менее четкую информацию, чем облачная версия. Перед написанием скрипта, который должен поддерживать обе версии, проверьте, идентичен ли вызов API, и по возможности используйте документацию Cloud.
Обратите внимание, что также можно использовать библиотеку Python Jira , но мы предпочли поговорить с Jira API напрямую. Таким образом, мы независимы от сторонней библиотеки.
Отчет о времени Джира
Требования к отчету о времени Jira, который мы хотим создать, следующие:
- Отчет должен содержать все зарегистрированные работы для пользователя в течение определенного периода времени для конкретного проекта Jira.
- Отчет должен быть отсортирован по пользователю, дню и проблеме
Чтобы получить рабочие журналы проблемы Jira, нам нужно вызвать запрос Получить выпуск рабочих журналов . Для этого запроса требуется идентификатор проблемы или ключ. Поэтому сначала нам нужно найти проблемы, которые содержат рабочие журналы в течение указанного периода времени. Мы можем использовать Поиск проблем, используя для этого JQL- запрос. Это даст нам возможность использовать язык запросов Jira (JQL), так же как мы можем использовать его для поиска проблем в самой Jira. Мы используем следующий запрос:
питон
xxxxxxxxxx
1
query = {
2
'jql': 'project = "' + args.project + '" and timeSpent is not null and worklogDate >= "' + args.from_date +
3
'"' + ' and worklogDate < "' + convert_to_date(args).strftime("%Y-%m-%d") + '"',
4
'fields': 'id,key',
5
'startAt': str(start_at)
6
}
В jqlпроверяет проект Jira, есть ли время , проведенное по этому вопросу, и в конце концов, он существует проверяет , является ли работа журналы в течение определенного периода времени. Проект Jira и дата, в которой нужно искать, указываются в качестве аргументов при запуске приложения. from_dateБудет иметь время 00:00:00. convert_to_dateДобавит один день к to_dateаргументу во время 00:00:00. Если нет to_date, то по умолчанию будет завтра 00:00:00.
fieldsУказать , какие поля мы хотим получить. Если не предоставлено, возвращаются все поля, но нас интересуют только idи key. start_atПараметр будет указывать , из которого записи на что мы хотим получить результаты. Результаты разбиты на страницы (максимум 50 результатов), поэтому нам нужно будет что-то сделать, чтобы запросить другие страницы.
Мы вызываем запрос Jira с помощью вышеуказанного запроса и загружаем часть JSON в response_json. Помните, что используется разбиение на страницы, поэтому мы добавляем в список результаты простых проблем JSON, которые будут содержать все проблемы в строке 3. Мы сознательно не преобразовывали выходные данные JSON в объекты, потому что нам нужны только операторы idand key. Мы всегда можем сделать это позже, если захотим.
питон
xxxxxxxxxx
1
response = get_request(args, "/rest/api/2/search", query)
2
response_json = json.loads(response.text)
3
issues_json.extend(response_json['issues'])
Поддержка нумерации страниц сделана в следующей части. Ответ JSON содержит общее количество проблем, возвращаемых запросом, и максимальное количество результатов, возвращаемых запросом. Мы читаем эти поля из ответа и затем проверяем, должен ли запрос вызываться снова с новым start_atпараметром. Этот код и приведенный выше код являются частью бесконечного цикла while. Мы вырываемся из цикла, когда обрабатываем все результаты поиска в строке 7.
питон
xxxxxxxxxx
1
total_number_of_issues = int(response_json['total'])
2
max_results = int(response_json['maxResults'])
3
max_number_of_issues_processed = start_at + max_results
4
if max_number_of_issues_processed < total_number_of_issues:
5
start_at = max_number_of_issues_processed
6
else:
7
break
Получение рабочих журналов работает примерно так же. Мы извлекаем рабочие журналы проблемы, а затем обрабатываем только рабочие журналы, которые попадают в указанный период времени. Рабочие журналы преобразуются в WorkLogобъекты.
питон
xxxxxxxxxx
1
class WorkLog:
2
def __init__(self, issue_key, started, time_spent, author):
3
self.issue_key = issue_key
4
self.started = started
5
self.time_spent = time_spent
6
self.author = author
Осталось только отсортировать список рабочих журналов. Мы используем sortedдля этого и с помощью attrgetter, мы получаем желаемую сортировку.
питон
xxxxxxxxxx
1
sorted_on_issue = sorted(work_logs, key=attrgetter('author', 'started', 'issue_key'))
И последнее, но не менее важное: sorted_on_issueсписок используется для форматирования рабочих журналов в выбранный формат вывода: либо вывод на консоль, либо файл CSV, либо файл Excel. Для последнего мы использовали библиотеку Python xlsxwriter .
питон
xxxxxxxxxx
1
def output_to_excel(work_logs):
2
try:
3
workbook = xlsxwriter.Workbook(EXCEL_FILE_NAME)
4
worksheet = workbook.add_worksheet()
5
row = 0
6
7
for work_log in work_logs:
8
worksheet.write(row, 0, work_log.author)
9
worksheet.write(row, 1, work_log.started.strftime('%Y-%m-%d'))
10
worksheet.write(row, 2, work_log.issue_key)
11
worksheet.write(row, 3, str(timedelta(seconds=work_log.time_spent)))
12
13
row += 1
14
finally:
15
workbook.close()
Заключение
Мы исследовали Jira API, чтобы сгенерировать отчет о времени для каждого пользователя за определенный период времени для конкретного проекта Jira. API хорошо документирован и довольно прост в использовании. При поиске информации об API Jira Rest вы будете использовать версию 3 API. Помните, что эта версия в настоящее время находится в бета-версии. Не стесняйтесь использовать генератор отчетов о времени Jira и запрашивать любые новые функции.