タイムトラッカーアプリClockifyのタイムエントリ（時間記録）をAPIでGoogleカレンダーにコピーするその1 – APIの認証を通してサンプルリクエストを送る

2022年8月27日 GAS活用法

freeeに関係ない話題ですが、Google Apps Script（以下GAS）でできる効率化の例として番外編としてfreee API以外のGASでの活用に関しても記事にしています。

今回は、「ある1日にどんな作業にどれだけ時間を使ったのか記録するタイムトラッカーアプリであるClockifyのタイムエントリ（時間記録）をGoogleカレンダーにコピーしてライフログにする」に挑戦したいと思います。

これはうまく使えばリモートワーク時代の勤怠管理やチームマネジメントにも使えるかなと思っています。

Clockify APIの認証まわりを確認する

API操作は何はともあれ、リクエストを送ってレスポンスを受け取るための前提となる認証方法を確認する必要があります。

ということで、まずは公式ドキュメントを確認します。

Clockify API Documentation

海外のSaaSやサービスのドキュメントは当然ながら英語で書かれています。DeepL翻訳などの拡張機能を使って読み込んでも良いのですが、細かい誤訳による誤解などを生じさせないために、英語のまま眺めて、わからない部分を翻訳するほうが良い気がしています。

ということで、認証は、AuthenticationだったりAuthorizationだったりしますのでこの単語を見つけます。

Clockify APIの場合は、API Key方式で、このAPI Keyさえあればリクエストを送れるようです。

すべてのリクエストには、リクエストヘッダに “X-Api-Key “を含め、APIキーを記載する必要があります。
https://clockify.me/developers-api

このAPI Keyは、Clockifyにログイン後、Profile settingsのページ下部で生成・確認できます。

Generate（生成）ボタンを押して、API Keyを控えておきます。

Time entry（時間記録）を取得したい

まず今回の連載のゴールは、ClockifyのTime entry（時間記録）をAPIで取得して、その内容や時間をGoogleカレンダーに転記することです。

そのため、まず1日のTime entryを取得することを目指します。

APIで情報取得のためのGETリクエストを送るためには、まずエンドポイントの確認からはじめます。

共通エンドポイント

多くのAPIでは、エンドポイント（リクエストを送るURL）にはデータ種別にかかわらずに共通利用する共通エンドポイントがあります。

Clockify APIにも共通エンドポイントがあります。

ドキュメントを確認すると

API Base Endpoint
API Base Endpoint for Reports
API Base Endpoint for Time Off

の3種類の共通エンドポイントがあるようですが、今回取得したいTime entryは、API Base Endpointに含まれるようです。

Time entryのエンドポイント

続いてTime entryのエンドポイントを確認します。

GETリクエストのエンドポイントが、

workspaces/{workspaceId}/user/{userId}/time-entries

と記されていますので、共通エンドポイントと組み合わせて

 https://api.clockify.me/api/v1/workspaces/{workspaceId}/user/{userId}/time-entries

がリクエストを送信するエンドポイントになります。

これを読み解くと、そもそもTime entryのリクエストには

User ID
Workspace ID

を先に取得しないといけないことがわかります。

まずはサンプルコードでリクエストを成功させる

Time entryのエンドポイントへのリクエストはやや複雑だったため、まずはAPI Keyを使ったリクエストが成功するかを確かめます。

Example request（リクエストの例）に記載のUser情報を取得するリクエスト

ドキュメントのExample request（リクエストの例）にログインユーザーの情報を確認するためのcurlコマンドが記載されています。

curl -H "content-type: application/json" -H "X-Api-Key: yourAPIkey" -X GET https://api.clockify.me/api/v1/user

curlコマンドとは、様々な通信プロトコルを通じて、コマンドライン上からデータの送受信を行うことができるコマンドです。

curlコマンドに関しては以下の記事が参考になります。

いつも隣にITのお仕事｜Windowsユーザー＆ノンプログラマー向けcurlコマンドの使い方

curlコマンドをJavaScriptに読み替える

curlコマンドは慣れないと何を書いているのかがわかりませんが、Convert curl commands to codeというサイトを使って任意のプログラミング言語に変換できます。今回は、JavaScriptに変換してみました。

fetch('https://api.clockify.me/api/v1/user', {
    headers: {
        'content-type': 'application/json',
        'X-Api-Key': 'yourAPIkey'
    }
});

JavaScriptをGASに読み替え

JavaScriptのFetch APIはGASではそのまま使用できません。HTTP・HTTPS通信をおこない、取得したレスポンスを処理するには…

のクラスを利用します。今回は、Class UrlFetchAppのfetch(url, params)メソッドが使用できるようにJavaScriptのパラメータを読み替えます。

const url = 'https://api.clockify.me/api/v1/user';
const params = {
  contentType: 'application/json',
  headers: { 'X-Api-Key': 'yourAPIkey' },
  muteHttpExceptions: true // レスポンスが失敗した場合でもエラーを出さずにHTTPResponseを返すオプション
};
UrlFetchApp.fetch(url, params); // HTTPResponse

fetch(url, params)メソッド第2引数のparamsが書き換えられています。

ログインユーザーの情報を取得するサンプルリクエスト

ということでドキュメント記載のログインユーザーの情報を取得するサンプルリクエストを送るスクリプトは以下になります。

function exampleRequest() {
  const apiKey = PropertiesService.getScriptProperties().getProperty('CLOCKIFY_API_KEY'); // API Keyはプロパティストアに格納
  const url = 'https://api.clockify.me/api/v1/user'; // Userのエンドポイント

  /* Class UrlFetchApp のリファレンスからfetch(url, params)メソッドを確認しパラメーターの書き方を読み替える */
  const params = {
    contentType: 'application/json',
    headers: { 'X-Api-Key': apiKey },
    muteHttpExceptions: true // レスポンスが失敗した場合でもエラーを出さずにHTTPResponseを返すオプション
  };
  
  const response = UrlFetchApp.fetch(url, params); // HTTPResponse
  const json = response.getContentText(); // HTTPResponseの内容の文字列 = JSON文字列
  const obj = JSON.parse(json); // JSON文字列をJSONオブジェクトにparse（解析）
  console.log(obj);
}

API Keyは、一度プロパティストアに格納し、定数apiKeyに代入しています。

こちらを実行すると…