API EVE Online. Общая информация

Введение

В данной статье приводится общая информация о том, что из себя представляет EVE API. Полный же список функций EVE API доступен здесь.

EVE API — это технология, позволяющая сторонним разработчикам (веб-сайтам, приложениям и пр.) использовать динамическую информацию о персонажах, аккаунтах, состоянии сервера EVE Online. Все вызовы, содержащие непубличную информацию, защищены специальным кодом — уникальным для каждого аккаунта API-ключом; сгенерировать такие ключи может только владелец этого аккаунта. Посмотреть свои API-ключи можно на специальной странице официального сайта игры: support.eveonline.com/api/Key/Index. Оглавление русской версии справочника EVE API доступно здесь.

EVE API представляет из себя веб-сервер; вызывая какую-нибудь функцию API, вы, по сути, открываете веб-страницу, передавая ей (если нужно) требуемые параметры с помощью методов GET или POST, получая в ответ XML-файл с данными. Самые распространённые параметры, требуемые для вызова API-функции — keyID и vCode, узнать которые можно здесь.

Следует отметить, что keyID — идентификатор ключа — константа, генерируемая в момент создания настраиваемого ключа, а vCode — строка, которая может быть сгенерирована заново, если вам это потребуется. Так же, API-ключи бывают двух видов: персональный и корпоративный, а доступные с их помощью вызовы функций задаются специальными числовыми масками. Подробнее о настраиваемых ключах можно узнать в статье «API EVE Online. Настраиваемые ключи».

В случае отправки в запросе API-функции неправильных аргументов возвращается сообщение об ошибке.

Кэширование

Для снижения нагрузки на API-сервер, данные кэшируются с определённой периодичностью. В EVE API встречается несколько видов кэширования: длительное (Long Style Caching), краткое (Short Style Caching) и модифицированное краткое (M-Short Style Caching). Все XML-файлы, возвращаемые сервером при вызове API-функции, содержат такие параметры как currentTime и cachedUntil. Параметр currentTime показывает текущее время API-сервера, а cachedUntil информирует о времени, когда данные устареют и можно будет повторно вызвать данную функцию. В зависимости от типа кэширования, параметр cachedUntil можно понимать немного по-разному.

Long-кэширование используется такими функциями, как список принадлежащих пилоту вещей, транзакции маркета, журнал операций кошелька игрока. Получение данных из таких функций возможно один раз в период от одного до 23 часов. Чаще всего данные, возвращаемые такими функциями не хранятся отдельно, а берутся напрямую из базы данных игрового сервера, но после запроса хранятся в памяти, пока не наступит момент, указанный в cachedUntil. Если вы повторно попробуете получить данные до наступления этого момента, то получите эту копию.

Short-кэширование подразумевает, что данные хранятся в памяти API-сервера и обновляются через определённые промежутки времени. Параметр cachedUntil явно указывает на момент, когда данные обновятся в памяти API-сервера. Этот тип кэширования даёт возможность несколько раз запрашивать данные, повторно вызывая функцию до истечения срока кэширования. Однако, совершенно понятно, что такой подход со стороны разработчика будет не очень изящно выглядеть. Зачем тратить лишние ресурсы на запрос, если вы и так знаете, какой результат получите?.. Можно же с самого начала сохранить результат запроса локально и пользоваться им, пока не истечёт время на кэширование.

M-short-кэширование похоже на short-версию, но семантика параметра cachedUntil немного отличается. Он в данном случае никак не сообщает о том, когда данные в памяти API-сервера обновятся, но позволяет «разбавить» запросы пользователей к сильно загруженным запросами частям данных. В качестве примера можно привести функцию, возвращающую данные о состоянии игрового сервера.

В описании каждой API-функции указывается, какой стиль кэширования она использует, однако, несмотря на конкретный тип кэширования, лучший способ — ориентироваться на значение параметра cachedUntil и не запрашивать данные повторно, пока не наступит указанный в нём срок.

Ошибки

Иногда при вызове функции происходит какая-нибудь ошибка. Причин может быть много, но сгруппировать их можно в четыре категории — в зависимости от номера. Все номера ошибок, возвращаемые функциями имеют три разряда и, в зависимости от значения старшего разряда, могут относиться к следующей категории:

  • 1xx — ошибки в пользовательском вводе
  • 2xx — ошибки аутентификации
  • 5xx — ошибки на стороне сервера
  • 9xx — прочие ошибки

Полный список ошибок можно узнать, вызвав API-функцию ErrorList.xml.aspx.

Ещё можно обратить внимание на ошибку с кодом «0», которая может возникать, если, например, в функциях /char/WalletJournal.xml.aspx или /corp/WalletJournal.xml.aspx вы используете слишком большие значения rowCount:

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <eveapi version="2">
  3.   <currentTime>2011-07-28 16:28:19</currentTime>
  4.   <error code="0">General Error: Scotty the docking manager heard you were talking shit about him behind his back and refuses to service your request.</error>
  5.   <cachedUntil>2011-07-28 17:28:19</cachedUntil>
  6. </eveapi>

Форматы данных

В описании каждой API-функции справочника EVE API присутствуют таблицы, рассказывающие о том, какие параметры принимает и возвращает функция. Ниже эти типы данных разъясняются более подробно. Итак, все принимаемые и возвращаемые API-функциями параметры могут представлять из себя следующие типы данных:

int

Целое число. Подразумевается тип данных int, который может принимать значения в диапазоне от -2^31 (-2 147 483 648) до 2^31-1 (2 147 483 647). В некоторых случаях может использоваться в качестве логического значения, когда соответствующий параметр подразумевает только значения 0 или 1.

bigint

Большое целое. Подразумевается тип данных bigint, который может принимать значения в диапазоне от -2^63 (-9 223 372 036 854 775 808) до 2^63-1 (9 223 372 036 854 775 807). Используется в таких функциях, как /char/WalletJournal.xml.aspx и /corp/WalletJournal.xml.aspx, где номера операций (refID) используют значения, превышающие 32-битный диапазон int.

decimal

Нецелое число, в котором значение представлено с точностью до 2-х знаков после запятой. Чаще всего используется для выражения суммы во внутриигровой валюте – ISK. Обратите внимание, что в качестве разделителя целой и дробной частей используется точка, а не привычная для русской письменности запятая, поэтому будьте внимательны, например, если передаёте данные в Excel.

float

Подразумевается тип данных float, в котором количество битов для хранения мантиссы числа при экспоненциальном представлении равно 53. Другими словами: это нецелое число, в котором значение представлено с точностью до 15 знаков после запятой. Обратите внимание, что в качестве разделителя целой и дробной частей используется точка, а не привычная для русской письменности запятая, поэтому будьте внимательны, например, если передаёте данные в Excel.

char(64)

Поле с таким типом данных в основном используется для хранения vCode-параметра API-ключа. Он всегда имеет длину в 64 символа (или меньше) и представляет из себя строку состоящую из заглавных и строчных английских букв, а так же — цифр.

string

Текстовая строка (UTF-8).

dateTime

Дата в формате DateTime. Такая дата составляется по шаблону yyyy-MM-dd HH:mm:ss, где:

  • yyyy – четыре знака (год);
  • MM – два знака (месяц);
  • dd – два знака (день);
  • HH – два знака (часы);
  • mm – два знака (минуты);
  • ss – два знака (секунды).

Например, "22 июля 2011 года, 16:42" будет обозначаться так: 2011-07-22 16:42:00. Все генерируемые данные используют всемирное координированное время (UTC). Сервер EVE Online так же "живёт" по UTC, так как находится в Лондоне, где смещение часового пояса равно нулю.

bool

Такой тип данных может возвращать значения True или False.

bit

Этот тип похож по смыслу на bool, но возвращает значения в виде 1 и 0.

Не определён

Иногда может встречаться и такое объяснение типа данных. Так бывает в тех случаях, когда тип данных, принимаемый полем, зависит от значения других полей. В любом случае, лучше использовать такой тип в качестве string – строкового значения – преобразуя его к остальным типам уже потом, если это требуется. Примером может служить функция /char/WalletJournal.xml.aspx, в результатах работы которой параметр argName1 может быть названием станции (строкой), когда речь идёт о прямой торговле между игроками, и идентификатором задания (числом), если речь идёт об использовании производственной линии для постройки или исследования.

Дополнительная информация

Первый девблог, посвящённый EVE API, вышел 15 мая 2007 года и назывался THE EVE API PROJECT.

Похожие материалы

Категория: Разработчикам | Добавил: Heritor (13 Июль 2011) | Автор: Heritor Skoliya E W
Просмотров: 6585 | Теги: eve api | Рейтинг: 5.0/2
Всего комментариев: 0
Добавлять комментарии могут только зарегистрированные пользователи.
[ Регистрация | Вход ]
»Рубрики«
Новичкам [21]
Информация о том как начать играть и как освоиться в игре
Таблицы [10]
Различная сводная информация
Расы [8]
Описание рас Нового Эдема
Хроники [96]
Хроники мира EVE Online. Перевод хроник официального сайта игры
Разработчикам [27]
API, IGB, технологии
Рассказы [1]
Творчество автора данного сайта
Разное [8]
Материалы общего характера
»Поиск«
»Ссылки«
»О сайте«

SKOLI.ru — русский фан сайт игры EVE Online. Статьи и новости с официального сайта eve-online о мире Нового Эдема, гайды, переводы хроник EVE, скриншоты и обои, амбиентная музыка из игры, видео.

»Статистика«

© 2008-2017 SKOLI.RU
Обязательна ссылка на источник, если вы используете материалы, расположенные на данном сайте.
COPYRIGHT NOTICE
EVE Online, the EVE logo, EVE and all associated logos and designs are the intellectual property of CCP hf. All artwork, screenshots, characters, vehicles, storylines, world facts or other recognizable features of the intellectual property relating to these trademarks are likewise the intellectual property of CCP hf. EVE Online and the EVE logo are the registered trademarks of CCP hf. All rights are reserved worldwide. All other trademarks are the property of their respective owners. CCP hf. is not in any way affiliated with, Skoli.ru. CCP is in no way responsible for the content on or functioning of this website, nor can it be liable for any damage arising from the use of this website.