<div data-theme-toc="true"> </div>
> :bookmark: このガイドでは、Discourse API を使用して、[Data Explorer](https://meta.discourse.org/t/32566?silent=true) プラグインでクエリを作成、実行、管理する方法について説明します。
>
> :person_raising_hand: 必要なユーザーレベル: 管理者
Discourse ユーザーインターフェースから実行できるほぼすべての操作は、Discourse API を使用してトリガーすることもできます。
このドキュメントでは、特に [Data Explorer](https://meta.discourse.org/t/32566?silent=true) プラグインと連携して API を利用するための包括的な概要を提供します。
アクションに適した API リクエストを見つける方法の一般的な概要については、https://meta.discourse.org/t/how-to-reverse-engineer-the-discourse-api/20576 を参照してください。
## [Data Explorer](https://meta.discourse.org/t/32566?silent=true) クエリの実行
API を介して [Data Explorer](https://meta.discourse.org/t/32566?silent=true) クエリを実行するには、`/admin/plugins/explorer/queries/<query-id>/run` に対して `POST` リクエストを送信します。クエリ ID は、Discourse サイトからアクセスし、アドレスバーの `id` パラメータを確認することで見つけることができます。
以下は、ID が `20` のクエリの例で、指定された日付の閲覧数に基づいてトピックを返します。
``` sql
--[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/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 プラグインは、デフォルトで結果を 1000 行に制限します。より大きなデータセットをページングするには、以下のクエリ例を使用できます。
--[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/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/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 クエリの実行にのみ使用する場合、「Scope」ドロップダウンメニューから「Granular」を選択し、「run queries」スコープを選択できます。
FAQ
レポートのリストとその ID 番号を取得できる API エンドポイントはありますか？ドロップダウンを作成したいのです。
はい、認証された GET リクエストを /admin/plugins/explorer/queries.json に対して行うと、サイト上のすべてのクエリのリストを取得できます。
API 経由でクエリを作成することは可能ですか？
はい。その方法に関するドキュメントは、Create a Data Explorer query using the API にあります。
POST リクエストでパラメータを送信することは可能ですか？
はい、例に示されているように、-F オプションを使用して SQL パラメータを含めることができます。
クエリの CSV エクスポートは API でサポートされていますか？
JSON 出力が標準ですが、結果を手動で CSV に変換することは可能です。ネイティブの CSV エクスポートはサポートされなくなりました。
追加リソース
- Create a Data Explorer query using the API
- Create and configure an API key
- Reverse engineer the Discourse API
- GitHub - lee-dohm/execute-discourse-query: Executes a Discourse data-explorer query via the API