---
title: "Jira 连接器"
description: "完整的 Jira Cloud 集成指南，通过 Tajo 将 Issue、项目和团队活动数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/jira/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/jira.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Jira 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 Tajo 将您的 Jira Cloud 实例连接到 Brevo，实现面向客户的 Issue 跟踪、支持工单可见性和项目里程碑通知。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Jira Cloud |
| **类别** | 自定义 |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | Issue、项目、用户、事件 |
| **API 类型** | REST API v3 |
| **认证方式** | OAuth 2.0 (3LO) / API 令牌（基本认证） |
| **基础 URL** | `https://your-domain.atlassian.net/rest/api/3/` |

## 功能

- **Issue 事件同步** - 将 Issue 创建、更新和解决事件转发到 Brevo 联系人时间线
- **客户工单跟踪** - 将 Jira Issue 与 Brevo 联系人关联，提供支持可见性
- **项目里程碑提醒** - 在版本发布和冲刺完成时触发 Brevo 活动
- **团队容量数据** - 同步工作负载指标，用于运营仪表板
- **状态变更事件** - 将 Issue 工作流转换跟踪为 Brevo 事件
- **评论同步** - 将面向客户的评论转发到 Brevo 活动日志

## 前提条件

开始之前，请确保您已具备：

1. Jira Cloud 实例（Jira Software、Jira Service Management 或 Jira Work Management）
2. 创建 OAuth 应用或生成 API 令牌的管理员权限
3. 与 API 令牌关联的 Atlassian 账户邮箱
4. 具有 API 访问权限的 Brevo 账户
5. 具有有效订阅的 Tajo 账户

## 认证

Jira Cloud 支持多种认证方式。

### 选项 1：OAuth 2.0 (3LO) - 推荐

1. 前往 [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
2. 点击**创建** > **OAuth 2.0 集成**
3. 配置回调 URL：`https://app.tajo.io/callbacks/jira`
4. 添加以下范围：

```
read:jira-work
read:jira-user
write:jira-work
read:me
```

OAuth 2.0 的 API URL 结构：

```
https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource}
```

### 选项 2：API 令牌（基本认证）

1. 前往 [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens)
2. 点击**创建 API 令牌**
3. 命名为”Tajo Integration”

```bash
# Basic Auth: email as username, API token as password
curl -X GET "https://your-domain.atlassian.net/rest/api/3/myself" \
  -u "email@example.com:$JIRA_API_TOKEN" \
  -H "Accept: application/json"
```

API 令牌限制

API 令牌绑定到个人用户账户。如果该用户被停用，集成将中断。生产环境请使用 OAuth 2.0。

### 连接到 Tajo

```bash
# Using OAuth 2.0
tajo connectors install jira \
  --client-id $JIRA_CLIENT_ID \
  --client-secret $JIRA_CLIENT_SECRET \
  --cloud-id $JIRA_CLOUD_ID

# Using API Token
tajo connectors install jira \
  --site-url your-domain.atlassian.net \
  --email admin@example.com \
  --api-token $JIRA_API_TOKEN
```

## 配置

### 基础设置

```yaml
connectors:
  jira:
    enabled: true
    site_url: "your-domain.atlassian.net"
    auth_type: "oauth2"  # or "basic"

    sync:
      issues: true
      projects: true
      users: true
      comments: true
      worklogs: false

    projects:
      - key: "SUPPORT"
        sync_to_list: 22
      - key: "PRODUCT"
        sync_to_list: 23

    issue_types:
      - Bug
      - Story
      - Task
      - Support Request
```

### 字段映射

将 Jira Issue 和用户字段映射到 Brevo 属性：

```yaml
field_mapping:
  # User fields
  accountId: JIRA_ACCOUNT_ID
  emailAddress: email
  displayName: FIRSTNAME

  # Issue fields mapped to contact events
  issue_key: LAST_TICKET_KEY
  issue_status: LAST_TICKET_STATUS
  issue_priority: LAST_TICKET_PRIORITY
  issue_created: LAST_TICKET_DATE
  resolution: LAST_TICKET_RESOLUTION
```

## API 端点

Tajo 集成以下 Jira Cloud REST API v3 端点：

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/rest/api/3/search` | POST | 使用 JQL 搜索 Issue |
| `/rest/api/3/issue/{issueIdOrKey}` | GET | 获取 Issue 详情 |
| `/rest/api/3/issue` | POST | 创建 Issue |
| `/rest/api/3/project` | GET | 列出所有项目 |
| `/rest/api/3/project/{projectIdOrKey}` | GET | 获取项目详情 |
| `/rest/api/3/user/search` | GET | 搜索用户 |
| `/rest/api/3/myself` | GET | 获取当前用户 |
| `/rest/api/3/issue/{issueIdOrKey}/comment` | GET | 获取 Issue 评论 |
| `/rest/api/3/webhook` | POST | 注册 Webhook |
| `/rest/api/3/status` | GET | 获取所有状态 |
| `/rest/api/3/priority` | GET | 获取所有优先级 |

## 代码示例

### 初始化连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('jira', {
  clientId: process.env.JIRA_CLIENT_ID,
  clientSecret: process.env.JIRA_CLIENT_SECRET,
  cloudId: process.env.JIRA_CLOUD_ID
});
```

### 同步支持 Issue

```javascript
// Sync Jira support issues to Brevo contacts
await tajo.connectors.sync('jira', {
  type: 'incremental',
  resources: ['issues'],
  jql: 'project = SUPPORT AND updated >= -24h',
  batchSize: 50
});

const status = await tajo.connectors.status('jira');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T12:00:00Z',
//   issuesTracked: 4560,
//   projectsMonitored: 3,
//   usersLinked: 890
// }
```

### 处理 Jira Webhook

```javascript
app.post('/webhooks/jira', async (req, res) => {
  const event = req.body;

  await tajo.connectors.handleWebhook('jira', {
    event: event.webhookEvent,
    payload: {
      issueKey: event.issue?.key,
      issueType: event.issue?.fields?.issuetype?.name,
      status: event.issue?.fields?.status?.name,
      reporter: event.issue?.fields?.reporter?.emailAddress,
      assignee: event.issue?.fields?.assignee?.emailAddress
    }
  });

  res.status(200).send('OK');
});
```

### 按客户搜索 Issue

```javascript
// Find all issues reported by a specific customer
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "customer@example.com" ORDER BY created DESC',
  maxResults: 20,
  fields: ['summary', 'status', 'priority', 'created']
});
```

## 速率限制

Jira Cloud 实施速率限制以确保平台稳定性：

| 上下文 | 速率限制 |
| --- | --- |
| **REST API** | 每用户每 10 秒约 100 个请求 |
| **并发请求** | 10 个并发长时请求 |
| **批量操作** | 因端点而异 |

分页

Jira 使用基于偏移量的分页，通过 `startAt` 和 `maxResults` 参数实现。默认页面大小为 50，最大为 100。Tajo 自动处理分页。

超出速率限制时，Jira 返回 `429 Too Many Requests` 响应，并附带 `Retry-After` 头部，指示何时可以重试。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | 令牌无效或 OAuth 过期 | 刷新 OAuth 令牌或重新生成 API 令牌 |
| 403 Forbidden | 权限不足 | 检查用户是否有访问所请求项目的权限 |
| JQL 错误 | 查询语法无效 | 先在 Jira 的 Issue 搜索中验证 JQL |
| 未收到 Webhook | 防火墙拦截 | 确保 Webhook URL 可公开访问 |
| 字段缺失 | 字段未在响应中 | 将字段添加到 `fields` 参数或使用 `expand` |

### 调试模式

```yaml
connectors:
  jira:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 测试连接

```bash
tajo connectors test jira
# ✓ API authentication successful
# ✓ Project access verified
# ✓ Issue search operational
# ✓ User lookup available
# ✓ Webhook registration active
```

## 最佳实践

1. **生产环境使用 OAuth 2.0** - 避免依赖个人用户账户
2. **使用 JQL 过滤** - 只同步相关 Issue 以减少 API 调用
3. **使用 Webhook 实现实时** - 避免轮询；注册 Webhook 监听 Issue 变更
4. **遵守 ADF 格式** - Jira v3 对富文本字段使用 Atlassian 文档格式
5. **项目到列表的映射** - 为每个 Jira 项目创建独立的 Brevo 列表
6. **处理分页** - 始终迭代所有页面以获取完整数据

## 安全

- **OAuth 2.0 (3LO)** - 带刷新令牌的安全基于令牌的认证
- **API 令牌 + 基本认证** - Base64 编码的 HTTPS 凭据
- **仅 HTTPS** - 所有 API 通信通过 TLS 1.2+ 加密
- **范围访问** - OAuth 范围将 API 访问限制到所需资源
- **Atlassian Cloud 安全** - SOC 2 Type II 认证基础设施
- **加密存储** - 凭据在 Tajo 中静态加密

## 相关资源

- [GitHub 连接器](https://tajo.io/zh-cn/docs/connectors/custom/github)
- [Linear 连接器](https://tajo.io/zh-cn/docs/connectors/custom/linear)
- [Gorgias 连接器](https://tajo.io/zh-cn/docs/connectors/support/gorgias)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)