Zenn
📆

[Mattermost Integrations] REST API

2021/06/19に公開
Mattermost
tech

Mattermost 記事まとめ: https://blog.kaakaa.dev/tags/mattermost/

本記事について

Mattermost の統合機能アドベントカレンダーの第 10 日目の記事です。

本記事では、Mattermost の REST API について紹介します。

REST API の概要

Mattermost には統合機能を作成するための様々な機能がありますが、一般的な REST API を利用することもできます。
Mattermost で利用可能な REST API は、下記の公式ドキュメントにまとまっています。

https://api.mattermost.com/

Access Token (Personal Access Token)

REST API を実行するには、API 実行権限を保持していることを示すための Token が必要になります。Mattermost ではいくつか Token を取得する方法がありますが、ここでは最も手軽に使える Personal Access Token を生成する方法について紹介します。

Personal Access Token を利用するには、システムコンソール > 統合機能 > 統合機能管理 > パーソナルアクセストークンを有効にするが有効になっている必要があります。

config pat

Personal Access Token 生成

メインメニュー > アカウントの設定 > セキュリティ > パーソナルアクセストークン > トークンを生成するを実行し、生成するトークンの説明を入力することで Personal Access Token を生成できます。

create pat

Personal Access Token の生成に成功すると、画面にトークンが表示されます。ここでアクセストークンと表示されている文字列を使って REST API の呼び出しを行います。(トークン IDは、Mattermost 内部でトークンを一意に識別するための ID であり、REST API の実行に利用することはできません)

complete pat

REST API 実行

先ほど生成したトークンを Authorization ヘッダーに指定し、/api/v4/users/meの API を実行することで、ユーザーの情報を取得する API を実行することができます。

$ curl -i \
>   -H 'Authorization: Bearer 4cacdozwn3fndnzobbpha3nnhy' \
>   http://localhost:8065/api/v4/users/me
HTTP/1.1 200 OK
Content-Type: application/json
Etag: 5.30.0.87x93uo8pfnzdro9ktcmobpa1r.1606000641083..0.true.true.0
Expires: 0
Vary: Accept-Encoding
X-Request-Id: qws4oo9dyjy8pxs48kaqd86goh
X-Version-Id: 5.30.0.dev.3fbba2b2e9e21536fd2bdc547afe31fd.false
Date: Sun, 22 Nov 2020 05:33:58 GMT
Content-Length: 774

{"id":"87x93uo8pfnzdro9ktcmobpa1r","create_at":1598680540414,"update_at":1606000641083,"delete_at":0,"username":"kaakaa","auth_data":"","auth_service":"","email":"kaakaa@example.com","nickname":"","first_name":"","last_name":"","position":"","roles":"system_user system_admin","allow_marketing":true,"notify_props":{"auto_responder_active":"false","auto_responder_message":"ただいま外出中のため返信できません。","channel":"true","comments":"never","desktop":"all","desktop_notification_sound":"Bing","desktop_sound":"true","email":"true","first_name":"false","mention_keys":"","push":"mention","push_status":"away"},"last_password_update":1598680540414,"locale":"ja","timezone":{"automaticTimezone":"","manualTimezone":"","useAutomaticTimezone":"true"}}

REST API 実行

REST API は種類が多いため、一部のみ実行方法を紹介します。

REST API から投稿を作成する

REST API を使って Mattermost に投稿を作成するには/postsを利用します。また、リクエストパラメータは JSON 形式のためContent-Typeヘッダーにapplication/jsonを指定し、下記のように API を実行することで投稿を作成できます。

BODY='{
  "channel_id": "uoxmk8819pyftybx6zqkij37ce",
  "message": "Create post by REST API"
}'

curl -i \
  -H 'Authorization: Bearer 4cacdozwn3fndnzobbpha3nnhy' \
  -H 'Content-Type: application/json' \
  -d "$BODY" \
  http://localhost:8065/api/v4/posts

use rest api

以下のようにpropsフィールドにattachmentsを指定することで Message Attachments を利用することもできます。

BODY='{
  "channel_id": "uoxmk8819pyftybx6zqkij37ce",
  "message": "Create post by REST API",
  "props": {
    "attachments": [{
      "text": "hoge"
    }]
  }
}'

use rest api

統計情報を取得する

/analytics/oldでは Mattermost の統計情報を取得することができます。

$ curl \
>   -H 'Authorization: Bearer 4cacdozwn3fndnzobbpha3nnhy' \
>   http://localhost:8065/api/v4/analytics/old
[
  {
    "name": "channel_open_count",
    "value": 9
  },
  {
    "name": "channel_private_count",
    "value": 1
  },
  {
    "name": "post_count",
    "value": 3696
  },
  {
    "name": "unique_user_count",
    "value": 3
  },
  {
    "name": "team_count",
    "value": 1
  },
  {
    "name": "total_websocket_connections",
    "value": 3
  },
  {
    "name": "total_master_db_connections",
    "value": 7
  },
  {
    "name": "total_read_db_connections",
    "value": 0
  },
  {
    "name": "daily_active_users",
    "value": 1
  },
  {
    "name": "monthly_active_users",
    "value": 2
  },
  {
    "name": "inactive_user_count",
    "value": 0
  }
]

name クエリにより取得する統計情報を指定することもできます。例えば、?name=post_counts_dayでは、ここ一週間の日ごとの投稿数を取得することができます。（取得する期間の指定などには対応していないようです）

$ curl \
>   -H 'Authorization: Bearer 4cacdozwn3fndnzobbpha3nnhy' \
>   http://localhost:8065/api/v4/analytics/old?name=post_counts_day
[
  {
    "name": "2020-11-19",
    "value": 11
  },
  {
    "name": "2020-11-07",
    "value": 15
  },
  {
    "name": "2020-11-04",
    "value": 29
  },
  {
    "name": "2020-11-03",
    "value": 41
  },
  {
    "name": "2020-11-02",
    "value": 5
  },
  {
    "name": "2020-11-01",
    "value": 17
  },
  {
    "name": "2020-10-31",
    "value": 25
  }
]

その他

API 実行回数の制限

大量の API リクエストの処理による高負荷状態を避けるために、REST API の頻度制限(Rate Limit)をかけることもできます。システムコンソール > 環境 > 投稿頻度制限から設定を行えます。

config rate limit

各言語向け Drivers

Mattermost REST API には各言語向けの Driver が存在します。Go と Javascript については、Mattermost が公式にサポートしています。
https://api.mattermost.com/#tag/drivers

さいごに

Mattermost REST API の使い方について紹介しました。
明日は、WebSocket API の使い方を紹介します。

Discussion