mirror of
https://git.joinsharkey.org/Sharkey/Sharkey.git
synced 2024-11-27 11:03:08 +02:00
Update doc
This commit is contained in:
syuilo
parent
9a2d435cb1
commit
432e18a0c0
2 changed files with 217 additions and 65 deletions
|
|
@ -1,19 +1,14 @@
|
|||
# ストリーミングAPI
|
||||
|
||||
ストリーミングAPIを使うと、リアルタイムで様々な情報(例えばタイムラインに新しい投稿が流れてきた、メッセージが届いた、フォローされた、など)を受け取ったり、HTTPリクエストを発生させることなくAPIにアクセスしたりすることができます。
|
||||
|
||||
ストリーミングAPIは複数の種類がありますが、ここではメインとなる「ホームストリーム」について説明します。
|
||||
ストリーミングAPIを使うと、リアルタイムで様々な情報(例えばタイムラインに新しい投稿が流れてきた、メッセージが届いた、フォローされた、など)を受け取ったり、様々な操作を行ったりすることができます。
|
||||
|
||||
## ストリームに接続する
|
||||
|
||||
以下のURLに**websocket**接続します。
|
||||
```
|
||||
%URL%
|
||||
```
|
||||
ストリーミングAPIを利用するには、まずMisskeyサーバーに**websocket**接続する必要があります。
|
||||
|
||||
接続する際は、`i`というパラメータ名で認証情報を含めます。例:
|
||||
以下のURLに、`i`というパラメータ名で認証情報を含めて、websocket接続してください。例:
|
||||
```
|
||||
%URL%/?i=xxxxxxxxxxxxxxx
|
||||
%URL%/streaming?i=xxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
認証情報は、自分のAPIキーや、アプリケーションからストリームに接続する際はユーザーのアクセストークンのことを指します。
|
||||
|
|
@ -22,12 +17,116 @@
|
|||
<p><i class="fas fa-info-circle"></i> 認証情報の取得については、<a href="./api">こちらのドキュメント</a>をご確認ください。</p>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
認証情報は省略することもできますが、その場合非ログインでの利用ということになり、受信できる情報や可能な操作は限られます。例:
|
||||
|
||||
```
|
||||
%URL%/streaming
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
ストリームに接続すると、後述するAPI操作や、投稿の購読を行ったりすることができます。
|
||||
しかしまだこの段階では、例えばタイムラインへの新しい投稿を受信したりすることはできません。
|
||||
それを行うには、ストリーム上で、後述する**チャンネル**に接続する必要があります。
|
||||
|
||||
**ストリームでのやり取りはすべてJSONです。**
|
||||
|
||||
## チャンネル
|
||||
MisskeyのストリーミングAPIにはチャンネルという概念があります。これは、送受信する情報を分離するための仕組みです。
|
||||
Misskeyのストリームに接続しただけでは、まだリアルタイムでタイムラインの投稿を受信したりはできません。
|
||||
ストリーム上でチャンネルに接続することで、様々な情報を受け取ったり情報を送信したりすることができるようになります。
|
||||
|
||||
### チャンネルに接続する
|
||||
チャンネルに接続するには、次のようなデータをJSONでストリームに送信します:
|
||||
|
||||
```json
|
||||
{
|
||||
type: 'connect',
|
||||
body: {
|
||||
channel: 'xxxxxxxx',
|
||||
id: 'foobar',
|
||||
params: {
|
||||
...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ここで、
|
||||
* `channel`には接続したいチャンネル名を設定します。チャンネルの種類については後述します。
|
||||
* `id`にはそのチャンネルとやり取りするための任意のIDを設定します。ストリームでは様々なメッセージが流れるので、そのメッセージがどのチャンネルからのものなのか識別する必要があるからです。このIDは、UUIDや、乱数のようなもので構いません。
|
||||
* `params`はチャンネルに接続する際のパラメータです。チャンネルによって接続時に必要とされるパラメータは異なります。パラメータ不要のチャンネルに接続する際は、このプロパティは省略可能です。
|
||||
|
||||
<div class="ui info">
|
||||
<p><i class="fas fa-info-circle"></i> IDはチャンネルごとではなく「チャンネルの接続ごと」です。なぜなら、同じチャンネルに異なるパラメータで複数接続するケースもあるからです。</p>
|
||||
</div>
|
||||
|
||||
### チャンネルからのメッセージを受け取る
|
||||
例えばタイムラインのチャンネルなら、新しい投稿があった時にメッセージを発します。そのメッセージを受け取ることで、タイムラインに新しい投稿がされたことをリアルタイムで知ることができます。
|
||||
|
||||
チャンネルがメッセージを発すると、次のようなデータがJSONでストリームに流れてきます:
|
||||
```json
|
||||
{
|
||||
type: 'channel',
|
||||
body: {
|
||||
id: 'foobar',
|
||||
type: 'something',
|
||||
body: {
|
||||
some: 'thing'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ここで、
|
||||
* `id`には前述したそのチャンネルに接続する際に設定したIDが設定されています。これで、このメッセージがどのチャンネルからのものなのか知ることができます。
|
||||
* `type`にはメッセージの種類が設定されます。チャンネルによって、どのような種類のメッセージが流れてくるかは異なります。
|
||||
* `body`にはメッセージの内容が設定されます。チャンネルによって、どのような内容のメッセージが流れてくるかは異なります。
|
||||
|
||||
### チャンネルに向けてメッセージを送信する
|
||||
チャンネルによっては、メッセージを受け取るだけでなく、こちらから何かメッセージを送信し、何らかの操作を行える場合があります。
|
||||
|
||||
チャンネルにメッセージを送信するには、次のようなデータをJSONでストリームに送信します:
|
||||
```json
|
||||
{
|
||||
type: 'channel',
|
||||
body: {
|
||||
id: 'foobar',
|
||||
type: 'something',
|
||||
body: {
|
||||
some: 'thing'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ここで、
|
||||
* `id`には前述したそのチャンネルに接続する際に設定したIDを設定します。これで、このメッセージがどのチャンネルに向けたものなのか識別させることができます。
|
||||
* `type`にはメッセージの種類を設定します。チャンネルによって、どのような種類のメッセージを受け付けるかは異なります。
|
||||
* `body`にはメッセージの内容を設定します。チャンネルによって、どのような内容のメッセージを受け付けるかは異なります。
|
||||
|
||||
### チャンネルから切断する
|
||||
チャンネルから切断するには、次のようなデータをJSONでストリームに送信します:
|
||||
|
||||
```json
|
||||
{
|
||||
type: 'disconnect',
|
||||
body: {
|
||||
id: 'foobar'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ここで、
|
||||
* `id`には前述したそのチャンネルに接続する際に設定したIDを設定します。
|
||||
|
||||
## ストリームを経由してAPIリクエストする
|
||||
|
||||
ストリームを経由してAPIリクエストすると、HTTPリクエストを発生させずにAPIを利用できます。そのため、コードを簡潔にできたり、パフォーマンスの向上を見込めるかもしれません。
|
||||
|
||||
ストリームを経由してAPIリクエストするには、次のようなメッセージをストリームに送信します:
|
||||
ストリームを経由してAPIリクエストするには、次のようなデータをJSONでストリームに送信します:
|
||||
```json
|
||||
{
|
||||
type: 'api',
|
||||
|
|
@ -39,11 +138,10 @@
|
|||
}
|
||||
```
|
||||
|
||||
`id`には、APIのレスポンスを識別するための、APIリクエストごとの一意なIDを設定する必要があります。UUIDや、簡単な乱数のようなもので構いません。
|
||||
|
||||
`endpoint`には、あなたがリクエストしたいAPIのエンドポイントを指定します。
|
||||
|
||||
`data`には、エンドポイントのパラメータを含めます。
|
||||
ここで、
|
||||
* `id`には、APIのレスポンスを識別するための、APIリクエストごとの一意なIDを設定する必要があります。UUIDや、簡単な乱数のようなもので構いません。
|
||||
* `endpoint`には、あなたがリクエストしたいAPIのエンドポイントを指定します。
|
||||
* `data`には、エンドポイントのパラメータを含めます。
|
||||
|
||||
<div class="ui info">
|
||||
<p><i class="fas fa-info-circle"></i> APIのエンドポイントやパラメータについてはAPIリファレンスをご確認ください。</p>
|
||||
|
|
@ -62,9 +160,9 @@ APIへリクエストすると、レスポンスがストリームから次の
|
|||
}
|
||||
```
|
||||
|
||||
`xxxxxxxxxxxxxxxx`の部分には、リクエストの際に設定された`id`が含まれています。これにより、どのリクエストに対するレスポンスなのか判別することができます。
|
||||
|
||||
`body`には、レスポンスが含まれています。
|
||||
ここで、
|
||||
* `xxxxxxxxxxxxxxxx`の部分には、リクエストの際に設定された`id`が含まれています。これにより、どのリクエストに対するレスポンスなのか判別することができます。
|
||||
* `body`には、レスポンスが含まれています。
|
||||
|
||||
## 投稿のキャプチャ
|
||||
|
||||
|
|
@ -82,12 +180,15 @@ Misskeyは投稿のキャプチャと呼ばれる仕組みを提供していま
|
|||
|
||||
```json
|
||||
{
|
||||
type: 'capture',
|
||||
id: 'xxxxxxxxxxxxxxxx'
|
||||
type: 'subNote',
|
||||
body: {
|
||||
id: 'xxxxxxxxxxxxxxxx'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`id`には、キャプチャしたい投稿の`id`を設定します。
|
||||
ここで、
|
||||
* `id`にキャプチャしたい投稿の`id`を設定します。
|
||||
|
||||
このメッセージを送信すると、Misskeyにキャプチャを要請したことになり、以後、その投稿に関するイベントが流れてくるようになります。
|
||||
|
||||
|
|
@ -97,22 +198,83 @@ Misskeyは投稿のキャプチャと呼ばれる仕組みを提供していま
|
|||
{
|
||||
type: 'noteUpdated',
|
||||
body: {
|
||||
note: {
|
||||
...
|
||||
id: 'xxxxxxxxxxxxxxxx',
|
||||
type: 'reacted',
|
||||
body: {
|
||||
reaction: 'like',
|
||||
userId: 'yyyyyyyyyyyyyyyy'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`body`内の`note`には、その投稿の最新の情報が含まれています。
|
||||
ここで、
|
||||
* `body`内の`id`に、イベントを発生させた投稿のIDが設定されます。
|
||||
* `body`内の`type`に、イベントの種類が設定されます。
|
||||
* `body`内の`body`に、イベントの詳細が設定されます。
|
||||
|
||||
---
|
||||
#### イベントの種類
|
||||
|
||||
このように、投稿の情報が更新されると、`noteUpdated`イベントが流れてくるようになります。`noteUpdated`イベントが発生するのは、以下の場合です:
|
||||
##### `reacted`
|
||||
その投稿にリアクションがされた時に発生します。
|
||||
|
||||
- 投稿にリアクションが付いた
|
||||
- 投稿に添付されたアンケートに投票がされた
|
||||
- 投稿が削除された
|
||||
* `reaction`に、リアクションの種類が設定されます。
|
||||
* `userId`に、リアクションを行ったユーザーのIDが設定されます。
|
||||
|
||||
例:
|
||||
```json
|
||||
{
|
||||
type: 'noteUpdated',
|
||||
body: {
|
||||
id: 'xxxxxxxxxxxxxxxx',
|
||||
type: 'reacted',
|
||||
body: {
|
||||
reaction: 'like',
|
||||
userId: 'yyyyyyyyyyyyyyyy'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### `deleted`
|
||||
その投稿が削除された時に発生します。
|
||||
|
||||
* `deletedAt`に、削除日時が設定されます。
|
||||
|
||||
例:
|
||||
```json
|
||||
{
|
||||
type: 'noteUpdated',
|
||||
body: {
|
||||
id: 'xxxxxxxxxxxxxxxx',
|
||||
type: 'deleted',
|
||||
body: {
|
||||
deletedAt: '2018-10-22T02:17:09.703Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### `pollVoted`
|
||||
その投稿に添付されたアンケートに投票された時に発生します。
|
||||
|
||||
* `choice`に、選択肢IDが設定されます。
|
||||
* `userId`に、投票を行ったユーザーのIDが設定されます。
|
||||
|
||||
例:
|
||||
```json
|
||||
{
|
||||
type: 'noteUpdated',
|
||||
body: {
|
||||
id: 'xxxxxxxxxxxxxxxx',
|
||||
type: 'pollVoted',
|
||||
body: {
|
||||
choice: 2,
|
||||
userId: 'yyyyyyyyyyyyyyyy'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 投稿のキャプチャを解除する
|
||||
|
||||
|
|
@ -122,62 +284,49 @@ Misskeyは投稿のキャプチャと呼ばれる仕組みを提供していま
|
|||
|
||||
```json
|
||||
{
|
||||
type: 'decapture',
|
||||
id: 'xxxxxxxxxxxxxxxx'
|
||||
type: 'unsubNote',
|
||||
body: {
|
||||
id: 'xxxxxxxxxxxxxxxx'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`id`には、キャプチャを解除したい投稿の`id`を設定します。
|
||||
ここで、
|
||||
* `id`にキャプチャを解除したい投稿の`id`を設定します。
|
||||
|
||||
このメッセージを送信すると、以後、その投稿に関するイベントは流れてこないようになります。
|
||||
|
||||
## 流れてくるイベント一覧
|
||||
# チャンネル一覧
|
||||
## `main`
|
||||
アカウントに関する基本的な情報が流れてきます。このチャンネルにパラメータはありません。
|
||||
|
||||
流れてくるすべてのメッセージはJSON形式で、必ず`type`というプロパティが含まれています。これにより、メッセージの種類(イベント)を判別することができます。
|
||||
|
||||
### `note`
|
||||
|
||||
タイムラインに新しい投稿が流れてきたときに発生するイベントです。
|
||||
|
||||
`body`プロパティの中に、投稿情報が含まれています。
|
||||
|
||||
### `renote`
|
||||
### 流れてくるイベント一覧
|
||||
|
||||
#### `renote`
|
||||
自分の投稿がRenoteされた時に発生するイベントです。自分自身の投稿をRenoteしたときは発生しません。
|
||||
|
||||
`body`プロパティの中に、Renoteされた投稿情報が含まれています。
|
||||
|
||||
### `mention`
|
||||
|
||||
#### `mention`
|
||||
誰かからメンションされたときに発生するイベントです。
|
||||
|
||||
`body`プロパティの中に、投稿情報が含まれています。
|
||||
|
||||
### `readAllNotifications`
|
||||
|
||||
#### `readAllNotifications`
|
||||
自分宛ての通知がすべて既読になったことを表すイベントです。このイベントを利用して、「通知があることを示すアイコン」のようなものをオフにしたりする等のケースが想定されます。
|
||||
|
||||
### `meUpdated`
|
||||
|
||||
#### `meUpdated`
|
||||
自分の情報が更新されたことを表すイベントです。
|
||||
|
||||
`body`プロパティの中に、最新の自分のアカウントの情報が含まれています。
|
||||
|
||||
### `follow`
|
||||
|
||||
#### `follow`
|
||||
自分が誰かをフォローしたときに発生するイベントです。
|
||||
|
||||
`body`プロパティの中に、フォローしたユーザーの情報が含まれています。
|
||||
|
||||
### `unfollow`
|
||||
|
||||
#### `unfollow`
|
||||
自分が誰かのフォローを解除したときに発生するイベントです。
|
||||
|
||||
`body`プロパティの中に、フォロー解除したユーザーの情報が含まれています。
|
||||
|
||||
### `followed`
|
||||
|
||||
#### `followed`
|
||||
自分が誰かにフォローされたときに発生するイベントです。
|
||||
|
||||
`body`プロパティの中に、フォローしてきたユーザーの情報が含まれています。
|
||||
## `homeTimeline`
|
||||
ホームタイムラインの投稿情報が流れてきます。このチャンネルにパラメータはありません。
|
||||
|
||||
### 流れてくるイベント一覧
|
||||
|
||||
#### `note`
|
||||
タイムラインに新しい投稿が流れてきたときに発生するイベントです。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
@import "../client/style"
|
||||
@import "./ui"
|
||||
|
||||
html
|
||||
--primary #fb4e4e
|
||||
|
||||
body
|
||||
margin 0
|
||||
color #34495e
|
||||
|
|
|
|||
Loading…
Reference in a new issue