利用 python 查询操作 JIRA 中的 issues

Question

最近有个需求是获取某些符合条件的 jira 数据，在统计后使用 echarts 可视化度量出来。后端代码打算用 Python 实现。

问题解决

这里着重说下后台获取 jira 数据的代码。python 有一个非常好用的 jira 操作库 jira-python。 这里 有其非常友好的文档说明。下面权当是对文档的摘抄复述吧！

安装

如果 Python 环境中集成了 pip 的话，可以直接使用如下命令安装：

pip install jira

或者直接 下载 其离线包安装（注意，jira 包在安装的时候可能有其他依赖包。其他依赖包也需要安装) 这种安装比较麻烦，更推荐上面 pip 命令安装。

使用

我们知道 jira 里有相应的 project、project 下是对应的一些 issues (我是这样理解的，一个 jira 是一个 issue，issue 也分类，project 是同一类 issues 的统称。不知道这样说对不对。要想获取 jira 对应的 project 或者 issues，就得先建立一个 jira 的链接对象。即：

from jira import JIRA
# 即通过 jira 的主网址、一个 jira 网站的用户名和密码即可获取该 jira 网站的链接对象
test_jira = JIRA('https://jirahost.com.cn', basic_auth=('username', 'password'))

下面就可以调用它来查询 jira 对应的 projet 与 issues 了。

查询 projet

# 获取所有的 projets
projects = test_jira.projects()
# 获取指定的 project, JRA
test_proj = test_jira.project('JRA')

查询 issues

获取或查询指定条件的 issues 一般是用的最多也是最常用的。一般我们需要获取到 issue，并对 issue 的数据进行统计度量。这里主要用到了这个包的search_issues()方法（该方法返回的是一个列表，里面都是符合对应条件的 issue 对象)，这个方法的参数是 jira 的JQL语句。JQL语句是一种用来查询 jira 数据的查询语句，类似于数据库的 sql 语句（例如 mySQL 的查询语句），但它不是数据库查询语句。 jira 官网文档 有更加详尽的说明。比如要查询名为“TEST”的 project 的 issues，则其 JQL 语句为：

project = "TEST"

要查询指派人为“小明”，并且 project 名为“TEST”的 issues，则其 JQL 语句为：

project = "TEST" AND assignee = "小明"

上面两句对应的 Python 代码分别为：

search_str = 'project = "TEST"'
issues = test_jira.search_issues(search_str)

search_str = 'project = "TEST" AND assignee = "小明"'
issues = test_jira.search_issues(search_str)

可以看到，要获取指定的 jira 或 issues，只要写好对应的 JQL 语句即可。关于 JQL 的关键字的用法说明 jira 官网文档 都有。可以把符合条件的 JQL 语句写好，然后在自己或公司搭建的 JIRA 网站（即在首页导航栏的Issues--->Search for issues）中调试，如果可行，再放入代码中运行。
需要注意的是search_issues() 默认查询的 issues 最多为 50 个。如果你查询的 jira 或 issues 数量超过 50 个，则需要添加maxResults参数来指定更大的值。例如获取 project 名为“TEST”的 issues 有 100 个，则 Python 中的代码为：

# 指定获取的 issues 总数最多 10000 个
search_str = 'project = "TEST"'
issues = test_jira.search_issues(search_str, maxResults=10000)

获取到指定条件的 issue 列表，我们就可以用它来得到对应 issue 的详细信息了，比如最简单的我们想获取每个 issue 的名字，即：

search_str = 'project = "TEST" AND assignee = "小明"'
# 得到 issue 的列表
issues = test_jira.search_issues(search_str)
# 获取 issue 的名字
name_list = [issue.key for issue in issues]

若是获取到对应的 issue 列表后，想获取 issue 的某一个信息，但我们又不知道其对应的是 issue 的哪个字段（有时候我们会给 jira 自定义某些字段），我们可以将获取到的 issues 转为 ison 数据，通过查看 json 数据，从而找到对应的字段。即：

import json
search_str = 'project = "PROJ" AND Created="2019-3-18 8:12"'
# 用于 json_result=True 来返回对应的字典。
issue = test_jira.search_issues(search_str, json_result=True)
写入到 json 文件中
issue = json.dumps(issue, ensure_ascii=False)
with open('jira.json', 'w', encoding='utf-8') as f:
    f.write(issue)
    f.close()

之后将该 json 文件中的数据进行 代码格式化 ，找到自己想要的字段，进行后续的 jira 数据查询操作。

删除、更新 issues

方便起见，下面已将一些常用的功能进行了封装，代码如下：

from jira import JIRA, JIRAError

server = JIRA(server='https://jirahost.com.cn',
              basic_auth=('username', 'password'))


# 查询 issues
def search_issue(jql: str) -> list:
    """
    查询 jira
    :param jql:
    :return:
    """
    issue_key_list = []
    try:
        issues = server.search_issues(jql, maxResults=10000)
        if len(issues) > 0:
            issue_key_list = [issue.key for issue in issues]
    except JIRAError as e:
        print(f'search issue failed: {e}')
    finally:
        return issue_key_list


# 验收 issues.只有当 issue 的状态为待验收或验收中时才会验收
def close_jira(issue_key):
    """
    :param issue_key:
    :return:
    """
    status_list = ['待验收', '验收中']
    closed = False
    try:
        issue = server.issue(issue_key)
        issue_status = issue.fields.status.name
        if issue_status == '完成':
            return True

        if issue_status not in status_list:
            return False

        transitions = server.transitions(issue)
        # print(transitions)
        issue_id = transitions[0]['id']
        # print(issue_id)
        server.transition_issue(issue, issue_id)
        # 如果为待验收则递归一次
        if issue_status == '待验收':
            close_jira(issue_key)
        closed = True
    except JIRAError as e:
        print(f'close issue failed: {e}')
    finally:
        return closed


# 创建 issue
def create_issue(issue_dict: dict):
    """
    创建一个 issue,并返回其 key
    :param issue_dict:
    :return: issue_key
    """
    issue_key = ''
    try:
        issue = server.create_issue(fields=issue_dict)
        issue_key = issue.key
    except JIRAError as e:
        print(f'create issue failed：{e}')
    finally:
        return issue_key


# 更新 issue 指派人
def modify_jira_assignee(issue_key: str, modify_usr: str):
    try:
        issue = server.issue(issue_key)
        issue.update(assignee=modify_usr)
    except JIRAError as e:
        print(e)


# 删除 issue
def delete_jira(issue_key: str):
    try:
        issue = server.issue(issue_key)
        issue.delete()
    except JIRAError as e:
        print(e)

# 更改 issue 的截至日期
def modify_jira_duration(issue_key: str, duration: str):
    try:
        issue = server.issue(issue_key)
        issue.update(duedate=duration)
    except JIRAError as e:
        print(e)