このガイドでは、Discourse API を使用して、Data Explorer プラグインでクエリを作成、実行、管理する方法について説明します。
必要なユーザーレベル: 管理者
Discourse ユーザーインターフェースから実行できるアクションは、事実上すべて Discourse API を使用してトリガーできます。
このドキュメントでは、特に Data Explorer プラグインと連携して API を利用するための包括的な概要を提供します。
アクションに適した API リクエストを見つける方法の一般的な概要については、Reverse engineer the Discourse API を参照してください。
Data Explorer クエリの実行
API を介して Data Explorer クエリを実行するには、/admin/plugins/discourse-data-explorer/queries/<query-id>/run に対して POST リクエストを送信します。クエリ ID は、Discourse サイトでアクセスし、アドレスバーの id パラメータを確認することで見つけることができます。
以下は、ID が 20 のクエリの例で、指定された日付の閲覧数に基づいてトピックを返します。
--[params]
-- date :viewed_at
SELECT
topic_id,
COUNT(1) AS views_for_date
FROM topic_views
WHERE viewed_at = :viewed_at
GROUP BY topic_id
ORDER BY views_for_date DESC
このクエリは、ターミナルから次のコマンドで実行できます。
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
<api-key> と <your-site-url> を、ご自身の API キーとドメインに置き換える必要があることに注意してください。
大規模データセットの処理
Data Explorer プラグインは、JSON の結果をデフォルトで 1000 行に制限しています（非表示のサイト設定 data_explorer_query_result_limit で制御されます）。リクエストごとに limit パラメータを渡すことで、これを上書きでき、最大 10,000 行まで指定できます。
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F "limit=5000"
10,000 行を超えるデータセットの場合、SQL レベルでページネーションを行う必要があります。以下の例のクエリを使用できます。
--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT *
FROM generate_series(1, 10000)
OFFSET :page * :limit
LIMIT :limit
結果をページごとに取得するには、リクエスト内の page パラメータをインクリメントします。
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}'
result_count がゼロになったら停止します。
大規模データセットの処理に関する追加情報については、Result Limits and Exporting Queries を参照してください。
結果からの relations データの削除
Data Explorer クエリがユーザーインターフェースを介して実行されると、結果に relations オブジェクトが追加されます。このデータは UI 結果でユーザーを描画するために使用されますが、API を介してクエリを実行する場合には必要になることはほとんどありません。
そのデータを結果から削除するには、リクエストに download=true パラメータを追加します。
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}' \
-F "download=true"
API 認証
リクエスト用の API キーを生成する詳細については、こちらを参照してください: Create and configure an API key 。
API キーが Data Explorer クエリの実行にのみ使用される場合、スコープのドロップダウンメニューで「Granular」を選択し、次に「run queries」スコープを選択できます。
FAQ
レポートのリストとその ID 番号を取得できる API エンドポイントはありますか？ドロップダウンを作成したいのです。
はい、認証済みの GET リクエストを /admin/plugins/discourse-data-explorer/queries.json に対して送信すると、サイト上のすべてのクエリのリストを取得できます。
API を介してクエリを作成することは可能ですか？
はい。その方法に関するドキュメントは、Create a Data Explorer query using the API にあります。
POST リクエストでパラメータを送信することは可能ですか？
はい。例に示されているように、-F オプションを使用して SQL パラメータを含めます。
クエリの CSV エクスポートは API でサポートされていますか？
はい。結果を CSV 形式で取得するには、実行エンドポイントの URL に .csv を追加します。
curl -X POST "https://your-site-url/admin/plugins/discourse-data-explorer/queries/20/run.csv" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'
CSV レスポンスは、デフォルトで最大 10,000 行を返します。limit パラメータを渡して、この数を減らすことができます。