ClawSkills logoClawSkills

Jira

具有托管 OAuth 的 Jira API 集成。使用 JQL 搜索问题，创建和更新问题，管理项目和转换。当用户希望

访问网站

介绍

# Jira

使用托管式 OAuth 身份验证访问 Jira Cloud API。使用 JQL 搜索问题、创建和管理问题，并自动化工作流。

## 快速开始

```bash # First, get your cloud ID python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/oauth/token/accessible-resources') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF

# Then search issues python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/search/jql?jql=project%3DKEY&maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

## 基础 URL

``` https://gateway.maton.ai/jira/{native-api-path} ```

将 `{native-api-path}` 替换为实际的 Jira API 端点路径。网关将请求代理到 `api.atlassian.com`，并自动注入您的 OAuth 令牌。

## 获取 Cloud ID

Jira Cloud 需要 Cloud ID。请先获取它：

```bash GET /jira/oauth/token/accessible-resources ```

响应：

```json [{ "id": "62909843-b784-4c35-b770-e4e2a26f024b", "url": "https://yoursite.atlassian.net", "name": "yoursite" }] ```

## 身份验证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

``` Authorization: Bearer $MATON_API_KEY ```

**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：

```bash export MATON_API_KEY="YOUR_API_KEY" ```

### 获取您的 API 密钥

1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥

## 连接管理

在 `https://ctrl.maton.ai` 管理您的 Jira OAuth 连接。

### 列出连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=jira&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 创建连接

```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'jira'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 获取连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "jira", "metadata": {} } } ```

在浏览器中打开返回的 `url` 以完成 OAuth 授权。

### 删除连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 指定连接

如果您有多个 Jira 连接，请使用 `Maton-Connection` 头指定要使用的连接：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/project') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

如果省略，网关将使用默认（最早）的活动连接。

## API 参考

### 项目

#### 列出项目

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/project ```

#### 获取项目

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/project/{projectKeyOrId} ```

### 问题

#### 搜索问题 (JQL)

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/search/jql?jql=project%3DKEY%20order%20by%20created%20DESC&maxResults=20&fields=summary,status,assignee ```

#### 获取问题

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} ```

#### 创建问题

```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue Content-Type: application/json

{ "fields": { "project": {"key": "PROJ"}, "summary": "Issue summary", "issuetype": {"name": "Task"} } } ```

#### 更新问题

```bash PUT /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} Content-Type: application/json

{ "fields": { "summary": "Updated summary" } } ```

#### 删除问题

```bash DELETE /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} ```

#### 分配问题

```bash PUT /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/assignee Content-Type: application/json

{ "accountId": "712020:5aff718e-6fe0-4548-82f4-f44ec481e5e7" } ```

### 转换

#### 获取转换

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/transitions ```

#### 转换问题 (更改状态)

```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/transitions Content-Type: application/json

{ "transition": {"id": "31"} } ```

### 评论

#### 获取评论

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/comment ```

#### 添加评论

```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/comment Content-Type: application/json

{ "body": { "type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Comment text"}]}] } } ```

### 用户

#### 获取当前用户

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/myself ```

#### 搜索用户

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/user/search?query=john ```

### 元数据

#### 列出问题类型

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issuetype ```

#### 列出优先级

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/priority ```

#### 列出状态

```bash GET /jira/ex/jira/{cloudId}/rest/api/3/status ```

## 代码示例

### JavaScript

```javascript // Get cloud ID first const resources = await fetch( 'https://gateway.maton.ai/jira/oauth/token/accessible-resources', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ).then(r => r.json());

const cloudId = resources[0].id;

// Search issues const issues = await fetch( `https://gateway.maton.ai/jira/ex/jira/${cloudId}/rest/api/3/search/jql?jql=project=KEY`, { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ).then(r => r.json()); ```

### Python

```python import os import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# Get cloud ID resources = requests.get( 'https://gateway.maton.ai/jira/oauth/token/accessible-resources', headers=headers ).json()

cloud_id = resources[0]['id']

# Search issues issues = requests.get( f'https://gateway.maton.ai/jira/ex/jira/{cloud_id}/rest/api/3/search/jql', headers=headers, params={'jql': 'project=KEY', 'maxResults': 10} ).json() ```

## 注意事项

- 始终先使用 `/oauth/token/accessible-resources` 获取 Cloud ID - JQL 查询必须有边界（例如 `project=KEY`） - 对 JQL 查询参数使用 URL 编码 - 更新、删除、转换操作成功时返回 HTTP 204 - Agile API 需要额外的 OAuth 范围。如果您收到范围错误，请通过 [email protected] 联系 Maton 支持，说明您需要的具体操作/API 以及您的用例 - 重要：使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，`$MATON_API_KEY` 等环境变量可能无法在某些 shell 环境中正确展开。通过管道传输时，您可能会遇到“Invalid API key”错误。

## 错误处理

| 状态 | 含义 | |--------|---------| | 400 | 缺少 Jira 连接或 JQL 无效 | | 401 | Maton API 密钥无效或缺失 | | 429 | 速率受限（每个账户每秒 10 次请求） | | 4xx/5xx | 来自 Jira API 的透传错误 |

### 故障排除：API 密钥问题

1. 检查是否设置了 `MATON_API_KEY` 环境变量：

```bash echo $MATON_API_KEY ```

2. 通过列出连接验证 API 密钥是否有效：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 故障排除：无效的应用名称

1. 确保您的 URL 路径以 `jira` 开头。例如：

- 正确：`https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/project` - 错误：`https://gateway.maton.ai/ex/jira/{cloudId}/rest/api/3/project`

## 资源

- [Jira API 简介](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) - [搜索问题 (JQL)](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get) - [获取问题](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get) - [创建问题](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post) - [转换问题](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-post) - [JQL 参考](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])

返回

更多产品

Obsidian

安全与密码

使用 Obsidian vault（纯 Markdown 笔记）并通过 obsidian-cli 自动化。

10.8K

Mcporter

安全与密码

使用 mcporter CLI 直接（HTTP 或 stdio）列出、配置、认证和调用 MCP 服务器/工具，包括临时服务器、配置编辑以及 CLI/类型生成

9.7K

YouTube

安全与密码

使用托管 OAuth 集成 YouTube Data API。搜索视频、管理播放列表、访问频道数据并与评论互动。当用户想要

8.5K