jointrashposs/content/ko/docs/4.for-developers/api/streaming/1.index.md

description
스트리밍 API를 사용하면, 실시간으로 다양한 정보(예를 들어 타임라인에 새로운 노트가 올라왔다거나, 리액션을 받았거나 팔로우 되었다거나 등)를 받거나, 다양한 작업을 할 수 있습니다.

스트리밍 API

:::tip 처음에 Misskey API의 문서를 읽는 것을 추천합니다. :::

스트리밍 API를 사용하면, 실시간으로 다양한 정보(예를 들어 타임라인에 새로운 노트가 올라왔다거나, 리액션을 받았거나 팔로우 되었다거나 등)를 받거나, 다양한 작업을 할 수 있습니다.

스트림에 접속하기

스트리밍 API를 이용하려면, 먼저 Misskey 서버에 websocket으로 접속이 필요합니다.

아래 형식의 URL로 websocket에 접속합니다:

wss://{host}/streaming?i={token}

여기서,

• {host}의 부분을 접속하고 싶은 서버의 호스트명으로 바꿉니다.
• {token}의 부분은, 유저의 액세스 토큰으로 바꿉니다.

:::tip 액세스 토큰은 생략할 수 있지만, 이 경우 비로그인으로 작동하기 때문에 수신할 수 있는 정보나 조작은 제한됩니다. :::

스트림에 접속하면, 후술할 노트의 구독을 하는 것이 가능합니다. 그러나, 아직 이 단계에서는 타임라인의 새로운 노트를 확인하는 등의 행동을 할 수 없습니다. 이러한 이벤트를 수신하기 위해서는, 스트림 상에 후술할 채널에 접속해야 합니다.

스트림상에서 주고 받는 정보는 모두 JSON입니다.

채널

Misskey의 스트리밍 API에는 채널이라는 개념이 있습니다.이것은 송수신하는 정보를 분리하기 위한 구조입니다. 스트림 상에서 채널에 접속함으로써, 다양한 정보를 받거나 보낼 수 있게 됩니다.

:::tip 하나의 스트림 연결에서, 동시에 여러 개의 채널에 접속할 수 있습니다. :::

아래에서 채널의 사용 방법을 설명합니다.어떠한 채널이 있는 지는, 채널 목록를 참조해 주세요.

チャンネルに接続する

チャンネルに接続するには、次のようなデータをJSONでストリームに送信します:

{
	type: 'connect',
	body: {
		channel: 'xxxxxxxx',
		id: 'foobar',
		params: {
			...
		}
	}
}

ここで、

• channelには接続したいチャンネル名を設定します。チャンネル一覧を参照してください。
• idにはそのチャンネルとやり取りするための任意のIDを設定します。ストリームでは様々なメッセージが流れるので、そのメッセージがどのチャンネルからのものなのか識別する必要があるからです。このIDは、UUIDや、乱数のようなもので構いません。
• paramsはチャンネルに接続する際のパラメータです。チャンネルによって接続時に必要とされるパラメータは異なります。パラメータ不要のチャンネルに接続する際は、このプロパティは省略可能です。

:::tip IDはチャンネルごとではなく「チャンネルの接続ごと」です。なぜなら、同じチャンネルに異なるパラメータで複数接続するケースもあるからです。 :::

チャンネルからのメッセージを受け取る

例えばタイムラインのチャンネルなら、新しい投稿があった時にメッセージを発します。そのメッセージを受け取ることで、タイムラインに新しい投稿がされたことをリアルタイムで知ることができます。

チャンネルがメッセージを発すると、次のようなデータがJSONでストリームに流れてきます:

{
	type: 'channel',
	body: {
		id: 'foobar',
		type: 'something',
		body: {
			some: 'thing'
		}
	}
}

ここで、

• idには前述したそのチャンネルに接続する際に設定したIDが設定されています。これで、このメッセージがどのチャンネルからのものなのか知ることができます。
• typeにはメッセージの種類が設定されます。チャンネルによって、どのような種類のメッセージが流れてくるかは異なります。
• bodyにはメッセージの内容が設定されます。チャンネルによって、どのような内容のメッセージが流れてくるかは異なります。

チャンネルに向けてメッセージを送信する

チャンネルによっては、メッセージを受け取るだけでなく、こちらから何かメッセージを送信し、何らかの操作を行える場合があります。

チャンネルにメッセージを送信するには、次のようなデータをJSONでストリームに送信します:

{
	type: 'channel',
	body: {
		id: 'foobar',
		type: 'something',
		body: {
			some: 'thing'
		}
	}
}

ここで、

• idには前述したそのチャンネルに接続する際に設定したIDを設定します。これで、このメッセージがどのチャンネルに向けたものなのか識別させることができます。
• typeにはメッセージの種類を設定します。チャンネルによって、どのような種類のメッセージを受け付けるかは異なります。
• bodyにはメッセージの内容を設定します。チャンネルによって、どのような内容のメッセージを受け付けるかは異なります。

チャンネルから切断する

チャンネルから切断するには、次のようなデータをJSONでストリームに送信します:

{
	type: 'disconnect',
	body: {
		id: 'foobar'
	}
}

ここで、

• idには前述したそのチャンネルに接続する際に設定したIDを設定します。

投稿のキャプチャ

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

例えばタイムラインを取得してユーザーに表示したとします。ここで誰かがそのタイムラインに含まれるどれかの投稿に対してリアクションしたとします。 しかし、クライアントからするとある投稿にリアクションが付いたことなどは知る由がないため、リアルタイムでリアクションをタイムライン上の投稿に反映して表示するといったことができません。

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

以下では、投稿のキャプチャ機能の使用方法を説明します。どのようなキャプチャイベントがあるかは、キャプチャイベント一覧を参照してください。

投稿をキャプチャする

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

{
	type: 'subNote',
	body: {
		id: 'xxxxxxxxxxxxxxxx'
	}
}

ここで、

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

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

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

{
	type: 'noteUpdated',
	body: {
		id: 'xxxxxxxxxxxxxxxx',
		type: 'reacted',
		body: {
			reaction: 'like',
			userId: 'yyyyyyyyyyyyyyyy'
		}
	}
}

ここで、

• body内のidに、イベントを発生させた投稿のIDが設定されます。
• body内のtypeに、イベントの種類が設定されます。
• body内のbodyに、イベントの詳細が設定されます。

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

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

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

{
	type: 'unsubNote',
	body: {
		id: 'xxxxxxxxxxxxxxxx'
	}
}

ここで、

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

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