最近要研究zabbix配合jira创建一些工单，方便对一些问题进行跟进和记录。
jira API在5.0开始启用，然后搜了下，有相关的API模块，因为依赖关系要下一些被屏蔽的地址上的包，国内如果需要装这个包需要×××，或者相关包下载下来本地setup。
下面为jira-python的一些翻译，会不定时的更新。有建议请留言，谢谢。
呈现出来的文档满足基本用法是足够了，如果需要后边更详细的一些操作，请访问我的博客地址，http://www.messfeel.com/?p=42 后面的翻译有点多，这里找不到传附件的地址。。
欢迎查看jira-python的文档！
这个文档详细描述了jira-python 0.21版本的，他是一个python的库，可以让你更简单的使用JIRA REST API 。同样支持一些基本的GreenHopper 的REST API 。
源代码地址：https://bitbucket.org/bspeakmon/jira-python.
更新日志
Version 0.13 – April 10, 2013
This is the first release driven by the community andfueled by its contributions. Many thanks to Markus Wiik, Sorin Sbarnea, MattDoar, Doug Johnston, Greg Warner, Mark Egan-Fuller, Diogo Campos, and RandallHunt for the feature work and bug-squishing that made such a terrific releasepossible!（俗称，来源，感谢语。）
·.将Requests 1.0引入，包括支持OAuth。
·支持基本的GreenHopper REST API.
·弃用python-magic，加入imghdr, mimetypes
·Addedoptional filename parameter to add_p_w_upload
·Addedability to pass a verify parameter to the requests session.
·search_issues and dashboards now returna ResultList which includes some search metadata.（查找issue 和dashboard，现在会返回一个结果列表）
·各种错误的修正 (issues #5, #7, #8 and #11)
Version 0.12 – August 6, 2012
·Reworkedcontent-type usage to play nice with OAuth in JIRA 5.1.
·Madeinterpretation and display of error messages more meaningful.
·Implementeda config file for JIRA Shell.
·Update toRequests 0.13.6 and IPython 0.13.
Known issues: 使用OAuth授权时，创建不了项目和用户头像。
安装
最简单的安装jira-python的方法是通过pip：
$ pip install jira
如果你要运行客户端的独立，我们强烈建议您使用的virtualenv，安装方法如下：
$ pip -E jira_python install jira
$ workon jira_python
这样做可以创建一个私有的Python“安装”，你可以自由升级，降级或中断，不会把你的系统的相关组件处于危险中。
源代码包（支持PyPI）：http://pypi.python.org/pypi/jira-python/
依赖关系
Python
Python的2.7和Python3.x的都支持。
Requests请求
python-requests使用HTTP处理相关请求，通常情况下发布的版本必须依赖最新版本，写文档时，该版本是1.2.0，但任何>=1.0.0的版本应该都行。
requests-oauthlib
使用OAuth，写这篇文章时最新版本为0.3.3。.
IPython
IPython增强了Python解释器关于issue的一些使用问题，写这篇文章的时候，版本是0.13.
filemagic
该库自动检测一些内容的类型，如上传图片等。他在系统上工作仅仅提供libmagic，Mac和Unix基本上都会预装这个库，但是windows 一般用Cygwin 或者compile 来处理，你如果你的系统没有它，你必须手动指定他的内容格式，例如项目和用户的创建。
tlslite
这是一个TLS实现，处理密钥签名。它是用来帮助实现OAuth的握手。
PyCrypto
这是需要使用的OAuth的RSA-SHA1。请注意，它不是自动安装，因为它是在Windows中一个相当繁琐的过程。在Linux和OS X， pip install pycrypto安装pycrypto应该这样做。
安装时注意依赖关系
Examples
这里是一个简单的使用例子
#这个脚本展示了如何使用匿名模式, 针对 jira.atlassian.com.
from jira.client import JIRA
#默认情况下，客户端从Atlassian的插件SDK中启用了实例去连接JIRA
# (查看https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDKfor details).
# 来查看其默认参数.
options = {
'server': 'https://jira.atlassian.com'
}
jira = JIRA(options)
# 获取所有的匿名用户可查看的项目。
projects = jira.projects()
# 排序可用的项目键，然后返回第二个，第三个和第四个键。
keys =sorted([project.keyfor project in projects])[2:5]
# 获取一个issue
issue = jira.issue('JRA-1330')
#从这个issue上获取所有By Atlassians 的评论。
import re
atl_comments = [comment forcomment in issue.fields.comment.comments
if re.search(r'@atlassian.com$', comment.author.emailAddress)]
# 在issue上增加一个评论.
jira.add_comment(issue, 'Comment text')
# 改变 issue 的 summary(摘要) and description(描述).
issue.update(summary="I'mdifferent!", description='Changed the summary to be different.')
#你可以像这样更新整个标签，
issue.update(labels=['AAA', 'BBB'])
#或修改现有标签的列表。新的标签是unicode的，不带空格
issue.fields.labels.append(u'new_text')
issue.update(fields={"labels": issue.fields.labels})
# Send the issue away for good.（关闭issue：不太确定）
issue.delete()
另外一个例子展示如何使用你的用户，密码验证登陆jira:
#这个脚本展示了如何使用账号密码通过HTTP BASIC 认证方式连接JIRA。
from jira.client import JIRA
# 默认情况下，客户端从Atlassian的插件SDK中启用了实例去连接JIRA。
# 查看https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDKfor details.
jira = JIRA(basic_auth=('admin', 'admin')) # 一个账号/密码的元祖
#获取此服务器的可变的应用性能（需要JIRA系统管理员用户的权限）
props = jira.application_properties()
# 找出所有关于admin的issue的报告（代理人或者是开发者是admin）
issues = jira.search_issues('assignee=admin')
# 找出前三个（报告人是）admin的issue
from collections import Counter
top_three = Counter([issue.fields.project.keyfor issue in issues]).most_common(3)
这个例子展示如何使用GreenHopper（JIRA的插件）去工作:
# 这个脚本展示了如何使用客户端通过匿名模式(针对jira.atlassian.com这个网站)
from six import print_ as print
from jira.client import GreenHopper
#默认情况下，客户端从Atlassian的插件SDK中启用了实例去连接JIRA。
# (访问https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDKfor details).
# 来查看相关的参数.
options = {
'server': 'https://jira.atlassian.com'
}
gh = GreenHopper(options)
# 获取所有匿名用户可见的版图。
boards = gh.boards()
# 在一个（sprint）具体的版面中查看信息
board_id = 441
print("GreenHopper board: %s(%s)" % (boards[0].name, board_id))
sprints = gh.sprints(board_id)
# 在每个sprint 列出不完整的issue
for sprint in sprints:
sprint_id = sprint.id
print("Sprint: %s" % sprint.name)
incompleted_issues = gh.incompleted_issues(board_id, sprint_id)
print("Incomplete issues: %s" % ', '.join(issue.key for issuein incompleted_issues))
Quickstart（快速入门）
Initialization（初始化）
所有操作通过JIRA的对象，所以做一个：
from jira.client import JIRA
jira = JIRA()
这个链接通过http://localhost:2990/jira 这个地址链接到JIRA,他将使用从Atlassian插件中的SDK启用实例链接上面的地址。
你可以手动指定这个JIRA的地址:
jac = JIRA(options={'server': 'https://jira.atlassian.com'})
Authentication（认证）
在初始化的时候，jira-python模块能够创建一个HTTP BASIC或者使用OAuth 1.0a 去取得一个令牌用于认证。这个会话将会应用到所有关于JIRA对象的连接。
HTTP BASIC
传递一个参数：元祖(用户,密码) 给basic_auth （构造函数）
authed_jira = JIRA(basic_auth=('username', 'password'))
OAuth
传递一个参数（字典）给oauth
# 所有的值都是样品，不会在你的代码工作！
key_cert_data=None
with open(key_cert, 'r') as key_cert_file:
key_cert_data= key_cert_file.read()
oauth_dict = {
'access_token': 'd87f3hajglkjh89a97f8',
'access_token_secret': 'a9f8ag0ehaljkhgeds90',
'consumer_key': 'jira-oauth-consumer',
'key_cert': key_cert_data
}
authed_jira = JIRA(oauth=oauth_dict)
Note
OAuth 使用的前提：令牌必须通过授权、必须通过OAuth的dance。在交互使用中，如果你没有有效的令牌，jirashell可以帮助你
Note
OAuth在jira中使用RSA-SHA1（依赖PyCrypto库），PyCrypto没有默认安装，详情请见依赖关系章节。
·访问令牌和令牌密钥相对于用户具有唯一性。
·Consumerkey 必须与JIRA服务器上OAuth的配置相匹配。
·密钥证书的数据必须是在JIRA服务器的OAuth提供者配置的公钥匹配的私钥。
查看https://confluence.atlassian.com/display/JIRA/Configuring+OAuth+Authentication+for+an+Application+Linkfor details on configuring an OAuth provider for JIRA（了解更多）.
Issues
你可以通过JIRA的对象（标号）拿到相应的issue:
issue = jira.issue('JRA-1330')
Issue的JSON 将自动封装到issue的对象中，方便你直接访问信息：
summary = issue.fields.summary# '字段级安全权限'
votes = issue.fields.votes.votes # 440 (at least)
如果你只想要几个特定的信息，为了节省时间，你可以声明它们：
issue = jira.issue('JRA-1330', fields='summary,comment')
重新分配的问题：
# issue分配相关的权限，（这个不同于编辑权限）。
jira.assign_issue(issue, 'newassignee')
创建issue很简单:
new_issue = jira.create_issue(project={'key': 'PROJ'}, summary='New issue from jira-python',
description='Look into this one', issuetype={'name': 'Bug'})
或者使用字典创建它们：
issue_dict= {
'project': {'key': 'PROJ'},
'summary': 'New issue from jira-python',
'description': 'Look into this one',
'issuetype': {'name': 'Bug'},
}
new_issue = jira.create_issue(fields=issue_dict)
Note
Project（项目）, summary（摘要）, description（描述） and issue type这几个在创建issue总是必须的。如果你创建issue需要设置其他的一些信息; 查看jira.createmeta方法获取相关信息。
同样，你可以通过相关参数更新issue的信息：
issue.update(summary='new summary', description='A new summary was added')
issue.update(assignee={'name': 'new_user'}) # 重新分配更新问题所需要的编辑权限
或者使用字典来操作：
issue.update(fields={'summary': 'new summary', 'description': 'A new summarywas added'})
如果你完成了创建issue，你可以通过下面来让他写入硬盘（保存、退出）
issue.delete()
Searching
利用JQL来快速找到你想要的issues：
issues_in_proj = jira.search_issues('project=PROJ')
all_proj_issues_but_mine=jira.search_issues('project=PROJ andassignee != currentUser()')
# 我应该在本周完成的5个issue（优先级排序）
oh_crap = jira.search_issues('assignee = currentUser() and due < endOfWeek() orderby priority desc', maxResults=5)
# Summaries of my last 3 reported issues 我的最后三个issue报告的总结
print [issue.fields.summary for issue in jira.search_issues('reporter =currentUser() order by created desc', maxResults=3)]
Comments评论
评论，像issue一样，都是对象。可以通过父issue的对象或者JIRA对象的专用方法获得：
comments_a = issue.fields.comments.comments
comments_b = jira.comments(issue) # comments_b ==comments_a
如果你知道issueID,可以获取个别评论：
comment = jira.comment('JRA-1330', '10234')
添加、编辑、删除评论同样也是随意的：
comment = jira.add_comment('JRA-1330', 'new comment') # no Issue object required
comment = jira.add_comment(issue, 'new comment', visibility={'type': 'role', 'value': 'Administrators'}) # foradmins only
comment.update('updated commentbody')
comment.delete()
Transitions（切换问题处理用户）
了解一个issue是否可以切换：
issue = jira.issue('PROJ-1')
transitions = jira.transitions(issue)
[(t['id'], t['name']) fortintransitions] # [(u'5', u'Resolve Issue'), (u'2', u'Close Issue')]
Note
仅适用于当前已经验证的用户的切换！。
对一个问题进行切换:
# 解决这个问题之后再将其付给下一个用户进行相关操作
jira.transition_issue(issue, '5',assignee={'name': 'pm_user'}, resolution={'id': '3'})
# The above line is equivalent to相当于上边的行(dic的方式):
jira.transition_issue(issue, '5', fields: {'assignee':{'name':'pm_user'}, 'resolution':{'id': '3'}})
Projects
项目也是对象。。:
projects = jira.projects()
Also, just like issue objects, project objects areaugmented with their fields:
像issue的对象一样，project的对象也会增强他们的内容：（tag）
jra = jira.project('JRA')
print jra.name #'JIRA'
print jira.lead.displayName # 'Paul Slade [Atlassian]'
如果你有权限，你可以获取组件、版本以及任何一角色的信息:
components = jira.project_components(jra)
[c.name for c incomponents] # 'Accessibility', 'Activity Stream', 'Administration',etc.
jira.project_roles(jra) # 'Administrators', 'Developers', etc.
versions = jira.project_versions(jra)
[v.name for v inreversed(versions)] # '5.1.1', '5.1', '5.0.7', '5.0.6', etc.
jirashell
这里没有太多的演示。如果要真正了解一个服务，就必须探索他，使用它。试验和解决错误，一个REST的设计特别适合积极的探索。
在命令行运行它:
$ jirashell -s http://jira.atlassian.com
*** JIRA shell active; client is in 'jira'.Press Ctrl-D to exit.
In [1]:
这是一个专门的Python翻译（建立在ipython基础上），让你了解JIRA服务。它接受任何合法的python代码，。Shell构建了一个客户端（在接受参数的基础上），并且将其存储在jira对象中。
尝试获得issue:
In [1]: issue = jira.issue('JRA-1330')
issue包含的方法可以通过tab键获得：如下：
In [2]: issue.
issue.delete issue.fields issue.id issue.raw issue.update
issue.expand issue.find issue.key issue.self
In [2]: issue.fields.
issue.fields.aggregateprogress issue.fields.customfield_11531
issue.fields.aggregatetimeestimate issue.fields.customfield_11631
issue.fields.aggregatetimeoriginalestimate issue.fields.customfield_11930
issue.fields.aggregatetimespent issue.fields.customfield_12130
issue.fields.assignee issue.fields.customfield_12131
issue.fields.p_w_upload issue.fields.description
issue.fields.comment issue.fields.environment
issue.fields.components issue.fields.fixVersions
issue.fields.created issue.fields.issuelinks
issue.fields.customfield_10150 issue.fields.issuetype
issue.fields.customfield_10160 issue.fields.labels
issue.fields.customfield_10161 issue.fields.mro
issue.fields.customfield_10180 issue.fields.progress
issue.fields.customfield_10230 issue.fields.project
issue.fields.customfield_10575 issue.fields.reporter
issue.fields.customfield_10610 issue.fields.resolution
issue.fields.customfield_10650 issue.fields.resolutiondate
issue.fields.customfield_10651 issue.fields.status
issue.fields.customfield_10680 issue.fields.subtasks
issue.fields.customfield_10723 issue.fields.summary
issue.fields.customfield_11130 issue.fields.timeestimate
issue.fields.customfield_11230 issue.fields.timeoriginalestimate
issue.fields.customfield_11431 issue.fields.timespent
issue.fields.customfield_11433 issue.fields.updated
issue.fields.customfield_11434 issue.fields.versions
issue.fields.customfield_11435 issue.fields.votes
issue.fields.customfield_11436 issue.fields.watches
issue.fields.customfield_11437 issue.fields.workratio
Advanced（高级）
Resource Objects and Properties（对象and属性的资源）
资源和属性：JIRA REST的API之间的区别库。
资源实际上指的是服务器当前的REST实体的状态，例如，“ABC-123”是issue的管理概念，它可以被看做是获得资源的网址：http://jira-server/rest/api/2/issue/ABC-123.。
在jira-python中，资源是资源项目（或他的子类）中的实例，只能从find()方法中的服务器中获得。并且资源可以连接到其他的资源中。
所有资源都有一个自己的链接：称为根级属性，它包含的资源来源于网址。
Important
一个资源连接到其他资源，并在客户端保存该连接。
在上边的例子中，issue的对象在issue.fields.assignee中不仅仅是个字典，它是一个完整的资源对象。
A properties object is a collection ofvalues returned by JIRA in response to some query from the REST API. Theirstructure is freeform and modeled as a Python dict. Client methods return thisstructure for calls that do not produce resources. For example, the propertiesreturned from the URL http://jira-server/rest/api/2/issue/createmeta aredesigned to inform users what fields (and what values for those fields) arerequired to successfully create issues in the server’s projects. Since theseproperties are determined by JIRA’s configuration, they are not resources.
一个Properties对象是JIRA响应来自REST API的一些查询返回的值的集合。
其结构是自由形式和建模为一个Python字典。
客户端方法返回这个结构不产生资源的调用。
举例来说，从性能http://jira-server/rest/api/2/issue/createmeta旨在告知哪些字段（和什么样的价值观对那些字段）都必须在服务器的成功创建问题的用户的URL返回项目。
由于这些属性是由JIRA的配置决定，他们不是资源。
JIRA的客户端的方法记录它们是否会返回一个资源或对象的属性。
Contributing贡献
客户端是在BSD许可下的一个开源项目。任何种类的欢迎踊跃投稿！http://bitbucket.org/bspeakmon/jira-python
Discussion讨论
我们鼓励所有愿意使用“python”标签的人到http://answers.atlassian.com这里讨论