TimeTracker NX Web APIはどう活用するのか？効果と活用例を紹介
本稿では、弊社サポートエンジニアの協力を得て、WebAPIを用いた機能拡張に関して記述いたします。
TimeTracker NXとは
TimeTracker NXは、ソフトウェア開発、ハード設計、営業、Web制作などの知識労働・デスクワーク業務における工数管理・プロジェクト管理のためのツールです。最大の特徴は「徹底した現場志向に基づいて開発されたツール」であることです。
Web APIとは
Webサイトやアプリケーションなどのプログラムに対し、外部のプログラムからデータの送受信を行うためのインターフェースです。Web APIを使用することで、外部のプログラムから特定の機能を利用したり、Webサイトの情報を取得したりすることができます。
TimeTracker NXは、Web APIを使用することで、ブラウザの画面から実施できる操作はもちろんのこと、ブラウザの画面からは難しい一括操作や自動実行も実現できます。これにより、TimeTracker NX以外のツール(※)と自動でデータをやり取りすることができます。
※ 例えば、基幹システムやBIツールがあります。
TimeTracker NX Web APIの基本的な使い方
TimeTracker NXは、『プロジェクト』や『ワークアイテム』といったリソースに対して URI（※） が割り当てられています。そのURI に対して GET／POST／PUTといった HTTP の標準的なメソッドを使用してリクエストを送ることで、対象のリソースを操作します。
※Uniform Resource Identifier：Web上にあるあらゆるファイルを認識するための識別子の総称です。
ここでは、Web APIを使用するまでに必要な以下のステップをご紹介します。
- Web API使用時の認証方法
- Web APIリクエストの送信方法
- 必要なプログラミングの基礎知識やライブラリ
Web API使用時の認証方法
どちらも一般的に使用される認証方法ですが、セキュリティや使用状況に応じて
最適な方法を選択する必要があります。
| 認証方式 | 利用する情報 |
| Basic認証 | ユーザー名とパスワード |
| トークン認証 | トークン（ランダムな文字列） |
どちらも一般的に使用される認証方法ですが、セキュリティや使用状況に応じて
最適な方法を選択する必要があります。
TimeTracker NXにおける具体的な認証方法は以下のページを参照してください。
https://docs.timetracker.jp/webapi/docs/use-api#%E8%AA%8D%E8%A8%BC%E6そ%96%B9%E5%BC%8F
Web APIリクエストの送信方法
Web APIのメソッドは以下の４種類あります。
| メソッド | 実現する処理 |
| 取得 (GET) | クエリパラメーターで取得対象のデータや条件を指定し、データを取得します。 |
| 追加 (POST) | 追加するデータをリクエストボディで指定します。 |
| 更新 (PUT) | 更新するデータをリクエストボディで指定します。 |
| 削除 (DELETE) | URIのパスパラメーターに対象オブジェクトのIDを指定し、データを削除します。 |
各メソッドでは、各形式のデータを使用します。
- クエリパラメーター
クエリパラメーターは、URLの末尾に追加されるキーと値のペアです。クライアントがサーバーに情報を送信するために使用され、短い情報やフィルタリングの目的に使用されます。
通常GETリクエストで使用され、URLの「?」以降に記述されます。
例） https://timetracker-server.com/api/system/users***?id=25***
- リクエストボディ
リクエストボディは、HTTPリクエストの一部として送信されるデータのペイロード（本文）です。リクエストボディは、クライアントからサーバーにデータを送信するために使用されます。
TimeTracker NXでは、JSON形式でデータをエンコードして送信します。
例）ユーザーの新しいプロフィール情報を更新する場合には、リクエストボディにJSON形式でユーザーの名前やメールアドレスなどのデータが含まれます。
- バスパラメーター
バスパラメーターは、URLの一部としてパスに直接埋め込まれるパラメータです。主に可変のリソースを識別するために使用されます。
バスパラメーターは、ダイナミックなURLパスを作成するために使用されます。
例） https://timetracker-server.com/api/system/users/***\{10, 25, 34}***
必要なプログラミングの基礎知識やライブラリについて
プログラミング言語
Web APIアプリ開発には、一般的に使用されるプログラミング言語の知識が必要です。
代表的な言語には、JavaScript、Python、Ruby、Java、C#などがあります。
これらの言語の基本構文やデータ操作、関数やクラスの作成などの基礎知識が必要です。
また、各プログラミング言語向けのWebフレームワークを使用することが一般的です。これらのフレームワークは、APIのルーティング、リクエストの処理など、開発者がAPIを作成する際に便利な機能を提供します。
代表的なWebフレームワークには、Express.js（Node.js向け）、Django（Python向け）、Ruby on Rails（Ruby向け）、ASP.NET（C#向け）などがあります。
ライブラリ
開発には、APIの作成や操作をサポートするためのライブラリやツールも使用されます。例えば、HTTPリクエストの送信やレスポンスの処理には、Axios（JavaScript）、Requests（Python）、RestSharp（C#）などのHTTPクライアントライブラリが利用されます。
具体的なライブラリは使用する言語やフレームワークに依存します。各言語の解説書などを参照して、使用してください。
Web APIを活用することによる効果
一般的にWeb APIを活用により以下の効果があると言われています。
- 手動で実施していた操作を自動化する → 効率の向上、時間の節約
- プログラムから実施することで人の手を介在しない → 正確性の向上、一貫性の確保
- 他サービスやプラットフォームと連携できる→ 拡張性の向上
次の章で実際に TimeTracker NXにてWeb APIを活用する例を紹介します。
本章で説明した効果も含まれていますので、あわせて確認してください。
TimeTracker NX Web APIの活用例
- 例1：実績工数を他システムから定期的に反映する
TimeTracker NXを新しく導入しても既に他システムに実績工数を入力している場合は二重で入力することになりますが、これは避けたいところです。
Web APIを活用することにより、他システムに入力した実績工数のデータをTimeTracker NXに自動的に取り込むことができます。
さらに、この処理を定期的に実行する仕組みを作ればデータの入力先を一か所に集約することができ、利用者の負担は増えません。
- 使用するAPI
- ユーザーの取得 GET /system/users/{userIds}
- プロジェクトの取得 GET /project/projects/{projectIds}
- ワークアイテムの取得 GET /workitem/workItems/{workItemIds}
- 実績工数の追加 POST /system/users/{userId}/timeEntries
- サンプルスクリプトの紹介ページhttps://docs.timetracker.jp/webapi/sample/code/register-actual-time
- 例2：実績工数データを他の管理システムに反映する
TimeTracker NXで入力された実績工数は、社内の採算管理や勤怠管理にとっても重要なデータです。
Web APIを活用することでＴｉｍｅＴｒａｃｋｅｒ ＮＸ に蓄積した実績工数データを、社内で運用している他のシステムに簡単に取り込むことができます。
- 使用するAPI
- ユーザーの取得 GET /system/users/{userIds}
- 実績工数の追加 GET /system/users/{userId}/timeEntries/{timeEntryIds}
- サンプルスクリプトの紹介ページ
https://docs.timetracker.jp/webapi/sample/code/export-actual-time
- 例3：プロジェクト単位で当該期間の工数を出力する
TimeTracker NXのダッシュボードに表示する工数やワークアイテム件数のデータも、Web APIを用いることで手軽に他の用途に再利用できます。
報告資料にデータを取り込んだり、自社の業務システムで統合管理をしたりと、様々な用途に活用できます。
- 使用するAPI
- 工数分析データの取得 POST /analytics/timeEntities
- サンプルスクリプトの紹介ページ
https://docs.timetracker.jp/webapi/docs/reference/analytics/timeEntities/postTimeEntities
TimeTracker NX Web APIの注意点
セキュリティリスクへの対応
Web APIの使用においては、セキュリティと認証に関する注意が必要です。HTTPSを使用して通信を暗号化し、データのセキュリティを確保しましょう。HTTPプロトコルでサーバーにアクセスする場合、データの内容は平文でサーバーに送信されるため、データが外部に流出するリスクがあります。必要に応じて、トークンベースの認証メカニズムやOAuthなどの認証プロトコルを使用して、APIへのアクセスを制御することも推奨されます。
TimeTracker NXではトークン認証に対応しているため、トークンを安全に管理し、不正なアクセスから保護することが重要です。
ドキュメントの確認
Web APIを使用する前に、リファレンスなど利用方法が記載されたドキュメントを詳しく確認しましょう。
利用可能なAPI、メソッドやパラメータ、応答の形式な度を理解することが重要です。
また、APIのバージョンによりAPIの振る舞いやパラメータが変わることもあります。利用するバージョンに対応したドキュメントを確認しましょう。
TimeTracker NXでは、Web APIリファレンス(※)を公開しており、バージョンアップ時も変更前のバージョンで使っていた機能やパラメータを踏襲するため安全です。（仮に既存動作に影響がある変更が発生する場合には、リリースのご案内にてご連絡します）
※TimeTracker NX のWeb APIドキュメント：https://docs.timetracker.jp/webapi/
サーバーマシンの処理負荷
Web APIを使用する場合、意図せずサーバーマシンに負荷をかけてしまい、サービスを提供できない状態に陥る（最悪の場合はサーバーマシンがダウンする）ことがあります。特に、Web APIはプログラムから実行することが可能であり、短い時間で多数のリクエストを送ってしまうことが主な要因として挙げられます。
Web API実行時は以下の点を注意することが重要です。
リクエスト数の制限（レート制限）の順守
提供元のサービスが設定しているリクエスト数の制限に従う必要があります。過度なリクエストの送信や高負荷状態を引き起こす処理は避け、APIの利用ポリシーに従ってリクエストの頻度や制限に注意しましょう。
TimeTracker NX では、目安としてWeb APIの呼び出し間隔を最低でも100msは空け、Web API利用時はサーバーマシンの処理負荷を監視して過度な負荷をかけない運用を推奨しています。
キャッシングの活用
頻繁に変化しないデータやリソースの場合、キャッシングを活用することでリクエストの呼び出し回数を抑え、サーバーマシンの処理負荷を軽減します。
TimeTracker NXでは『ユーザー数』や『プロジェクト数』などのデータは、一連のWeb APIの処理中には変わらないことが多いです。１度取得した情報をプログラム内の変数で保存し、再度呼び出さない方法があります。
リクエスト情報の最適化
Web APIの利用においては、不要なリクエストや冗長なデータの送信を避けることが重要です。必要なデータのみを要求し、レスポンスに含まれるデータのサイズを最小限に抑えるようにしましょう。
TimeTracker NX には各プロジェクトの「ルートアイテム」があり、このアイテムに対して処理するとプロジェクト内のすべてのアイテムを検索／特定するため、サーバーマシンに負荷がかかります。必要なデータを抽出する条件を指定することで、処理するデータ量を減らし、サーバーマシンにかかる負荷を抑えることができます。
まとめ
今回の記事では、TimeTracker NXに搭載されているWeb APIの活用について紹介しました。使い方次第では、様々な自動化が実現できます。
活用例でもご紹介した「他システムとの連携」や「集計」の処理を、実際にWeb APIを活用して自動化にチャレンジしてみてください。
既にTimeTracker NXを利用されている方でWeb APIをまだ使ったことがないという方は、これを機にWeb APIを活用してみてはいかがでしょうか？
保守契約をご契約の方は、サポートチームでWeb APIの使い方をサポートいたします。お気軽にお問い合わせください。