REST API

Labvanced は、参加者が研究を完了した後に Labvanced サーバーからデータを取得するための REST API を提供しています。

REST API はトークンを使用して認証されており、すべてのデータをプログラムでダウンロードできます。REST API は、データの取得を集中化し、パイプラインプロトコルに従ってデータを特定の場所に保存したい組織や学術研究機関に最適です。手動でデータを選択してダウンロードし、ローカルに保存する代わりに、これにより組織は自社のサーバーでデータにアクセスでき、GDPR プロトコルにも重要です。

REST エンドポイントのドキュメント (Swagger UI) はこちらでご覧いただけます: https://www.labvanced.com/openapi.html

また、さまざまなプログラミング言語用のクライアントコードを自動生成するために使用できる OpenAPI 仕様も提供しています (例: Postman のようなツールで): https://www.labvanced.com/labvanced-openapi.json

API トークンの作成

これはセキュリティが確保された API であり、データにアクセスするためには Labvanced で生成されたトークンを使用してアクセスを検証する必要があります。

トークンを作成するには、Labvanced アプリにログインし、メニューの左側にある「マイアカウント」タブに移動します。

「API 認証情報」というセクションがあり、トークンを作成するには「生成」をクリックするだけです。

トークンが表示されたら、そのトークンキーをダブルクリックして全てハイライトし、Ctrl+C でコピーします。

このトークンを使用すると、あなたの研究と関連するセッションのデータにアクセスできます。

注: トークンは、研究の所有者によってセッションデータへのアクセスを提供するためにのみ生成できます。

API ドキュメント (Swagger UI) を使用した試行

API を試す最も簡単な方法は、API ドキュメント (Swagger UI) の「試してみる」機能を利用することです: https://www.labvanced.com/openapi.html

右上の「認証」をクリックします。

これにより、トークンを「値」フィールドに入力または貼り付けするように求めるダイアログボックスが開きます。

トークンを貼り付けたら、「認証」をクリックし、「閉じる」をクリックしてダイアログボックスを閉じます。

注: データの表示が終わったら、ウェブサイト右上にある「認証」をクリックし、表示されるダイアログボックスで左下に表示される「ログアウト」ボタンをクリックすることで、このセッションからログアウトできます。

API ドキュメントを使用したデータアクセスの試行

ログインしたら、以下の二つのエリアを利用して実験データにアクセスできます:

• /api/{expId}/download/{recSessionId}: このセクションでは、特定の参加者のデータにアクセスしてダウンロードできます。データをダウンロードすると、Labvanced アプリの ‘Dataview & Export’ ページにある exportSettings で指定した設定に基づいて、.csv ファイル形式で出力されます。
• /api/{expId}/sessions: 「experiment id」を入力することで、特定の実験のすべてのセッションを取得できます。

‘/api/{expId}/sessions’ からのデータ

最初に第二のエンドポイントを使用して、特定の実験内でどの録音セッション (およびそれに対応する rec_session_id) が存在するかを確認するのが最適です。 青色の /api/{expId}/sessions とラベルが付けられた第二のフィールドをクリックすると、大きなビューが開き、「試してみる」ボタンを右側でクリックします:

「試してみる」をクリックすることで、セッションデータにアクセスしたい実験 ID を指定するために「expid」フィールドに数字を入力できます。これを Labvanced の「マイスタディ」ページの「ID」列で見つけることができます。このフィールドに入力したら、「実行」をクリックします。

これを行うと、特定の実験のすべてのセッションの情報を下にスクロールして見ることができます:

応答ペイロードから rec_session_id の一つをメモして、次のセクションでその録音セッションのすべての記録データをダウンロードするために使用してください。

注: 異なる「experiment id」を入力したい場合は、右側の赤い「キャンセル」ボタンをクリックして、新しい「experiment id」を入力できるようにします。

‘recSessionId’ からのデータ

参加者のデータにアクセスしてダウンロードするには、青色の /api/{expId}/download/{recSessionId} とラベルが付けられた最初のフィールドをクリックすると、大きなビューが開き、右側の「試してみる」ボタンをクリックします:

「試してみる」をクリックすると、ダウンロードしたい「experiment id」と「rec_session_id」を指定する2つのフィールドに数字を入力できます (前のセクションを参照)。

これらの値を入力したら、「実行」をクリックすると API が実行されます。下にスクロールすると、「ファイルをダウンロード」するオプションが表示されます。

「ファイルをダウンロード」をクリックすると、2つの .csv ファイル、すなわち:

• sessions.csv
• trials.csv

が含まれる .zip がダウンロードされます。

これらのファイルには、特定のセッションと関連するトライアルデータに関するすべての関連データが含まれています。

注: 異なるセッションを取得するには、右側の赤い「キャンセル」ボタンをクリックして、新しい「experiment id」と新しい「rec_session_id」を入力できるようにします。

結論として、これらのステップにより、Labvanced で生成されたユニークでセキュアなトークンを使用してデータにアクセスし、実験データとセッションデータを表示できます。

Postman を使用して試してみる

これは、日常的に Postman (API プラットフォーム) を使用している人向けの API を試すための第二のオプションです。Labvanced API トークンは、そこでも機能します。

Labvanced API ウェブサイトに基づいて、上部フィールドに URL を入力します。

次に、キーを選択し、「値」列の下にトークンを貼り付けます。以下のようになります:

この方法で、実験のセッションデータに Postman を通じてアクセスできます。

同様のプロセスに従って、特定の参加者のファイルをダウンロードすることもできます。

これを行うと、プレビューには奇妙な文字が表示されますが、これは正常です。このコマンドはファイルを取得するためのものであり、「レスポンスを保存」と「ファイルに保存」をクリックすると、特定の参加者のデータが正常に表示されます。