monkeeShark/src/docs/ko-KR/stream.md

스트리밍 API

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

스트림에 접속하기

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

아래 URL에, i 라고 하는 매개변수명으로 인증 정보를 포함해서, websocket에 접속해주세요. 예:

%WS_URL%/streaming?i=xxxxxxxxxxxxxxx

인증 정보는 자신의 API 키나 애플리케이션에서 스트림에 접속할 때, 사용자의 접속 토큰을 뜻합니다.

인증 정보 발급에 대해서는, 해당 문서를 참고해 주세요.

---

인증 정보는 생략할 수 있지만, 이렇게 하면 게스트로 작동하기 때문에, 수신할 수 있는 정보나 조작이 한정됩니다. 예:

%WS_URL%/streaming

---

스트림에 접속하면, 뒤에서 서술하는 API 조작 및 노트 구독을 할 수 있습니다. 그러나 아직 이 단계에서는, 타임라인에 새로운 노트를 확인하는 등의 행동을 할 수 없습니다. 이것을 하기 위해서는, 스트림 상에서 후술하는 채널에 접속할 필요가 있습니다.

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

채널

Misskey의 스트리밍 API에는 채널이라는 개념이 있습니다. 이것은 송수신하는 정보를 분리하기 위한 구조입니다. Misskey의 스트림 연결만으로는, 아직 실시간으로 타임라인의 노트를 수신할 수 없습니다. 스트림 상에서 채널에 접속함으로써, 다양한 정보를 받거나 보낼 수 있게 됩니다.

채널에 접속하기

채널에 접속하려면, 다음 데이터를 JSON으로 스트림에 전송합니다:

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

여기서,

• channel에는 접속하고자 하는 채널명을 입력합니다. 채널의 종류에 대해서는 후술하겠습니다.
• id에는 해당 채널과 주고받기 위한 임의의 ID를 입력합니다. 스트림에서는 다양한 메시지가 나오기 때문에, 그 메시지가 어떤 채널에서 나오는 것인지 식별할 수 있어야 합니다. ID는 UUID나 난수 같은 것이면 됩니다.
• params는 채널에 접속할 때의 매개변수입니다. 채널에 따라서 접속 시 필요한 매개변수는 다릅니다. 매개변수가 필요없는 채널에 접속할 때는, 이 속성은 생략할 수 있습니다.

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를 입력합니다.

스트림을 경유하여 API 요청하기

스트림을 통해 API를 요청하면, HTTP 요청을 발생시키지 않고 API를 이용할 수 있습니다. 이렇게 하면, 코드를 간결하게 만들거나, 성능을 향상시킬 수 있을지도 모릅니다.

스트림을 통해 API를 요청하려면, 다음 데이터를 JSON으로 스트림에 전송합니다:

{
    type: 'api',
    body: {
        id: 'xxxxxxxxxxxxxxxx',
        endpoint: 'notes/create',
        data: {
            text: 'yee haw!'
        }
    }
}

여기서,

• id에는 API의 응답을 식별할 수 있는 API 요청별 핵심 ID를 입력해야 합니다. UUID나 간단한 난수 같은 것으로 설정해도 됩니다.
• endpoint에는 내가 요청하려는 API의 엔드포인트를 입력합니다.
• data에는 엔드포인트의 매개변수를 입력합니다.

API의 엔드포인트 및 매개변수는 API 레퍼런스를 확인하시기 바랍니다.

응답 수신

API로 요청하면, 응답이 스트림에서 다음 형식으로 전달됩니다.

{
    type: 'api:xxxxxxxxxxxxxxxx',
    body: {
        ...
    }
}

여기서,

• xxxxxxxxxxxxxxxx 부분에는, 요청 시 설정된 id가 포함되어 있습니다. 이를 통해, 어떤 요청에 대한 응답인지 판별할 수 있습니다.
• body에는 응답이 포함되어 있습니다.

노트 캡처

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에는 이벤트의 상세 내용이 포함됩니다.

이벤트의 종류

reacted

해당 노트에 리액션이 올라갔을 때 발생합니다.

• reaction에 리액션 종류가 포함됩니다.
• userId에 리액션을 한 유저의 ID가 포함됩니다.

예:

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

deleted

해당 노트가 삭제되었을 때 발생합니다.

• deletedAt에 삭제한 날짜가 포함됩니다.

예:

{
    type: 'noteUpdated',
    body: {
        id: 'xxxxxxxxxxxxxxxx',
        type: 'deleted',
        body: {
            deletedAt: '2018-10-22T02:17:09.703Z'
        }
    }
}

pollVoted

해당 노트에 첨부된 투표에 투표했을 때 발생합니다.

• choice에 선택 항목의 ID가 포함됩니다.
• userId에 투표한 유저의 ID가 포함됩니다.

예:

{
    type: 'noteUpdated',
    body: {
        id: 'xxxxxxxxxxxxxxxx',
        type: 'pollVoted',
        body: {
            choice: 2,
            userId: 'yyyyyyyyyyyyyyyy'
        }
    }
}

노트 캡처 해제

노트가 더 이상 화면에 표시되지 않는 등의 이유로, 해당 노트에 대한 이벤트를 받을 필요가 없을 때는, 캡처 해제를 진행해 주세요.

아래 메시지를 보냅니다:

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

여기서,

• id에 캡처를 해제하고자 하는 노트의 id를 입력합니다.

이 메시지를 보내면, 더 이상 해당 노트에 대한 이벤트는 발생하지 않습니다.

채널 목록

main

계정에 대한 기본적인 정보를 표시됩니다. 이 채널에 대응하는 매개변수는 없습니다.

발생하는 이벤트 목록

renote

내 노트가 Renote 되었을 때 발생하는 이벤트입니다. 내가 올린 노트를 Renote 했을 때는 발생하지 않습니다.

mention

다른 사람이 나를 멘션 했을 때 발생하는 이벤트입니다.

readAllNotifications

나에게 온 알림을 모두 읽었음을 나타내는 이벤트입니다. 이 이벤트를 이용해, 「알림이 있음을 나타내는 아이콘」과 같은 것을 끄는 등의 활용이 가능합니다.

meUpdated

내 정보가 업데이트 되었음을 나타내는 이벤트입니다.

follow

내가 누군가를 팔로우 했을 때 발생하는 이벤트입니다.

unfollow

내가 누군가를 언팔로우 했을 때 발생하는 이벤트입니다.

followed

다른 사람이 나를 팔로우 했을 때 발생하는 이벤트입니다.

homeTimeline

홈 타임라인에 게시된 정보가 표시됩니다. 이 채널에 대응하는 매개변수는 없습니다.

발생하는 이벤트 목록

note

타임라인에 새로운 노트가 올라왔을 때 발생하는 이벤트입니다.

localTimeline

로컬 타임라인에 게시된 정보가 표시됩니다. 이 채널에 대응하는 매개변수는 없습니다.

발생하는 이벤트 목록

note

로컬 타임라인에 새로운 노트가 올라왔을 때 발생하는 이벤트입니다.

hybridTimeline

소셜 타임라인에 게시된 정보가 표시됩니다. 이 채널에 대응하는 매개변수는 없습니다.

발생하는 이벤트 목록

note

소셜 타임라인에 새로운 노트가 올라왔을 때 발생하는 이벤트입니다.

globalTimeline

글로벌 타임라인에 게시된 정보가 표시됩니다. 이 채널에 대응하는 매개변수는 없습니다.

발생하는 이벤트 목록

note

글로벌 타임라인에 새로운 노트가 올라왔을 때 발생하는 이벤트입니다.