mir.pe (일반/어두운 화면)
최근 수정 시각 : 2022-10-23 11:42:35

Discord/DiscordAPI



파일:디스코드 로고_white.svg

특징 · 사용 방법 · 배지 · · 문제점 및 사건 사고

1. 개요2. Discord HTTP API
2.1. API URL2.2. 인증(Authentication)
3. Discord Gateway API
3.1. 게이트웨이에 연결하기3.2. Gateway Commands
3.2.1. 식별(Identify)3.2.2. 재개(Resume)3.2.3. 하트비트(Heartbeat)3.2.4. 프레즌스 업데이트(Update Presence)
3.3. Gateway Events
3.3.1. Hello3.3.2. Dispatch - Ready
4. 기타
4.1. 데이터 암호화4.2. 스노우플레이크

1. 개요

2016년 4월 8일에 출시된 Discord의 공식 API이다. Discord 봇, 라이브러리를 이걸로 만들 수 있다. Discord 개발자 독스는 여기에서 볼 수 있다.

2022년 10월 23일 기준으로 최신 API 버전은 10이지만 버전 기본값은 6이다. 현재 API 버전 3, 4, 5는 중단되어 이용 불가능하다.

2. Discord HTTP API

JSON 자료 구조를 이용해 요청을 처리하는 REST API로 메시지 생성과 같은 영구적인 요청을 처리하며 Base URL은 https://discord.com/api이다.

2.1. API URL

DiscordAPI의 Base URL과 버전 번호를 https://discord.com/api/v{버전} 과 같이 조합한다. Base URL만으로 요청을 전송하면 버전 기본값으로 처리된다.

2.2. 인증(Authentication)

따로 명시되지 않은 엔드포인트를 제외하고 Authorization 헤더를 넣어야 한다. 그렇지 않으면 401 Unauthorized를 반환한다.
Authorization: {토큰유형} {토큰}


토큰의 유형은 Discord 개발자 포털에 의해 발급받은 봇의 토큰인 Bot OAuth2 승인으로 발급받은 토큰인 Bearer가 있다. 이러한 토큰은 클라이언트를 식별하는 데 사용된다.

3. Discord Gateway API

웹소켓에 기반한 API. 문자열로 이루어진 JSON 자료 구조 또는 바이너리로 이루어진 ETF로 데이터를 주고받는다. Gateway URL은 wss://gateway.discord.gg/이다. Discord에서 이벤트를 수신하고 봇을 온라인 상태로 전환하기 위해 사용된다.

게이트웨이에 연결하면 Hello 이벤트를 수신해 하트비트 간격을 저장해야 한다.

3.1. 게이트웨이에 연결하기

다음 테이블을 참고해 Gateway URL에 연결한다.
Gateway URL 쿼리 문자열 파라미터 테이블
필드
v 게이트웨이 API 버전
encoding json 또는 etf

3.2. Gateway Commands

클라이언트가 웹소켓 서버에 전송할 수 있는 명령이다.

3.2.1. 식별(Identify)

봇 클라이언트를 식별하는 데 사용된다. OP 코드는 2.
#!syntax json
{
    "op": 2,
    "d": {
        "token": "(토큰)",
        "intents": "(인텐트_플래그_값)",
        "properties": {
            "$os": "(운영_체제)",
            "$browser": "(라이브러리_이름)",
            "$device": "(라이브러리_이름)"
        }
    }
}

3.2.2. 재개(Resume)

게이트웨이에 연결했을 때 종종 연결이 끊긴다. 이때 재연결해 게이트웨이 세션을 복원하는데 사용된다. OP 코드는 6.
#!syntax json
{
    "op": 6,
    "d": {
        "token": "(토큰)",
        "seq": "(마지막으로_수신한_시퀸스_번호)",
        "session_id": "(READY_이벤트에서_수신한_세션_ID)"
    }
}

3.2.3. 하트비트(Heartbeat)

서버 연결을 유지하는데 사용된다. Hello Gateway Event에서 수신한 하트비트 간격 값을 주기로 계속 전송하지 않으면 연결이 끊긴다. OP 코드는 1.
#!syntax json
{
    "op": 1,
    "d": "(마지막으로_수신한_시퀸스_번호_또는_null)"
}

3.2.4. 프레즌스 업데이트(Update Presence)

클라이언트의 상태 및 활동을 업데이트하는데 사용된다. OP 코드는 3.
#!syntax json
{
    "op": 3,
    "d": {
        "since": "(idle_시작한_유닉스_밀리초_시간_또는_null)",
        "activities": "(Activity_오브젝트_배열)",
        "status": "(클라이언트_상태)",
        "afk": "(사용자_afk_여부)"
    }
}

3.3. Gateway Events

웹소켓 서버에서 클라이언트에 전송하는 이벤트다.

3.3.1. Hello

게이트웨이에 연결하자마자 수신하는 이벤트로 하트비트 간격과 같은 정보를 담고 있다. OP 코드는 10.
#!syntax json
{
    "op": 10,
    "d": {
        "heartbeat_interval": "(하트비트_간격_밀리초)"
    }
}

3.3.2. Dispatch - Ready

Identify에 성공 시 수신하는 이벤트로 세션 ID와 같은 정보를 담고 있다. OP 코드는 0.
#!syntax json
{
    "op": 0,
    "d": {
        "session_id": "(세션_ID)",
        "guilds": "(Unavailable_Guild_오브젝트_배열)"
    }
}

4. 기타

4.1. 데이터 암호화

HTTP API와 웹소켓 API 둘 다 TLS 1.2를 이용 중이다.

4.2. 스노우플레이크

Twitter 스노우플레이크 포맷을 활용 중이다. 이러한 스노우플레이크 ID는 자식 오브젝트가 부모 오브젝트의 ID와 동일한 것을 제외하고 서로 겹치지 않으며 JSON 자료 구조에서는 문자열로 반환된다.

분류