Steamworks 문서
웹 API 개요

개요

Steam은 다양한 Steamworks 기능에 액세스하는 데 사용되는 HTTP 기반의 웹 API를 제공합니다. API는 게임 클라이언트 또는 서버와 같이 HTTP 요청이 가능한 모든 애플리케이션에서 액세스할 수 있는 공용 메서드를 담고 있습니다. API는 또한 인증이 필요한 보호된 메서드를 포함하며, 신뢰할 수 있는 백엔드 애플리케이션에 액세스할 수 있도록 고안되었습니다.

예를 들면, 보안 게시자 서버는 보통 웹 API 메서드를 다음과 같은 목적으로 사용합니다.
  • 해당 서버에 대한 Steam 사용자의 로그인 정보 확인
  • 사용자의 특정 애플리케이션 소유 여부 확인
  • 사용자의 통계, 도전 과제 또는 순위표 점수 설정 또는 검색
  • 게임 내 구매 진행

Steamworks 웹 API에서 제공하는 모든 메서드의 목록은 Steamworks 웹 API 참고자료에서 확인하실 수 있습니다.

요청 형식

개방형 Steamworks 웹 API는 api.steampowered.com으로 HTTP(포트 80) 또는 HTTPS(포트 443) 요청을 보내서 엑세스할 수 있습니다.
게시자인 경우, Steam은 https://partner.steam-api.com에서 호스트되는 파트너 전용 웹 API 서버도 제공합니다. 이 서비스의 목적은 개방형 호스트보다 더 큰 가용성을 제공하는 것입니다. 보안 서버에서 보내는 모든 요청에 이 서비스를 사용해야 합니다. 자세한 내용은 웹 API 호스트 주소 및 방화벽 고려 사항 문서를 참고하세요.

Steamworks C++ API와 비슷하게, 웹 API도 관련 메서드를 포함한 여러 인터페이스로 나뉩니다. 각 API에 요청에 대한 URI 형식은 다음과 같습니다.
https://api.steampowered.com/<interface>/<method>/v<version>/

대부분 메서드는 필수 및 선택적 매개변수 목록을 지원합니다. 메서드에 따라 이러한 매개변수는 반드시 요청에서 GET 또는 POST 매개변수로 전달되어야 합니다.

모든 요청은 HTTP 1.1을 사용하여 전달해야 하며, 가능한 경우 보안 TLS 연결을 사용해야 합니다. 콘텐츠 유형은 application/x-www-form-urlencoded이어야 하며, POST 매개변수는 표준 방식인 urlencoding 형식으로 요청의 본문에 있어야 합니다. 텍스트는 반드시 UTF-8로 전송되어야 합니다.

인증

많은 웹 API 메서드에는 고유한 키가 필요한 액세스 제한이 있습니다. 자세한 내용은 Authentication using Web API Keys 문서를 참고하세요.

배열 매개변수

일부 매서드는 배열로 된 매개변수가 필요합니다. 이러한 매개변수는 매개변수 이름 끝에 [0]이 지정되어 있습니다. 배열 전달 시에는 항상 배열의 매개변수 수를 지정하는 count 매개변수가 있습니다. 그 예는 다음과 같습니다.
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

서비스 인터페이스

일반 웹 API 호출 외에도 서비스 인터페이스가 있습니다. 이러한 인터페이스는 일반 인터페이스와 매우 비슷한 기능을 합니다. 주요 차이점은 모든 서비스 API는 인수를 GET 또는 POST 매개변수로 취급할 뿐만 아니라 단일 JSON BLOB으로 받는다는 것입니다. JSON으로 데이터를 전달하기 위해서는 웹 API 메서드를 다음과 같이 input_json 매개변수 세트로 호출하세요.
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

JSON은 URL로 인코딩되어 있어야 한다는 점을 참고하세요. 'key'와 'format' 필드는 이전과 같이 계속해서 별도의 매개변수로 전달되어야 합니다. POST 요청도 지원됩니다.

웹 API가 '서비스'인지 여부는인터페이스의 이름으로 구분할 수 있습니다. 인터페이스의 이름이 IPlayerService와 같이 'Service'로 끝나는 경우 매개변수 데이터를 전달하는 이 추가 메서드를 지원합니다. 일부 Service 메서드는 조금 더 복잡한 구조의 매개변수를 사용하며 이러한 대체 입력 형식이 요구됩니다.

쿼리 예시

다음 예시는 Team Fortress 2에 대한 최근 3개의 새로운 항목을 검색합니다.
이 요청은 응답이 JSON으로 반환되어야 함을 지정하고 요구되는 appid 매개변수(Team Fortress 2의 AppID는 440임) 및 반환되는 결과 수를 제한하기 위한 선택적 count 매개변수를 포함합니다.

GET /ISteamNews/GetNewsForApp/v2/?appid=440&count=3\r\n Host: api.steampowered.com/r/n Content-Length: 0\r\n\r\n

다음 링크를 통해 이 쿼리를 시행하고 결과를 확인할 수 있습니다.
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

이 특정 호출에 대한 더 자세한 정보는 ISteamNews/GetNewsForApp 문서에서 확인하실 수 있습니다.

사용자의 SteamID 받기

Steamworks 웹 API는 고유한 64비트 Steam ID를 이용하여 개별 사용자를 확인합니다. 사용자의 SteamID를 안전하게 받는 방법은 사용자 인증 및 소유권 문서에서 확인하세요.

웹 API 호스트 주소 및 방화벽 고려 사항

개방형 웹 API(api.steampowered.com)는 Akamai의 엣지 캐시 뒤에 있으므로 실제 IP 주소에 대한 이름은 귀하의 위치와 사용 중인 서비스가 변경되면 달라집니다. IP 주소는 빠르고 유동적으로 변경되므로 웹 API 호출이 아웃바운드 요청의 방화벽을 통해 이루어진 경우 꼭 확인하시기 바랍니다.

보안 서버에서 보내는 모든 요청은 파트너 전용 노드(https://partner.steam-api.com)를 사용해야 합니다. 이 호스트는 공개 호스트와는 다른 속성으로 되어 있습니다.
  • 이 호스트는 HTTPS를 통해서만 접근할 수 있습니다.
  • 이 호스트는 Akamai의 엣지 캐시 뒤에 있지 않습니다.
  • 이 호스트에 대한 모든 요청은 귀사의 게시자 웹 API 키와 함께 요청되어야 하며 일반적으로 키가 필요하지 않은 요청 또한 마찬가지입니다. 유효한 게시자 키 없이 요청한 경우 403 오류 코드가 표시됩니다.
  • 403 상태 코드를 생성하는 요청은 대개 게시자 키가 아닌 일반 웹 API 키를 사용하는 경우 발생하며, IP 주소 연결에 대한 속도 제한이 엄격해집니다. 이는 고가용성을 확보하기 위함입니다.
  • 아웃바운드 요청에 방화벽 필터를 적용힌 호스트에서 해당 API 서비스에 요청을 하는 경우, 'partner.steam-api.com' 이름으로 된 DNS를 허용 목록에 추가해야 합니다. 방화벽이 숫자로 된 주소만 지원하는 경우, CIDR 블록인 208.64.200.0/22를 허용 목록에 추가하세요.
    참고: 웹 API 서버는 IP 주소가 아닌 DNS 이름을 사용하여 연결해야 합니다. 해당 주소들은 방화벽의 허용 목록에 이러한 주소를 추가해야 하는 고객에게만 제공됩니다.

IP 주소 허용 목록

WebAPI 호출에 사용할 IP 주소를 허용 목록에 추가하실 수 있습니다. 이는 WebAPI 키가 도용된 경우를 위한 추가적인 보안 계층으로, 허용 목록에 추가된 IP 주소를 이용한 WebAPI 호출만 허용합니다. 허용 목록에 IP 주소를 추가하고 나면 허용 목록에 포함되지 않은 주소에 대한 다른 모든 요청은 차단되며 '403 - Forbidden' 오류 메시지가 표시됩니다.

허용 목록에 IP 주소를 추가하는 방법은 간단합니다. WebAPI 키를 보유하고 있는 그룹 페이지에서 'WebAPI 키 관리' 버튼을 클릭하고 지침을 따르세요.

각 WebAPI는 별도의 고유한 허용 목록이 있으며, 허용 목록에 IP 주소를 꼭 추가해야 하는 것은 아닙니다.

참고: 허용 목록을 사용하더라도 WebAPI 키에 대한 보안이 보장되는 것은 아닙니다. 키를 안전하게 보호하고 절대 공유하지 마세요. 만약 키가 도용된 경우, 즉시 변경하세요.