APIトークンでJiraに接続

APIトークンを使うと、サインイン画面を経由せずにPlanning Poker WebからJiraの課題を読み取り、確定した見積もりを書き戻せます。このページでは、トークンの作成方法、許可される操作、問題が起きたときの確認事項を説明します。対象はJira Cloud（your-team.atlassian.netのようなアドレス）です。Jira Data Centerには対応していません。

始める前に

• 組織でプランニングポーカーを管理する権限が必要です。オーナーには標準で付与されています。
• トークンを使うJiraアカウントには、各プロジェクトでプロジェクトの閲覧（課題のインポート）と課題の編集（見積もりの書き戻し）権限が必要です。インポートのみで書き戻しを行わない場合は、閲覧権限だけで十分です。
• 個人アカウントではなく、[email protected]のような専用の共有アカウントをおすすめします。課題の履歴にはそのアカウント名が表示されます。個人のトークンは、その人が退職したりアクセスを失ったりすると使えなくなります。

手順1：Atlassianでトークンを作成

1. 選んだアカウントでAtlassianにサインインし、id.atlassian.com → セキュリティ → APIトークンを開きます。
2. APIトークンを作成を選びます。「スコープ付きAPIトークンを作成」ではない通常のトークンを使ってください。スコープ付きトークンはこの連携では動作しません。
3. 「Planning Poker Web」など分かりやすい名前を付け、有効期間を選びます。
4. トークンをすぐにコピーします。Atlassianが表示するのは一度だけです。紛失した場合は新しく作成してください。

この項目が表示されない場合、Atlassian管理者がトークンを作成できるユーザーを制限している可能性があります。選んだアカウントで作成できるよう管理者に依頼してください。

手順2：Planning Poker Webで接続

1. 設定 → 連携を開き、Jira、接続の順に選び、APIトークンを選択します。
2. 次の3項目を入力します。
   • Jiraサイト：Jiraのアドレス（例：https://your-team.atlassian.net）。https://…​.atlassian.net形式のみ使用できます。
   • アカウントのメールアドレス：トークンを作成したAtlassianアカウントのメールアドレス。
   • APIトークン：コピーしたトークン。
3. テストを選びます。接続に成功するとJiraアカウント名が表示されます。トークンは暗号化して保存され、再表示されません。
4. 設定の手順で、確定した見積もりをJiraに送信するか、送信先のフィールドを選びます。詳しくは見積もりを外部ツールに反映をご覧ください。

仕組み

すべてのリクエストは、メールアドレスとトークンで認証し、当社サーバーからJiraへ送信します。トークンの権限は作成したアカウントと同じで、それを超えることはありません。Planning Poker Webが行う操作は次のとおりです。

• インポート画面で絞り込みを表示するため、プロジェクト、ステータス、課題タイプ、エピック、スプリントを読み取る。
• ルームに取り込むため、課題キー、タイトル、説明を読み取る。
• 選択したフィールドに確定した見積もりの数値を1つ書き込む。

課題の作成・削除、ステータスの変更、コメントの追加は行いません。スプリント情報は、アカウントがJira Softwareでプロジェクトのボードを開ける場合にのみ読み取られます。権限がない場合、スプリントフィルターは空になります。

接続できない場合

• 「Jiraが認証情報を拒否しました」：メールアドレスまたはトークンが誤っている、トークンが無効化された、または期限切れの可能性があります。新しいトークンを作成して再接続してください。
• 「Jiraがアクセスを拒否しました（403）」：Jiraはキーを認識しましたが、リクエストを拒否しました。順に確認してください。アカウントでそのJiraサイトにアクセスできるか（そのアカウントでログインしてサイトを開く）、プロジェクトの閲覧と課題の編集ができるか、Atlassian管理者がAPIアクセス元のネットワークを制限していないか、通常のトークンを使っているか。Jiraから説明がある場合はエラーメッセージの後に表示されます。
• プロジェクトが一覧に表示されない：アカウントに閲覧権限がありません。プロジェクトに追加するか、すでにアクセスできるアカウントを使ってください。
• フィールドが画面にないため見積もりを送れない：そのプロジェクトの課題編集画面にフィールドを追加してください。似たフィールドにStory pointsとStory point estimateがあります。ボードに表示されるほうを選びます。
• 「Jira Cloudのアドレスを使用してください」：サイト欄はhttps://your-team.atlassian.net形式で、後ろにパスを付けないでください。

トークンの期限切れや接続解除

Atlassianのトークンには有効期限があります。期限が切れたら、新しいトークンを作成して再接続してください。見積もりの設定は保持されます。接続を終了するには、Planning Poker Webで接続解除を選び、必要に応じてid.atlassian.com → セキュリティ → APIトークンでトークンを無効化します。接続解除後はJiraにアクセスできません。