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

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

스트리밍 API

:::tip

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

:::

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

스트림에 접속하기

스트리밍 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를 설정합니다.

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