--- title: "Jira コネクタ" description: "Tajo を介して Jira Cloud の Issue、プロジェクト、チームアクティビティデータを Brevo と同期するための完全な Jira Cloud 統合ガイド。" url: https://tajo.io/jp/docs/connectors/custom/jira/ markdown: https://tajo.io/jp/docs/connectors/custom/jira.md lang: ja-JP 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` | Jira Cloud インスタンスを Brevo に接続し、Tajo を介して顧客向け Issue トラッキング、サポートチケットの可視化、プロジェクトマイルストーン通知を実現します。 ## 概要 | プロパティ | 値 | | --- | --- | | **プラットフォーム** | Jira Cloud | | **カテゴリ** | カスタム | | **セットアップの複雑さ** | 中 | | **公式統合** | いいえ | | **同期データ** | Issue、プロジェクト、ユーザー、イベント | | **API タイプ** | REST API v3 | | **認証** | OAuth 2.0(3LO)/ API Token(Basic Auth) | | **ベース 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. **Create** > **OAuth 2.0 integration** をクリック 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 Token(Basic Auth) 1. [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens) にアクセス 2. **Create API token** をクリック 3. 「Tajo Integration」と名前を付ける ```bash # Basic Auth: メールをユーザー名、API トークンをパスワードとして使用 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 # OAuth 2.0 を使用 tajo connectors install jira \ --client-id $JIRA_CLIENT_ID \ --client-secret $JIRA_CLIENT_SECRET \ --cloud-id $JIRA_CLOUD_ID # 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" # または "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: # ユーザーフィールド accountId: JIRA_ACCOUNT_ID emailAddress: email displayName: FIRSTNAME # 連絡先イベントにマッピングされた Issue フィールド 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 // Jira のサポート Issue を Brevo 連絡先に同期 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 // 特定の顧客が報告したすべての Issue を検索 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 認証に成功 # ✓ プロジェクトアクセスを確認 # ✓ Issue 検索操作可能 # ✓ ユーザー検索が利用可能 # ✓ Webhook 登録有効 ``` ## ベストプラクティス 1. **本番環境には OAuth 2.0 を使用する** - 個々のユーザーアカウントへの依存を避ける 2. **JQL でフィルタリングする** - API 呼び出しを減らすため関連する Issue のみ同期 3. **リアルタイムには Webhook を使用する** - ポーリングを避け、Issue 変更用に Webhook を登録 4. **ADF 形式を尊重する** - Jira v3 はリッチテキストフィールドに Atlassian Document Format を使用 5. **プロジェクトをリストにマッピングする** - Jira プロジェクトごとに個別の Brevo リストを作成 6. **ページネーションを処理する** - 完全なデータのため常にすべてのページを反復処理 ## セキュリティ - **OAuth 2.0(3LO)** - リフレッシュトークンを使用した安全なトークンベース認証 - **API Token + Basic Auth** - HTTPS 経由の Base64 エンコードされた資格情報 - **HTTPS のみ** - すべての API 通信は TLS 1.2 以上で暗号化 - **スコープ付きアクセス** - OAuth スコープが API アクセスを必要なリソースに制限 - **Atlassian Cloud セキュリティ** - SOC 2 Type II 認証取得済みインフラストラクチャ - **暗号化されたストレージ** - 資格情報は Tajo で保存時に暗号化 ## 関連リソース - [GitHub コネクタ](https://tajo.io/jp/docs/connectors/custom/github) - [Linear コネクタ](https://tajo.io/jp/docs/connectors/custom/linear) - [Gorgias コネクタ](https://tajo.io/jp/docs/connectors/support/gorgias) - [Brevo Contacts API](https://tajo.io/jp/docs/contact-management)