JIRA REST API

2017-10-16 (Mon)  •  By 伊藤  •  ドキュメント  •  JIRA Core JIRA Service Desk JIRA Software 翻訳

今回の記事は、Jira 開発者向けドキュメント「JIRA REST APIs 」の弊社翻訳版です。原文と差異がある場合は、原文の内容が優先されます。

このページでは、Jira がサポートする唯一のリモート API である、JIRA REST API の概要について解説しています。このページやチュートリアルに記載されている例は Jira プラットフォーム用 REST API を使用しています。しかし、その原則の多くは Jira アプリケーション用 REST API にも適用可能です。

  • Jira 用 REST API のすべてのドキュメントが必要な場合は、「JIRA APIs 」を参照してください。

このページの内容 :

  • 概要
  • アプリケーション UI からの REST API の参照とテスト
  • 簡単な例 : Jira 上での課題の作成
  • 認証
  • 課題の編集や更新
  • チュートリアル

概要

Atlassian REST API は Jira やその他アプリケーションと対話を行うための標準インターフェイスを実装しています。

REST API は URI パス経由でのリソース (データ エンティティ) へのアクセスを提供します。REST API を使用するために、お使いのアプリケーションは HTTP 要求を行い、さらにその応答を解析します。メソッドは GET、PUT、POST、および DELETE などの標準 HTTP メソッドです。REST API は HTTP(S) を使用しての操作するため、任意のプログラム言語やフレームワークで取り扱い易くなっています。Jira REST API の入出力形式は JSON です。

Jira は Atlassian REST プラグイン を使用して Jira API を実装しています。この REST プラグインは Jira に同梱されています。独自の REST API を Jira に追加するには、REST プラグイン モジュールを含む Jira プラグインを作成 します。

Jira REST API を使用したことがない場合は、「Atlassian REST API policy 」を参照してください。

アプリケーション UI からの REST API の参照とテスト

REST API の仕様はアトラシアン アプリケーション毎に異なるため、お使いの製品用の REST API Browser を学習する最良の方法は、Jira インスタンスで REST API Browser ビルドを使用することです。

この REST API Browser を使用することで、お使いのアプリケーション用の REST API Browser を閲覧、検査、および実行できます。これはアトラシアン アプリケーションで利用可能な REST API やその他のリモート API を発見するためのツールです。

Stash、および最近のバージョンの Confluence や Jira など、何種類かのアトラシアン アプリケーションでこのブラウザーはビルドされています。Developer Toolbox プラグイン の一部でもあり (アトラシアン アプリケーションの開発者インスタンスに既定で組み込まれています)、また、単独で利用 することもできます。Developer Toolbox プラグインは Jira 7 以降とは互換性がないことに注意してください。

REST API Browser の取得と操作の詳細については、「Using the REST API Browser 」を参照してください。

簡単な例 : Jira 上での課題の作成

REST 経由で Jira 上に課題を作成したいですか? その方法は簡単です。

以下の例では curl を使用しています。理想としては REST API Browser を使用して API がどのように動作するかを調査すべきでしょう。しかし、この例はあくまでも概要を説明するためのものです。ローカルの Jira インスタンス上に課題を作成します。

今回の例におけるポイントは、以下のとおりです。

  • 入力ファイルは ‘--data @filename‘ 構文で表されます。
  • データの表記は個別に行い、かつ JSON 形式を使用します。
  • リクエスト内のコンテンツ タイプを ‘application/json‘ に必ず設定してください。
  • Jira サーバーに JSON を POST します。
  • 今回の例の場合、サーバーは http://localhost:8080/jira/rest/api/2/issue/ です。
  • 今回の例では基本認証を使用しています (ユーザー名は admin、ならびにパスワードは admin)。
  • 実行する前にインスタンスにプロジェクトを追加する必要があります。また、課題の追加先となるプロジェクトのプロジェクト ID を事前に取得します。

curl を用いた簡単な REST コマンドを試すには、以下の操作を行います。

  1. POST データを含むデータ ファイルの作成から始めます。今回の場合、そのファイル名を data.txt と仮定します。以下のコンテンツを追加します。
  2. {
        "fields": {
           "project":
           {
              "id": "10000"
           },
           "summary": "No REST for the Wicked.",
           "description": "Creating of an issue using ids for projects and issue types using the REST API",
           "issuetype": {
              "id": "3"
           }
       }
    }
    

    今回の場合、プロジェクト ID は 10000 です。お使いのインスタンス上のプロジェクトに合わせて適切な ID を使用してください。また、今回指定する課題タイプは 3 です。これはタスクを表しています。

    その他の方法として、REST API Browser 上で api/2/issue リソースを検索し、そして上記のテキストを [Request Body] フィールドに張り付けることで試すことができます。
  3. コマンド ラインから以下のコマンドを入力します。
  4. curl -u admin:admin -X POST --data @data.txt -H "Content-Type: application/json" http://localhost:8080/jira/rest/api/2/issue/ 
    

    すでに述べたとおり、Jira インスタンスのホスト名やポート番号など、お使いの環境に合わせて詳細を調整します。クラウド インスタンスや多くのパブリック インスタンスでは、HTTPS の使用、ならびにそのインスタンスに関する有効な資格情報が要求されることに注意してください。

応答として、課題 ID、課題キー、ならびにその課題への URL が返されます (これらは追加データを GET したり、更新を PUT したりする際に利用できます)。

{
   "id":"10009",
   "key":"TEST-10",
    "self":"http://localhost:8080/jira/rest/api/2/issue/10009"
} 

プロジェクトや課題タイプとして数値識別子を使用する代わりに、以下のようにプロジェクト キーや課題タイプ名を使用することもできます。

{
    "fields": {
       "project":
       { 
          "key": "TEST"
       },
       "summary": "REST ye merry gentlemen.",
       "description": "Creating of an issue using project keys and issue type names using the REST API",
       "issuetype": {
          "name": "Task"
       }
   }
}

REST 経由で課題を作成する方法の詳細については、以下を参照してください。

認証

REST API は基本認証、Cookie ベース (セッション) の認証、および OAuth に対応しています。基本認証 Cookie ベース (セッション) の認証 、および OAuth の例を参照してください。

課題の編集や更新

Updating an Issue via the JIRA REST APIs 」 を参照してください。

チュートリアル

JIRA REST API Tutorials 」を参照してください。


Related Articles

お気軽にお問い合わせください

お問い合わせ