Jira 连接器

通过 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 活动日志

前提条件

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

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

认证

Jira Cloud 支持多种认证方式。

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

前往 developer.atlassian.com
点击创建 > OAuth 2.0 集成
配置回调 URL：https://app.tajo.io/callbacks/jira
添加以下范围：

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 令牌（基本认证）

前往 id.atlassian.com/manage/api-tokens
点击创建 API 令牌
命名为”Tajo Integration”

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

API 令牌限制

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

连接到 Tajo

# 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 [email protected] \
  --api-token $JIRA_API_TOKEN

配置

基础设置

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 属性：

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	获取所有优先级

代码示例

初始化连接器

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

// 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

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

// Find all issues reported by a specific customer
const issues = await tajo.connectors.query('jira', {
  jql: 'reporter = "[email protected]" 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`

调试模式

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

测试连接

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

最佳实践

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

安全

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

Jira 连接器

概览

功能

前提条件

认证

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

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

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

同步支持 Issue

处理 Jira Webhook

按客户搜索 Issue

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Thanks — you're subscribed.

Jira 连接器

概览

功能

前提条件

认证

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

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

连接到 Tajo

配置

基础设置

字段映射

API 端点

代码示例

初始化连接器

同步支持 Issue

处理 Jira Webhook

按客户搜索 Issue

速率限制

故障排除

常见问题

调试模式

测试连接

最佳实践

安全

相关资源

Subscribe to updates

Thanks — you're subscribed.