Discourse API を使用して Data Explorer クエリを実行する

[Discourse]

<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

[37Rb (Ryan)]

@simon

CSVエクスポートのlimit=ALLサポート

このコメントは、APIからCSVエクスポートができることを示唆しているようです。それは可能ですか？CSVとしてデータが必要なので、単に興味があります。JSONとして取得してCSVに変換することは常にできますが、CSVを取得する組み込みの方法があれば、もう少し簡単になります。

[francis_exalate (Francis Martens (Exalate))]

「過去50秒間に作成または更新された」というクエリを実行することは可能ですか？

[Canapin (Coin-coin le Canapin)]

AI says

-- [params]
-- int :seconds = 50

SELECT
    p.id AS post_id,
    p.created_at,
    p.updated_at,
    p.raw AS post_content,
    p.user_id,
    t.title AS topic_title,
    t.id AS topic_id
FROM posts p
INNER JOIN topics t ON t.id = p.topic_id
WHERE
    (EXTRACT(EPOCH FROM (NOW() - p.created_at)) <= :seconds
    OR EXTRACT(EPOCH FROM (NOW() - p.updated_at)) <= :seconds)
    AND p.deleted_at IS NULL
    AND t.deleted_at IS NULL
ORDER BY p.created_at DESC
LIMIT 50

簡単なテストをしたところ、動作するようです

[Moin]

投稿に追加した「いいね 」が表示されません。

post_actions を使用する必要があると思います。

--[params]
--string :timespan = 50 seconds

SELECT post_id,
       user_id,
       created_at,
       updated_at,
       deleted_at
FROM  post_actions
WHERE post_action_type_id=2 AND updated_at > NOW() - INTERVAL :timespan

より見栄えの良い結果が得られるバージョン

--[params]
--string :timespan = 50 seconds
--boolean :include_in_timespan_deleted = false

SELECT
  post_id,
  user_id,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400), ' days ago')
  END AS relative_created_at,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 86400), ' days ago')
  END AS relative_updated_at,
  CASE
    WHEN deleted_at IS NULL THEN 'no'
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 86400), ' days ago')
  END AS relative_deleted_at
FROM
  post_actions
WHERE
  post_action_type_id = 2
  AND updated_at > NOW() - INTERVAL :timespan
  AND (
    :include_in_timespan_deleted = false
    OR (deleted_at IS NOT NULL AND deleted_at > NOW() - INTERVAL :timespan)
  )

[Canapin (Coin-coin le Canapin)]

ああ、読み間違えました！「作成または更新された最後の50秒」のようなクエリを実行できますか？

（一重引用符の位置に注意してください）

[francis_exalate (Francis Martens (Exalate))]

皆さん、ありがとうございます。

ask.discourse が私をここに誘導したので、ここに投稿しました。
API がこの機能を提供しているかどうかを知りたいのです。

[Canapin (Coin-coin le Canapin)]

はい、もちろんです。

データエクスプローラーでクエリを作成し、このガイドで説明されているようにAPI経由でクエリを実行します。

MoinのクエリをAPI経由で実行したところ、期待どおりの結果が正しく返されました。

[tanya_byrne (kukulaka)]

私もこれについて疑問に思っていました。API経由でデータをエクスポートする方法はJSONだけですか、それともData ExplorerではCSVエクスポートもサポートされていますか？

[francis_exalate (Francis Martens (Exalate))]

皆さん、ありがとうございます。

返信が遅くなり申し訳ありません。少しの間オフラインでした。

現在行っているのは、今日作成されたすべてのトピック/投稿を検索し、タイムスタンプより前に更新されたトピック/投稿を除外することです。

[Canapin (Coin-coin le Canapin)]

@francis_exalate

現在行っているのは、今日作成されたすべてのトピック/投稿を検索し、タイムスタンプより前に更新されたトピック/投稿を除外することです。

自分でやりたくない場合は、ask.discourse.com のボットに尋ねることができます。通常、Discourse 関連の SQL クエリに関してはかなり正確です（ただし、正しいと 仮定 せずに、コードを確認して確実にしてください）。

[srinivas.chilukuri]

@Discourse

-H "Content-Type: multipart/form-data; `

---

Content-Type ヘッダーは正しいですか？
開発者ツールで、パラメータ付きのData Explorerクエリを検査すると、Content-Type ヘッダーは次のように表示されます。

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

しかし、現在の cURL コマンドには次が含まれています。

-H "Content-Type: multipart/form-data;"

---

[blake (Blake Erickson)]

• multipart/form-data
• application/x-www-form-urlencoded
• application/json

は、APIリクエストを行う際に使用できる有効なコンテンツタイプです。

[srinivas.chilukuri]

@blake
language python
library requests
APIサンプルData Explorerクエリを、3つのパラメータを含めて提供していただけますか？
パラメータは、paramsを厳密に二重引用符で囲む必要があると記載されているTopicを参照してください。

[blake (Blake Erickson)]

はい、Python を使用した例を次に示します。

import json
import requests

API_KEY      = "YOUR_API_KEY"
API_USERNAME = "system"
QUERY_ID     = 20
SITE_URL     = "https://your-site-url"

# すべての値は文字列である必要があります
params = {
    "user_id":   "2",
    "viewed_at": "2019-06-10",
    "limit":     "5"
}

# Data Explorer は params を JSON エンコードされた文字列として期待します
payload = {
    "params": json.dumps(params)
}

url = f"{SITE_URL}/admin/plugins/explorer/queries/{QUERY_ID}/run"
headers = {
    "Api-Key":       API_KEY,
    "Api-Username":  API_USERNAME,
    "Content-Type":  "application/json"
}

r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
print(r.json())