【Redmine】Redmine API を試してみる【curl編】
今回は curl コマンドを使って、Redmine API 経由でプロジェクトを操作 してみたいと思います。
ここのところ、ちょくちょく Redmine をさわる機会があり、Redmine API について調べることがあったので、簡単にまとめてみたいと思います。
目次
必要な環境
解説の中で、git, docker、docker-compose、シェルスクリプト、curl を使用しています。
本記事の内容をトレースする場合は、上記のツールが必要になります。
簡単な流れ
本記事では、以下のような流れで解説を進めていきます。
- GitHub から使用するソースコードを取得
- Docker を使って、Redmine 環境をセットアップ
- 必要になる変数を定義
- プロジェクト操作用の関数のロードと解説
- API 経由でプロジェクトを操作
- まとめ
それでは、早速、curl コマンドを使って、Redmine API 経由でプロジェクトを操作する方法を解説していきたいと思います。
ソースコードの取得
本記事で解説するコードは、以下のリポジトリにまとめてあります。
以下のコマンドを実行して、使用するソースコードをクローンしてください。
git clone https://github.com/mm0202/trial_redmine-api-with-curl.git
Redmine コンテナの起動
ソースコードに含まれている、docker-compose.yml を使って、Redmine 環境をセットアップします。
docker-compose.yml の中身は、以下の通りです。
version: "3" services: redmine: image: redmine restart: always ports: - 53000:3000 environment: REDMINE_DB_MYSQL: db REDMINE_DB_PASSWORD: example REDMINE_SECRET_KEY_BASE: supersecretkey db: image: mariadb restart: always command: mysqld --character-set-server=utf8 --collation-server=utf8_unicode_ci environment: MYSQL_ROOT_PASSWORD: example MYSQL_DATABASE: redmine
今回は、Redmine API を試すだけなので、データの永続化設定などは行っていません。
外部公開ポートは 53000 に設定しています。
※ 本番利用する場合は、永続化設定やパスワードの調整をしてください。
以下のコマンドで、ソースコードのルートディレクトリへ移動してください。
cd trial_redmine-api-with-curl
ソースコードのルートへ移動したら、コンテナを起動してください。
docker-compose up -d
起動後、http://localhost:53000 にアクセスすると Redmine の初期画面が表示されます。
ホスト名を変えている場合は、localhost の部分を調整してください。
※ Redmine の起動には少し時間がかかります。ページが表示されない場合は、少し時間をおいてからページをリロードしてください。
必要な変数の定義
後述するプロジェクト操作関数を使用する上で、必要になる変数を定義しておきます。
以下のコマンドで DOMAIN と API_ACCESS_KEY 変数を定義してください。
DOMAIN=localhost:53000 API_ACCESS_KEY=[APIアクセスキー]
ホストやポートを調整している場合は、localhost:53000 の部分を調整してください。
API アクセスキーは以下の流れで確認してください。
API アクセスキーの確認
REST API を有効化する
http://localhost:53000 を開いてください。
パスワード入力画面が表示されるので、ログイン ID に「 admin 」、パスワードにも「 admin 」(初期パスワード)と入力してください。
パスワード変更画面が表示されるので、パスワードには「 admin 」、新しいパスワードとパスワードの確認の部分には、適当なパスワードを入力して、新しいパスワードを設定してください。
左上にある項目の中の「管理」をクリックしてください。
左の方に表示される項目の中の「設定」をクリックして設定ページを開いてください。
タブの中から「 API 」タブを選択し、「 REST による Web サービスを有効にする」をチェックして「保存」ボタンをクリックしてください。
API アクセスキーを取得する
右上にある項目の中の「個人設定」をクリックしてください。
個人設定ページが開くと、右の方に以下の画像のようなエリアが表示されます。
「 API アクセスキー」の下にある「表示」をクリックすると API アクセスキーが表示されます。
API アクセスキーをコピーして、API_ACCESS_KEY 変数に設定してください。
プロジェクト操作関数をロード
Redmine API へのリクエストを functions.sh ファイルで関数化しています。
今回は Redmine API の Projects API を使用します。
Redmine API の詳細については、以下のページを参照してください。
functions.sh の中身は、以下の通りです。
function checkVariables() { if [ -z "$DOMAIN" ]; then echo 'DOMAIN is empty. Please set DOMAIN.' fi if [ -z "$API_ACCESS_KEY" ]; then echo 'API_ACCESS_KEY is empty. Please set API_ACCESS_KEY.' fi } function listProjects() { checkVariables curl "$DOMAIN/projects.json" } function showProject() { checkVariables local ID=$1 curl "$DOMAIN/projects/$ID.json" } function createProject() { checkVariables local ID=$1 curl -X POST -H "Content-Type: application/json" -H "X-Redmine-API-Key: $API_ACCESS_KEY" -d "{\"project\":{\"name\":\"$ID\",\"identifier\":\"$ID\"}}" "$DOMAIN/projects.json" } function updateProjectDescription() { checkVariables local ID=$1 local DESCRIPTION=$2 curl -X PUT -H "Content-Type: application/json" -H "X-Redmine-API-Key: $API_ACCESS_KEY" -d "{\"project\":{\"description\":\"$DESCRIPTION\"}}" "$DOMAIN/projects/$ID.json" } function deleteProject() { checkVariables local ID=$1 curl -X DELETE -H "Content-Type: application/json" -H "X-Redmine-API-Key: $API_ACCESS_KEY" "$DOMAIN/projects/$ID.json" }
DOMAIN と API_ACCESS_KEY 変数が関数の利用前に定義されていることを想定しています。
関数をコマンドラインから使用するために、以下のコマンドで関数をロードしてください。
. functions.sh
各関数の簡単な解説
checkVariables
DOMAIN と API_ACCESS_KEY 変数が設定されているかを確認する関数です。
他の関数から呼び出して、変数が設定されているかを確認しています。
listProjects
プロジェクトのリストを表示します。
showProject
引数で id (または identifier )を指定して、指定のプロジェクトの情報を表示します。
createProject
引数で identifier を指定して、プロジェクトを作成します。
プロジェクト名にも引数の値を設定しています。
updateProjectDescription
引数に id (または identifier )と description を指定して、指定のプロジェクトの説明( description )を更新します。
deleteProject
引数に id (または identifier )を指定して、指定のプロジェクトを削除します。
プロジェクトを API 経由で操作する
プロジェクトを API 経由で操作する準備が整ったので、早速、試してみたいと思います。
プロジェクトをリストアップ
まずは、listProjects 関数で、プロジェクトをリストアップしてみます。
$ listProjects {"projects":[],"total_count":0,"offset":0,"limit":25}
まだ、プロジェクトを作成していないので、projects の中身は空になっています。
プロジェクトの作成
続いて、createProject 関数でプロジェクトを作成します。
$ createProject id-1 {"project":{"id":1,"name":"id-1","identifier":"id-1","description":null,"homepage":"","status":1,"is_public":true,"inherit_members":false,"created_on":"2020-05-09T20:47:15Z","updated_on":"2020-05-09T20:47:15Z"}}
プロジェクト作成結果の identifier と name フィールドには引数にしていた id-1 が設定されています。
listProjects 関数でプロジェクトが作成されたことを確認しておきます。
$ listProjects {"projects":[{"id":1,"name":"id-1","identifier":"id-1","description":null,"status":1,"is_public":true,"inherit_members":false,"created_on":"2020-05-09T20:47:15Z","updated_on":"2020-05-09T20:47:15Z"}],"total_count":1,"offset":0,"limit":25}
先ほどは空だった projects にプロジェクトが１つ追加されました。
Redmine のページでもプロジェクトが作成されたか、確認しておきます。
http://localhost:53000 を開いて、左上の方にある「プロジェクト」リンクをクリックしてください。
プロジェクトページに、以下のようなプロジェクトが表示されていれば、プロジェクトの作成は成功です。
プロジェクトの更新
次に、updateProjectDescription 関数を使って、プロジェクトの説明を変更します。
$ updateProjectDescription id-1 success?
showProject 関数でプロジェクトの説明が変更されたか確認します。
$ showProject id-1 {"project":{"id":1,"name":"id-1","identifier":"id-1","description":"success?","homepage":"","status":1,"is_public":true,"inherit_members":false,"created_on":"2020-05-09T20:47:15Z","updated_on":"2020-05-09T20:48:48Z"}}
description フィールドに success? と表示されていれば更新成功です。
Redmine のページでもプロジェクトが更新されたか、念のため、確認しておきます。
先ほど開いた、「プロジェクト」ページをリロードしてください。
id-1 プロジェクトに以下のような説明が追加されていれば、問題なく更新されています。
プロジェクトの削除
最後に、追加したプロジェクトを削除しておきます。
$ deleteProject id-1
listProjects 関数でプロジェクトが削除されたか確認しておきます。
$ listProjects {"projects":[],"total_count":0,"offset":0,"limit":25}
projects フィールドが空になっているので、問題なく削除できたようです。
「プロジェクト」ページの方でも、リロードしてプロジェクトが消えているか確認してみてください。
後始末
最後に、使用した redmine コンテナと mariadb コンテナを停止しておきます。
以下のコマンドで、起動したコンテナを停止してください。
docker-compose down
まとめ
以上、curl コマンドを使って、Redmine API 経由でプロジェクトを操作してみました。
今回は、プロジェクトの基本的な操作だけでしたが、Issue や User などについても、同様の CRUD 操作 API が用意されています。
カスタムフィールドについては、ドキュメントを見る限り、残念ながらカスタムフィールドの定義の取得だけのようです。
API 経由での操作であれば、データの不整合が起こる事は少ないと思うので、API が使える部分は、極力、API で操作したほうが良さそうです。
カスタムフィールドなど API が充実していない部分は、データベースに直接アクセスして操作 するしかなさそうですが、慎重にやらないと怖そうです(´▽｀；)
最後に、今回の内容について、簡単にまとめてみたいと思います。
- API が充実している項目は、大概の事ができそう！
- API が充実していない項目もある
- API が充実していない項目はデータベースに直接アクセス？
- データベースに直接アクセスする場合は、慎重に( ﾟДﾟ)ﾌﾞﾙﾌﾞﾙ
