Discord/DiscordAPI

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에 연결한다.

3.2. Gateway Commands[편집]

---

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

3.2.1. 식별(Identify)[편집]

---

봇 클라이언트를 식별하는 데 사용된다. OP 코드는 2.

{
    "op": 2,
    "d": {
        "token": "(토큰)",
        "intents": "(인텐트_플래그_값)",
        "properties": {
            "$os": "(운영_체제)",
            "$browser": "(라이브러리_이름)",
            "$device": "(라이브러리_이름)"
        }
    }
}

3.2.2. 재개(Resume)[편집]

---

게이트웨이에 연결했을 때 종종 연결이 끊긴다. 이때 재연결해 게이트웨이 세션을 복원하는데 사용된다. OP 코드는 6.

{
    "op": 6,
    "d": {
        "token": "(토큰)",
        "seq": "(마지막으로_수신한_시퀸스_번호)",
        "session_id": "(READY_이벤트에서_수신한_세션_ID)"
    }
}

3.2.3. 하트비트(Heartbeat)[편집]

---

서버 연결을 유지하는데 사용된다. Hello Gateway Event에서 수신한 하트비트 간격 값을 주기로 계속 전송하지 않으면 연결이 끊긴다. OP 코드는 1.

{
    "op": 1,
    "d": "(마지막으로_수신한_시퀸스_번호_또는_null)"
}

3.2.4. 프레즌스 업데이트(Update Presence)[편집]

---

클라이언트의 상태 및 활동을 업데이트하는데 사용된다. OP 코드는 3.

{
    "op": 3,
    "d": {
        "since": "(idle_시작한_유닉스_밀리초_시간_또는_null)",
        "activities": "(Activity_오브젝트_배열)",
        "status": "(클라이언트_상태)",
        "afk": "(사용자_afk_여부)"
    }
}

3.3. Gateway Events[편집]

---

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

3.3.1. Hello[편집]

---

게이트웨이에 연결하자마자 수신하는 이벤트로 하트비트 간격과 같은 정보를 담고 있다. OP 코드는 10.

{
    "op": 10,
    "d": {
        "heartbeat_interval": "(하트비트_간격_밀리초)"
    }
}

3.3.2. Dispatch - Ready[편집]

---

Identify에 성공 시 수신하는 이벤트로 세션 ID와 같은 정보를 담고 있다. OP 코드는 0.

{
    "op": 0,
    "d": {
        "session_id": "(세션_ID)",
        "guilds": "(Unavailable_Guild_오브젝트_배열)"
    }
}

4. 기타[편집]

---

4.1. 데이터 암호화[편집]

---

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

4.2. 스노우플레이크[편집]

---

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