V7 APIを使用してカスタムレポートを生成するには、どうすればよいでしょうか？

Answer

カスタムダッシュボードを作成するには、フェッチメカニズムが使用するフレームワークとデータ可視化方法を決定する必要があります。例えば、JavaScriptを使用してAPI呼び出しでメトリックをリクエストし、Google Sheetsを仲介者として使用して、Looker Studio（Data Studio）で特定のアノテータによる平均アノテーション時間を測定するカスタムダッシュボードを設定することができます。

手順は以下の通りです：

APIリクエストを書く：ドキュメントを参照してリクエストを作成します。
APIコールをトリガーし、レスポンスを解析する：Google Apps Scriptのようなツールを使用してデータフェッチを自動化します。
結果を視覚化：Looker Studioのようなプラットフォームを利用してインタラクティブなダッシュボードを作成します。

【手順詳細】

APIリクエストを書く

始める前に、新しいAPIキーを生成し、保存しておきます。これは認証に必要です。

また、チームのスラッグ化された名前も必要です。これを見つけるには、任意のデータセットの設定タブにアクセスしてください。データセットは「/スラッグ化された名前/データセット名」の構造を使用しています。

APIキーとスラッグ化されたチーム名を入手したら、このページにアクセスしてリクエストを作成し、試すことができます。パラメータを設定し、Shell、Python、JavaScriptなどの特定のフレームワーク用のコードを生成します。

この例では、V7のデータをフェッチするためにGoogle Sheetsを使用します。そのため、自動フェッチメカニズムの設定に最適なJavaScriptを使用します。

ここでは、ユーザーごと、月ごとの合計アノテーション情報と平均アノテーション時間を取得することに興味があると仮定しましょう。
リクエストは次のようになります：

すべての情報はURLパラメータに含まれています。この場合の完全なリンクは次の通りです：

https://darwin.v7labs.com/api/v2/teams/v7-account/reports/annotation?metrics[]=total_annotations&metrics[]=time_per_item&start=2023-11-01T00%3A00%3A00Z&stop=2023-11-30T23%3A59%3A59Z&granularity=1mo&group_by=annotators

?マークの後のパラメータ、例えばmetrics[]=time_per_itemは、取得したいメトリクスを決定するために使用されます。
こちらがレスポンスです：

結果には特定のチームメンバーの名前ではなく、actor_idが含まれていることに注意してください。これはアノテータの身元を保護するためのアプローチです。しかし、固有のユーザーIDに関する情報を取得したい場合は、こちらで説明する別のAPIリクエストを使用することができます。誰が誰であるかを判断したら、次のステップでのレスポンス解析中にIDを実名に置き換えることができます。

APIコールをトリガーし、レスポンスを解析するスクリプトを書く

今回の例では、Google Sheetsを使用してV7データを取得するので、JavaScriptをベースにしたGoogle Apps Scriptを利用します。Google Apps Scriptは、Google Sheetsがネイティブでサポートしているスクリプト言語で、カスタム関数、自動化、他のGoogleサービスや外部APIとのインタラクションを作成するために使用されます。

新しいGoogle Sheetsファイルを作成し、拡張機能 > Apps Scriptに移動してコードを追加します。ステップ1で生成したリクエストは、スクリプト全体の一部に過ぎないことを覚えておいてください。異なる実装では、特定の部分を微調整したり、追加の関数を設定したりする必要があるかもしれません。しかし、ChatGPTを使用してロジックを修正し、正しいスニペットを生成することができます。

時間ベースのルールで関数をトリガーする自動化を設定することができます。例えば、データは数時間ごとに取得され、既存のセルを更新したり、スプレッドシートの新しい行に保存したりすることができます。シートにエータを詰め込みすぎたくない場合は、追加のパースロジックを使用して特定の値をより一般的な名前に変換することもできます。