TimeTrackerApiClient 0.4.0.306

1. 概要

• TimeTrackerApiClient は、TimeTracker RX の Web API を.NET アプリから簡単に利用するための C#ライブラリを提供する SDK（ソフトウェア開発キット）です。
• TimeTrackerApiClient を用いることで、TimeTracker RX の Web API を用いたソフトウェアを容易に開発できます。（TimeTracker RX の Web API については、「はじめに」を参照ください。）

2. インストール方法

コマンドプロンプトより次のように実行してください。

> dotnet add package TimeTrackerApiClient

3. 利用方法

以下ではソフトウェア開発時のTimeTrackerApiClient の利用方法を説明します。

3.1. using ステートメントを追加する。

TimeTrackerApiClient を使用するために、まずは以下の using ステートメントを追加します。

using TimeTrackerApiClient;

3.2. TimeTrackerApiClient クラスのインスタンスを生成する。

TimeTrackerApiClient クラスは、TimeTracker RX の Web API を実行するための機能を提供します。
ユーザーは TimeTrackerApiClient クラスのインスタンスを通して API を実行できるため、まずはインスタンスを生成します。
インスタンスの生成は、TimeTrackerApiClientFactory クラス の Create メソッドを用いて行います。

var apiClient = TimeTrackerApiClientFactory.Create("https://server.example.co.jp/ttrx", "username", "password");

Create メソッドの引数には、「ベース URL、TimeTracker RX のログイン名、パスワード」を入力します。
ベース URL の形式は以下のようになります。

http(s)://サーバー名/Web サイト名

「サーバー名」は TimeTracker RX のサーバー名、「Web サイト名」は TimeTracker RX の Web サイト名です。

apiClient オブジェクトを通して Web API を実行する場合、引数で渡したベース URL に対して、引数で渡したログイン名、パスワードのユーザーで Web API を実行します。

3.3. Web API を実行する。

TimeTracker RX の Web API には、API の分類を意味するエリアと、プロジェクトやワークアイテムといった実際の操作対象となるデータ（オブジェクト）を示すリソースが存在します。
また、各リソースに対して URI が割り当てられており、その URI に対して 取得(GET)、追加(POST)、更新(PUT)、削除(DELETE) といった HTTP の標準的なメソッドを使用してリクエストを送ることで対象のリソースを操作します。

• 例：ユーザー一覧取得 API（GET /system/users）の場合
  • エリア：system
  • リソース：users
  • 実行時の URI：{ベース URL}/api/system/users

基本的な Web API の実行

TimeTrackerApiClient クラスのインスタンスを使用して TimeTracker RX の Web API を実行します。
TimeTrackerApiClient では、リソースごとにクライアントクラス（Projects リソースには ProjectsClient、WorkItems リソースには WorkItemsClient）が定義されています。
また、各クライアントクラスに、対象のリソースを取得(GET)、追加(POST)、更新(PUT)、削除(DELETE) するためのメソッドが定義されています。
TimeTrackerApiClient クラスには各クライアントクラスにアクセスするためのプロパティ（リソース名でアクセス可）が定義されており、ユーザーはリソース名と、対象のリソースを操作するためのいずれかのメソッドを指定することで Web API を実行できます。

• 例：プロジェクト一覧の取得 API（GET /project/projects）の場合

  var projects = await apiClient.Projects.Get();
  

• 例：ワークアイテムの削除 API（DELETE /workitem/workItems/{workItemIds}）の場合

  var workItem = await apiClient.WorkItems.DeleteById(user.Id);
  

  ワークアイテムの削除 API のように URI で任意の値を指定する必要がある場合、メソッドの引数で値を渡します。
  リソースの種類についてはWeb API 一覧を参照ください。

リクエスト型とレスポンス型

リクエスト型

クエリパラメータやリクエストボディの指定を許可している API のメソッドの場合、メソッド実行時に引数で「××Request」型のオブジェクトを渡すことで、クエリパラメータやリクエストボディのフィールド値を渡すことができます。
Request 型にはクエリパラメータやリクエストボディのフィールドがプロパティとして定義されており、インスタンス生成時に値を指定できます。

例えばワークアイテムの取得API（GET /workitem/workItems/{workItemIds}）にてクエリパラメータで取得するフィールドを設定する場合、以下のようにRequestオブジェクトを生成します。
※Fields パラメータなどカンマ（,）区切りの文字列を記述する際は、例のようにカンマの後ろにスペースを入れずに記述してください！

var workItemsGetByIdRequest = new WorkItemsGetByIdRequest()
{
   Fields = "Id,Name,ActualProgress,PlannedStartDate,PlannedFinishDate,PlannedTime,ActualTime"
};

また、実績工数の追加API（POST /system/users/{userId}/timeEntries）を実行する場合、リクエストボディでの「WorkItemId（ワークアイテムID）, StartTime（開始時刻）, FinishTime（終了時刻）」の指定が必須であるため、以下のようにRequestオブジェクトを生成します。

var usersTimeEntriesPostRequest = new UsersTimeEntriesPostRequest()
{
   WorkItemId = "5",
   StartTime = DateTime.Parse("2023-11-01T09:00:00"),
   FinishTime = DateTime.Parse("2023-11-01T10:00:00")
};

上で生成したRequestオブジェクトを用いて「実績工数を追加するメソッド（Users.PostTimeEntries）」を実行する例は以下の通りです。

var usersTimeEntriesPostRequest = new UsersTimeEntriesPostRequest()
{
   WorkItemId = "5",
   StartTime = DateTime.Parse("2023-11-01T09:00:00"),
   FinishTime = DateTime.Parse("2023-11-01T10:00:00")
};
var usersTimeEntriesPostResponse = await apiClient.Users.PostTimeEntries("21", usersTimeEntriesPostRequest);

それぞれの API 実行で指定できるクエリパラメータやリクエストボディのフィールドについては、Web API リファレンスを参照ください。

レスポンス型

API実行後のレスポンスには「××Response」型で返るものがあります。
Response 型にはレスポンスボディに含まれるフィールドがプロパティとして定義されています。

例えばユーザー一覧の取得API（GET /system/users）のレスポンスには「totalCount（検索条件に該当するユーザーの総数）, data（取得したユーザー一覧）」が含まれており、メソッド実行後以下のようにフィールドにアクセスできます。

var usersGetResponse = await apiClient.Users.Get();
var users = usersGetResponse.Data;

それぞれの API 実行のレスポンスに含まれるフィールドについては、Web API リファレンスを参照ください。

使用例

上記の利用方法に従って「自身の昨日の実績工数一覧を取得」する処理と実行結果は以下の通りです。

using TimeTrackerApiClient;

namespace TimeTrackerApiClient_Ex
{
   class Program
   {
      static async Task Main()
      {
         var apiClient = TimeTrackerApiClientFactory.Create("https://server.example.co.jp/ttrx", "username", "password");

         // 自身のユーザーIDの取得
         var user = await apiClient.Users.GetMe();
         var userId = user.Id;

         // 昨日の自身の実績工数一覧の取得
         var yesterday = DateTime.Today.AddDays(-1);
         var usersTimeEntriesGetRequest = new UsersTimeEntriesGetRequest()
         {
            StartDate = yesterday,
            FinishDate = yesterday
         };
         var usersTimeEntriesGetResponse = await apiClient.Users.GetTimeEntries(userId, usersTimeEntriesGetRequest);
         var actualTimeEntries = usersTimeEntriesGetResponse.Data;

         foreach(var actualTimeEntry in actualTimeEntries)
         {
            Console.WriteLine($"{actualTimeEntry.WorkItemName} : {actualTimeEntry.StartTime.ToString("HH:mm")} ～ {actualTimeEntry.FinishTime.ToString("HH:mm")}");
         }
      }
   }
}

アイテムA : 11:00 ～ 12:00
アイテムB : 13:00 ～ 14:00
アイテムC : 14:00 ～ 15:00

4. パッケージのアンインストール方法

次のコマンドを実行してください。

> dotnet remove package TimeTrackerApiClient