sharkey/src/docs/stream.ja.md

# ストリーミングAPI

ストリーミングAPIを使うと、リアルタイムで様々な情報(例えばタイムラインに新しい投稿が流れてきた、メッセージが届いた、フォローされた、など)を受け取ったり、HTTPリクエストを発生させることなくAPIにアクセスしたりすることができます。

ストリーミングAPIは複数の種類がありますが、ここではメインとなる「ホームストリーム」について説明します。

## ストリームに接続する

以下のURLに**websocket**接続します。
```
%URL%
```

接続する際は、`i`というパラメータ名で認証情報を含めます。例:
```
%URL%/?i=xxxxxxxxxxxxxxx
```

## ストリームを経由してAPIリクエストする

ストリームを経由してAPIリクエストすると、HTTPリクエストを発生させずにAPIを利用できます。そのため、コードを簡潔にできたり、パフォーマンスの向上を見込めるかもしれません。

ストリームを経由してAPIリクエストするには、次のようなメッセージをストリームに送信します:
```json
{
	type: 'api',
	id: 'xxxxxxxxxxxxxxxx',
	endpoint: 'notes/create',
	data: {
		text: 'yee haw!'
	}
}
```

`id`には、APIのレスポンスを識別するための、APIリクエストごとの一意なIDを設定する必要があります。UUIDや、簡単な乱数のようなもので構いません。

`endpoint`には、あなたがリクエストしたいAPIのエンドポイントを指定します。

`data`には、エンドポイントのパラメータを含めます。

<div class="ui info">
	<p><i class="fas fa-info-circle"></i> APIのエンドポイントやパラメータについてはAPIリファレンスをご確認ください。</p>
</div>

### レスポンスの受信

APIへリクエストすると、レスポンスがストリームから次のような形式で流れてきます。

```json
{
	type: 'api-res:xxxxxxxxxxxxxxxx',
	body: {
		...
	}
}
```

`xxxxxxxxxxxxxxxx`の部分には、リクエストの際に設定された`id`が含まれています。これにより、どのリクエストに対するレスポンスなのか判別することができます。

`body`には、レスポンスが含まれています。

## 投稿のキャプチャ

Misskeyは投稿のキャプチャと呼ばれる仕組みを提供しています。これは、指定した投稿のイベントをストリームで受け取る機能です。

例えばタイムラインを取得してユーザーに表示したとします。ここで誰かがそのタイムラインに含まれるどれかの投稿に対してリアクションしたとします。

しかし、クライアントからするとある投稿にリアクションが付いたことなどは知る由がないため、リアルタイムでリアクションをタイムライン上の投稿に反映して表示するといったことができません。

この問題を解決するために、Misskeyは投稿のキャプチャ機構を用意しています。投稿をキャプチャすると、その投稿に関するイベントを受け取ることができるため、リアルタイムでリアクションを反映させたりすることが可能になります。

### 投稿をキャプチャする

投稿をキャプチャするには、ストリームに次のようなメッセージを送信します:

```json
{
	type: 'capture',
	id: 'xxxxxxxxxxxxxxxx'
}
```

`id`には、キャプチャしたい投稿の`id`を設定します。

このメッセージを送信すると、Misskeyにキャプチャを要請したことになり、以後、その投稿に関するイベントが流れてくるようになります。

例えば投稿にリアクションが付いたとすると、次のようなメッセージが流れてきます:

```json
{
	type: 'note-updated',
	body: {
		note: {
			...
		}
	}
}
```

`body`内の`note`には、その投稿の最新の情報が含まれています。

### 投稿のキャプチャを解除する

その投稿がもう画面に表示されなくなったりして、その投稿に関するイベントをもう受け取る必要がなくなったときは、キャプチャの解除を申請してください。

次のメッセージを送信します:

```json
{
	type: 'decapture',
	id: 'xxxxxxxxxxxxxxxx'
}
```

`id`には、キャプチャを解除したい投稿の`id`を設定します。

このメッセージを送信すると、以後、その投稿に関するイベントは流れてこないようになります。

## 流れてくるイベント一覧

流れてくるすべてのメッセージはJSON形式で、必ず`type`というプロパティが含まれています。これにより、メッセージの種類(イベント)を判別することができます。

### `note`

タイムラインに新しい投稿が流れてきたときに発生するイベントです。

`body`プロパティの中に、投稿情報が含まれています。