Не партнёр

Главная Документация и помощь
Документация Steamworks
Обзор веб-API

Введение

В Steam встроен основанный на HTTP веб-API, который может использоваться для доступа ко многим функциям Steamworks. Этот API содержит публичные методы, доступ к которым может получить любое приложение, способное отправить HTTP-запрос, к примеру игровой клиент или сервер. Он также содержит защищённые методы, которые требуют аутентификации, к ним доступ могут получить доверенные серверные приложения.

У примеру, методы веб-API обычно используются защищённым сервером издателя в следующих целях:
  • Верификация данных учетной записи пользователя Steam на сервере
  • Проверка владения приложением
  • Сохранение или получение данных о статистиках, достижениях и счёта пользователей в списках лидеров
  • Проведение внутриигровых покупок

Полный список доступных функций веб-API Steamworks доступен здесь.

Формат запроса

Запросы к публичным функциям веб-API Steamworks отправляются как HTTP (порт 80) или HTTPS (порт 443) запросы к api.steampowered.com.
Издатели также могут отправлять запросы к работающему только для партнёров серверу веб-API здесь: https://partner.steam-api.com. Этот сервер более доступен, чем публичный, так что вы должны использовать его для всех запросов со своих защищённых серверов. Дополнительная информация здесь: Соображения об адресах узлов веб-API и брандмауэрах.

Как и API Steamworks на С++, веб-API разделён на множество интерфейсов, содержащих связанные методы. Формат URI для запроса к API таков:
https://api.steampowered.com/<interface>/<method>/v<version>/

Большинство методов поддерживают несколько обязательных и необязательных параметров. В зависимости от метода, эти параметры необходимо отправлять, используя GET или POST.

Все запросы необходимо отправлять по протоколу HTTP 1.1 с SSL версии 3.0 и 128-битным шифрованием, если возможно. Content-Type должен быть указан как application/x-www-form-urlencoded, а параметры POST должны содержаться в теле запроса в стандартном формате URL-кодирования. Текст должен быть в UTF-8.

Аутентификация

Доступ ко многим методы веб-API ограничен, для их использования потребуется уникальный ключ. См. Авторизация с помощью ключей веб-API

Параметры массива

Для некоторых методов необходим массив параметров. На это указывает постфикс [0] в названии параметра. При передаче массива указывается параметр count, который уточняет число параметров в массиве. Пример:
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

Служебные интерфейсы

В дополнение к обычным вызовам веб-API существуют служебные интерфейсы. Они подобны обычным интерфейсам с тем исключением, что все служебные функции помимо параметров GET и POST могут принимать один объект в формате JSON. Чтобы передать данные в JSON, вызовите метод веб-API с параметром input_json в следующем формате:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

Обратите внимание, что JSON должен быть закодирован в виде URL. Поля key и format по-прежнему передаются как отдельные параметры. Запросы POST также поддерживаются.

Определить, является ли метод служебным, можно по названию: если в окончании названия есть "Service", к примеру IPlayerService, это означает, что он поддерживает дополнительный метод передачи параметров. Параметры некоторых служебных методов имеют более сложную структуру и требуют альтернативный формат ввода.

Пример запроса

В следующем примере запрос возвращает 3 последние новости о Team Fortress 2.
Запрос уточняет, что ответ должен быть в формате JSON, и включает в себя обязательный параметр appid (AppID Team Fortress 2 равен 440) и необязательный параметр — число возвращаемых результатов.

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

Получение Steam ID пользователя

веб-API Steamworks идентифицирует отдельных пользователей с помощью их уникальных 64-битных Steam ID. Получение SteamID пользователя описано в разделе Аутентификация и проверка владения.

Соображения об адресах узлов веб-API и брандмауэрах

Публичный веб-API (api.steampowered.com) находится за пограничным сервером кэширования Akamai, так что IP-адреса, которые вы увидите, будут разниться в зависимости от того, где вы находитесь, а также от других факторов. IP-адреса могут часто меняться, так что если вы выполняете запросы из-за брандмауэра, ограничивающего исходящие запросы, продолжайте читать.

Для запросов с ваших защищённых серверов необходимо указывать узел https://partner.steam-api.com, который используется только партнёрами. У этого узла есть отличные от общедоступного узла свойства:
  • Доступ к этом узлу возможен только по HTTPS.
  • Этот узел не находится за пограничным сервером кэширования Akamai.
  • Каждый запрос к этому узлу должен выполняться с использованием издательского ключа, даже если запрос, не требующий ключа. Запросы без ключа вернут ошибку 403.
  • Запросы, вызывающие ошибку 403, вызовут наложение строгих ограничений на подключающийся IP. Это сделано для того, чтобы убедиться в высокой доступности узла. Если в определённый интервал отправить определённое число запросов, вызывающих ошибку 403 (либо по причине тестирования, либо из-за использования обычного ключа вместо издательского), узел временно заблокирует ваш IP.
  • Если вы отправляете запросы с узла, имеющего фильтр брандмауэра на исходящие запросы, вы должны добавить DNS 'partner.steam-api.com' в разрешённый список. Если ваш брандмауэр принимает только цифровые адреса, добавьте следующий бесклассовый адрес в разрешённый список: 208.64.200.0/22.
    Обратите внимание: не подключайтесь к серверам веб-API по IP, используйте DNS-имя. Данный адрес предоставляется только для клиентов, которым нужно добавить его в разрешённый список в брандмауэре.