m's blog

備忘録とかメモとか

【Redmine】Redmine API を試してみる【curl編】

Redmine API を試してみる【 curl 編 】

今回は curl コマンドを使って、Redmine API 経由でプロジェクトを操作 してみたいと思います。

ここのところ、ちょくちょく Redmine をさわる機会があり、Redmine API について調べることがあったので、簡単にまとめてみたいと思います。

目次

必要な環境

解説の中で、git, dockerdocker-compose、シェルスクリプト、curl を使用しています。

本記事の内容をトレースする場合は、上記のツールが必要になります。

簡単な流れ

本記事では、以下のような流れで解説を進めていきます。

  1. GitHub から使用するソースコードを取得
  2. Docker を使って、Redmine 環境をセットアップ
  3. 必要になる変数を定義
  4. プロジェクト操作用の関数のロードと解説
  5. API 経由でプロジェクトを操作
  6. まとめ

それでは、早速、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 の起動には少し時間がかかります。ページが表示されない場合は、少し時間をおいてからページをリロードしてください。

必要な変数の定義

後述するプロジェクト操作関数を使用する上で、必要になる変数を定義しておきます。

以下のコマンドで DOMAINAPI_ACCESS_KEY 変数を定義してください。

DOMAIN=localhost:53000
API_ACCESS_KEY=[APIアクセスキー]

ホストやポートを調整している場合は、localhost:53000 の部分を調整してください。

API アクセスキーは以下の流れで確認してください。

API アクセスキーの確認

REST API を有効化する

http://localhost:53000 を開いてください。

パスワード入力画面が表示されるので、ログイン ID に「 admin 」、パスワードにも「 admin 」(初期パスワード)と入力してください。

Redmine API を試してみる【 curl 編 】

パスワード変更画面が表示されるので、パスワードには「 admin 」、新しいパスワードとパスワードの確認の部分には、適当なパスワードを入力して、新しいパスワードを設定してください。

Redmine API を試してみる【 curl 編 】

左上にある項目の中の「管理」をクリックしてください。

Redmine API を試してみる【 curl 編 】

左の方に表示される項目の中の「設定」をクリックして設定ページを開いてください。

Redmine API を試してみる【 curl 編 】

タブの中から「 API 」タブを選択し、「 REST による Web サービスを有効にする」をチェックして「保存」ボタンをクリックしてください。

Redmine API を試してみる【 curl 編 】

API アクセスキーを取得する

右上にある項目の中の「個人設定」をクリックしてください。

Redmine API を試してみる【 curl 編 】

個人設定ページが開くと、右の方に以下の画像のようなエリアが表示されます。

Redmine API を試してみる【 curl 編 】

「 API アクセスキー」の下にある「表示」をクリックすると API アクセスキーが表示されます。

API アクセスキーをコピーして、API_ACCESS_KEY 変数に設定してください。

プロジェクト操作関数をロード

Redmine API へのリクエストを functions.sh ファイルで関数化しています。

今回は Redmine API の Projects API を使用します。

Redmine API の詳細については、以下のページを参照してください。

https://www.redmine.org/projects/redmine/wiki/Rest_Projects

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"
}

DOMAINAPI_ACCESS_KEY 変数が関数の利用前に定義されていることを想定しています。

関数をコマンドラインから使用するために、以下のコマンドで関数をロードしてください。

. functions.sh

各関数の簡単な解説

checkVariables

DOMAINAPI_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"}}

プロジェクト作成結果の identifiername フィールドには引数にしていた 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 にプロジェクトが1つ追加されました。

Redmine のページでもプロジェクトが作成されたか、確認しておきます。

http://localhost:53000 を開いて、左上の方にある「プロジェクト」リンクをクリックしてください。

プロジェクトページに、以下のようなプロジェクトが表示されていれば、プロジェクトの作成は成功です。

Redmine API を試してみる【 curl 編 】

プロジェクトの更新

次に、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 プロジェクトに以下のような説明が追加されていれば、問題なく更新されています。

Redmine API を試してみる【 curl 編 】

プロジェクトの削除

最後に、追加したプロジェクトを削除しておきます。

$ 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 が充実していない項目はデータベースに直接アクセス?
  • データベースに直接アクセスする場合は、慎重に( ゚Д゚)ブルブル