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

# 스트리밍 API

:::tip

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

:::

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

## 스트림에 접속하기

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

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

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

여기서,

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

:::tip

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

:::

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

\*\*스트림상에서 주고 받는 정보는 모두 JSON입니다.어떠한 채널이 있는 지는, [채널 목록](./channel/index.md)를 참조해 주세요.

## 채널에 접속하기

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

:::tip

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

:::

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

### 채널에 접속하기

채널에 연결하려면 다음과 같은 데이터를 JSON으로 스트림에 전송합니다.

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

여기서,

- `channel`에는 접속하고자 하는 채널명을 입력합니다.[채널 목록](./channel/index.md)를 참고하세요.
- `id`에는 해당 채널과 상호작용할 수 있는 임의의 ID를 설정합니다.스트림에는 다양한 메시지가 흘러나오기 때문에 어떤 채널에서 온 메시지인지 식별해야 하기 때문입니다.이 ID는 UUID나 난수 같은 것이 될 수 있습니다.
- `params`는 채널에 연결할 때의 파라미터입니다.채널에 따라 연결 시 필요한 파라미터가 다릅니다.파라미터가 필요 없는 채널에 연결할 때는 이 속성을 생략할 수 있습니다.

:::tip

ID는 채널 단위가 아니라 '채널 연결 단위'입니다.왜냐하면 같은 채널에 서로 다른 파라미터로 다중접속 하는 경우도 있기 때문입니다.

:::

### 채널에서 메시지 받기

예를 들어, 타임라인 채널의 경우 새로운 게시물이 올라오면 메시지를 발신합니다.해당 메시지를 받으면 타임라인에 새로운 게시물이 올라왔다는 것을 실시간으로 알 수 있습니다.

채널이 메시지를 보내면 다음과 같은 데이터가 JSON으로 스트림에 유입됩니다.

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

여기서,

- `id`에는 앞서 언급한 해당 채널에 접속할 때 설정한 ID가 설정되어 있습니다.이제 이 메시지가 어느 채널에서 온 것인지 알 수 있습니다.
- `type`에는 메시지 종류가 설정됩니다.채널에 따라 어떤 종류의 메시지가 흘러나오는지는 달라질 수 있습니다.
- `body`에는 메시지 내용이 설정됩니다.채널에 따라 어떤 내용의 메시지가 흘러나오는지는 달라질 수 있습니다.

### 채널에 메시지 보내기

채널에 따라서는 메시지를 받을 수 있을 뿐만 아니라, 여기에서 메시지를 보내거나 어떤 조작을 할 수 있는 경우도 있습니다.

채널에 메시지를 보내려면 다음과 같은 데이터를 JSON으로 스트림에 전송합니다.

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

여기서,

- `id`에는 앞서 설명한 해당 채널에 접속할 때 설정한 ID를 설정합니다.이제 이 메시지가 어떤 채널을 대상으로 하는 메시지인지 식별할 수 있습니다.
- `type`에는 메시지 종류를 설정합니다.채널에 따라 어떤 종류의 메시지를 받을 수 있는지는 달라질 수 있습니다.
- `body`에는 메시지 내용을 설정합니다.채널에 따라 어떤 내용의 메시지를 받아들이는지는 달라질 수 있습니다.

### 채널 연결 끊기

채널에서 연결을 끊으려면 다음과 같은 데이터를 JSON으로 스트림에 전송합니다.

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

여기서,

- `id`에는 앞서 설명한 해당 채널에 접속할 때 설정한 ID를 설정합니다.

## 게시물 캡처

Misskey는 게시물 캡쳐라는 메커니즘을 제공하고 있습니다.지정한 게시물의 이벤트를 스트림으로 받아볼 수 있는 기능입니다.

예를 들어 타임라인을 가져와서 사용자에게 보여줬다고 가정해 봅시다.여기서 누군가가 해당 타임라인에 포함된 어떤 게시물에 리액션을 했다고 가정해봅시다.
하지만 클라이언트 입장에서는 어떤 게시물에 리액션이 붙었다는 것을 알 길이 없기 때문에 실시간으로 리액션을 타임라인의 게시물에 반영하여 표시하는 등의 작업을 할 수 없습니다.

이 문제를 해결하기 위해 Misskey는 게시물 캡처 기능을 제공하고 있습니다.게시물을 캡처하면 해당 게시물에 대한 이벤트를 수신할 수 있기 때문에 실시간으로 반응을 반영할 수 있습니다.

아래에서는 게시물 캡처 기능을 사용하는 방법을 설명합니다.어떤 캡처 이벤트가 있는지는 [캡처 이벤트 목록](./note-capture-events.md)에서 확인할 수 있습니다.

### 게시물 캡처하기

게시물을 캡처하려면 스트림에 다음과 같은 메시지를 보냅니다.

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

해당 게시물이 더 이상 화면에 표시되지 않거나, 해당 게시물에 대한 이벤트를 더 이상 받을 필요가 없을 때는 캡처 해제를 신청하세요.

- `id`에 캡처하고자 하는 게시물의 `id`를 설정합니다.

이 메시지를 보내면 Misskey에 캡쳐를 요청하는 것이며, 이후 해당 게시물에 대한 이벤트가 흘러나오게 됩니다.

여기서,

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

이 메시지를 보내면 이후 해당 게시물에 대한 이벤트가 발생하지 않습니다.

- `body` 내의 `id`에는 이벤트를 발생시킨 게시물의 ID가 설정됩니다.
- `body` 내의 `type`에는 이벤트의 종류가 설정됩니다.
- `body` 내의 `body`에는 이벤트의 세부 정보가 설정됩니다.

### 게시물 캡쳐 해제하기

해당 게시물이 더 이상 화면에 표시되지 않거나, 해당 게시물에 대한 이벤트를 더 이상 받을 필요가 없을 때는 캡처 해제를 신청하세요.

다음 메시지를 보냅니다:

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

여기서,

- `id`에 캡처를 해제하고 싶은 게시물의 `id`를 설정합니다.

이 메시지를 보내면 이후 해당 게시물에 대한 이벤트가 발생하지 않습니다.