Castles:Защита серверов/API защиты серверов: различия между версиями

Материал из SurvivalHost Wiki
Перейти к навигации Перейти к поиску
м
 
(не показаны 24 промежуточные версии этого же участника)
Строка 15: Строка 15:
= Доступ и авторизация =
= Доступ и авторизация =
'''Authorization: Bearer <token>'''
'''Authorization: Bearer <token>'''
Пример тестового токена: nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V


= Работа с игровыми серверами =
= Работа с игровыми серверами =


== Просмотр данных сервера ==
== Просмотр данных сервера ==
  '''GET [baseUrl]/[project]/v2/<ip_address>:<main_port>'''
  '''GET [baseUrl]/[project]/v2/<ip_address>/<main_port>'''
Пример запроса: https://api.castles.pro/myhost/v2/10.10.10.5/27020
Пример запроса:  
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/89.22.249.11/27020 -k -v 
 
Пример ответа:  
Пример ответа:  
  "game": "ark",
{
  "ipAddress": "10.10.10.5",
  "game": "ark",
  "enduser": "uid=123",
  "ipAddress": "10.10.10.5",
  "ports": {
  "enduser": "user123",
    "query": "27015",
  "ports": {
    "game": "27020",
    "query": "27015",
    "rcon": "27100"
    "game": "27020",
  },
    "rcon": "27100"
  "protection": {
  },
    "status": "online",
  "protection": {
    "address": "10.10.10.5/27020",
    "status": "online",
    "additional": "query:27015, rcon:27100",
    "address": "10.10.10.5/27020",
    "comment": "Защита игрового сервера"
    "additional": "query:27015, rcon:27100",
  }
    "comment": "Защита игрового сервера"
  }
}


Возвращаемые ошибки:
Возвращаемые ошибки:
* HTTP 400 Request must contain a valid IP.
* HTTP 400 Request must contain a valid IP.
* HTTP 404 Machine not found.
* HTTP 400 The port must be in the range 1-65535.
* HTTP 400 The port must be in the range 1-65535.
* HTTP 404 Server not found.
* HTTP 404 Server not found.
Строка 46: Строка 51:
== Просмотр данных всех серверов на IP-адресе ==
== Просмотр данных всех серверов на IP-адресе ==
  '''GET [baseUrl]/[project]/v2/<ip_address>'''
  '''GET [baseUrl]/[project]/v2/<ip_address>'''
Пример запроса: https://api.castles.pro/myhost/v2/10.10.10.5
Пример запроса:  
   
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/89.22.249.11 -k -v 
 
Пример ответа:
[
  {
    "game": "ark",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "query": 27015,
      "game": 27020,
      "rcon": 27100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/27020",
      "additional": "query:27015, rcon:27100",
      "comment": "Защита игрового сервера"
    }
  },
  {
    "game": "arma3",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "game": 29020,
      "query": 29015,
      "rcon": 29100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/29020",
      "additional": "query:29015, rcon:29100",
      "comment": "Защита игрового сервера"
    }
  }
  ]
 
Возвращаемые ошибки:
* HTTP 400 Request must contain a valid IP.
 
== Просмотр данных всех серверов c пагинацией и фильтрацией по endUser ==
'''GET [baseUrl]/[project]/v2?start=<start>&length=<length>&endUser=<endUser>'''
Пример запроса:
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2?start=0&length=2&endUser=user123 -k -v 
 
Пример ответа:
Пример ответа:
   {
{
    "game": "ark",
   "rows": [
    "ipAddress": "10.10.10.5",
  {
    "enduser": "uid=123",
    "game": "ark",
    "ports": {
    "ipAddress": "10.10.10.5",
      "query": "27015",
    "enduser": "user123",
      "game": "27020",
    "ports": {
      "rcon": "27100"
      "query": 27015,
    },
      "game": 27020,
    "protection": {
      "rcon": 27100
      "status": "online",
    },
      "address": "10.10.10.5/27020",
    "protection": {
      "additional": "query:27015, rcon:27100",
      "status": "online",
      "comment": "Защита игрового сервера"
      "address": "10.10.10.5/27020",
    }
      "additional": "query:27015, rcon:27100",
  },
      "comment": "Защита игрового сервера"
  {
    }
    "game": "arma3",
  },
    "ipAddress": "10.10.10.5",
  {
    "enduser": "uid=123",
    "game": "arma3",
    "ports": {
    "ipAddress": "10.10.10.5",
      "game": "29020",
    "enduser": "user123",
      "query": "29015",
    "ports": {
      "rcon": "29100"
      "game": 29020,
    },
      "query": 29015,
    "protection": {
      "rcon": 29100
      "status": "deleted",
    },
      "address": "10.10.10.5/29020",
    "protection": {
      "additional": "query:29015, rcon:29100",
      "status": "online",
      "comment": "Защита игрового сервера"
      "address": "10.10.10.5/29020",
    }
      "additional": "query:29015, rcon:29100",
   }
      "comment": "Защита игрового сервера"
    }
  }
   ],
  "total_count": 100
}
   
   
Возвращаемые ошибки:
Возвращаемые ошибки:
* HTTP 400 Request must contain a valid IP.
* HTTP 400 The start field must contain a number greater than or equal to 0.
* HTTP 400 The length field must contain a number greater than 0.


== Добавление сервера под защиту ==
== Добавление сервера под защиту ==
  '''POST [baseUrl]/[project]/<ip_address>'''
  '''POST [baseUrl]/[project]/v2/<ip_address>'''
Тело запроса:
Тело запроса:
  {}
  {
  "game":"ark",
  "ports": {
    "game": 27020,
    "query": 27015,
    "rcon": 27100
  },
  "enduser": "user123"
}
 
Пример запроса:
Пример запроса:
   
curl -d '{"game":"ark","ports":{"game":27020,"query":27015,"rcon":27100},"enduser":"uid=123"}' -H "Content-Type: application/json" -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X POST https://api.castles.pro/myhost/v2/89.22.249.11 -k -v  
Пример ответа:
 
   
Пример ответа:  
  {
  "game": "ark",
  "ipAddress": "89.22.249.11",
  "enduser": "uid=123",
  "ports": {
    "query": 27015,
    "game": 27020,
    "rcon": 27100
  },
  "protection": {
    "status": "online",
    "address": "89.22.249.11/27020",
    "additional": "query:27015, rcon:27100",
    "comment": "Защита игрового сервера"
  }
}
 
Возвращаемые ошибки:
Возвращаемые ошибки:
* HTTP 400 Request must contain a valid IP.
* HTTP 400 Body must contain valid json.
* HTTP 400 The game field is required.
* HTTP 400 The ports[] field is required.
* HTTP 400 Game not found.
* HTTP 400 The <port_id> port is required.
* HTTP 400 The <port_id> port must be in the range 1-65535.
* HTTP 400 The <ip>:<port> is overlaps with current servers.
* HTTP 503 Service Unavailable


== Удаление сервера из под защиты ==
== Удаление сервера из под защиты ==
  '''DELETE [baseUrl]/[project]/v2/<ip_address>/<main_port>'''
  '''DELETE [baseUrl]/[project]/v2/<ip_address>/<main_port>'''
Пример запроса: https://api.castles.pro/myhost/v2/10.10.10.5/27020
Пример запроса:  
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X DELETE https://api.castles.pro/myhost/v2/89.22.249.11/27020 -k -v


Пример ответа:
Пример ответа:
  "status": true
{
  "status": true
}


Возвращаемые ошибки:
Возвращаемые ошибки:
HTTP 400 Request must contain a valid IP.
* HTTP 400 Request must contain a valid IP.
HTTP 400 The port must be in the range 1-65535.
* HTTP 400 The port must be in the range 1-65535.
HTTP 404 Server not found.
* HTTP 404 Server not found.
HTTP 503 Service Unavailable
* HTTP 503 Service Unavailable


= Справочники =
= Справочники =
== Cтатусы сервера ==
Статус сервера можно увидеть в блоке protection.status в результатах GET и POST-запросов.
Поддерживаются следующие статусы:
* '''protected''' - сервер поставлен на защиту;
* '''online''' - сервер поставлен на защиту и успешно прошел ping-pong по query-порту (по протоколам, source query, miecraft query и т.д.);
* '''updating''' - выгрузка запланирована но еще не осуществлена. Обычно в этом статусе находятся серверы, которые не выгрузились по какой-либо причине (недоступность сервера или роутера, некорректная сеть). Сервис защиты будет постоянно пробовать добавить сервер под защиту. Если сервер находится в статусе updating слишком долго - это свидетельствует об ошибке;
* '''deleted''' - терминальный статус. Сервер удален из защиты.


== Поддерживаемые игры ==
== Поддерживаемые игры ==
  '''GET [baseUrl]/[project]/v2/games'''
  '''GET [baseUrl]/[project]/v2/games'''
Пример запроса: https://api.castles.pro/myhost/v2/games
Пример запроса:  
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/games -k -v


Пример ответа:
Пример ответа:
  {
[
    "id": "7dtd",
  {
    "name": "7 Days to Die",
    "id": "7dtd",
    "main_port_id": "game"
    "name": "7 Days to Die",
  },
    "main_port_id": "game"
  {
  },
    "id": "ark",
  {
    "name": "ARK: Survival Evolved",
    "id": "ark",
    "main_port_id": "game"
    "name": "ARK: Survival Evolved",
  },
    "main_port_id": "game"
  {
  },
    "id": "arma3",
  {
    "name": "Arma 3",
    "id": "arma3",
    "main_port_id": "game"
    "name": "Arma 3",
  },
    "main_port_id": "game"
  },
]


== Перечень обслуживаемых подсетей ==
== Перечень обслуживаемых подсетей ==
  '''GET [baseUrl]/[project]/v2/network'''
  '''GET [baseUrl]/[project]/v2/network'''
Пример запроса: https://api.castles.pro/myhost/v2/network
Пример запроса:
curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/network -k -v


Пример ответа:
Пример ответа:
  "10.10.10.1/24",
[
  "15.15.15.1/24"
  "10.10.10.1/24",
  "15.15.15.1/24"
]


[[Категория:Castles]]
[[Категория:Castles]]
{{nav foot}}
{{nav foot}}

Текущая версия на 01:19, 23 ноября 2023

Castles Pro - API защиты серверов
<< Castles:Защита серверов | К концу статьи | Предыдущая глава: Поддерживаемые игры | Короткая ссылка

Основные параметры

[baseUrl]: Главный URL сервиса (https://api.castles.pro)

[project]: Идентификатор проекта (выдается сервисом при подключении, например myhost)

<token>: Токен доступа к сервисам (выдается сервисом при подключении)

<ip_address>: IP-адрес игрового сервера (например 10.10.10.5)

<main_port>: Главный порт игрового сервера (см. колонку "Основной (адресный) порт" в Поддерживаемые игры)

Доступ и авторизация

Authorization: Bearer <token>

Пример тестового токена: nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V

Работа с игровыми серверами

Просмотр данных сервера

GET [baseUrl]/[project]/v2/<ip_address>/<main_port>

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/89.22.249.11/27020 -k -v  

Пример ответа:

{
  "game": "ark",
  "ipAddress": "10.10.10.5",
  "enduser": "user123",
  "ports": {
    "query": "27015",
    "game": "27020",
    "rcon": "27100"
  },
  "protection": {
    "status": "online",
    "address": "10.10.10.5/27020",
    "additional": "query:27015, rcon:27100",
    "comment": "Защита игрового сервера"
  }
}

Возвращаемые ошибки:

  • HTTP 400 Request must contain a valid IP.
  • HTTP 404 Machine not found.
  • HTTP 400 The port must be in the range 1-65535.
  • HTTP 404 Server not found.

Просмотр данных всех серверов на IP-адресе

GET [baseUrl]/[project]/v2/<ip_address>

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/89.22.249.11 -k -v  

Пример ответа:

[
  {
    "game": "ark",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "query": 27015,
      "game": 27020,
      "rcon": 27100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/27020",
      "additional": "query:27015, rcon:27100",
      "comment": "Защита игрового сервера"
    }
  },
  {
    "game": "arma3",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "game": 29020,
      "query": 29015,
      "rcon": 29100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/29020",
      "additional": "query:29015, rcon:29100",
      "comment": "Защита игрового сервера"
    }
  }
]

Возвращаемые ошибки:

  • HTTP 400 Request must contain a valid IP.

Просмотр данных всех серверов c пагинацией и фильтрацией по endUser

GET [baseUrl]/[project]/v2?start=<start>&length=<length>&endUser=<endUser>

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2?start=0&length=2&endUser=user123 -k -v  

Пример ответа:

{
 "rows": [
  {
    "game": "ark",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "query": 27015,
      "game": 27020,
      "rcon": 27100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/27020",
      "additional": "query:27015, rcon:27100",
      "comment": "Защита игрового сервера"
    }
  },
  {
    "game": "arma3",
    "ipAddress": "10.10.10.5",
    "enduser": "user123",
    "ports": {
      "game": 29020,
      "query": 29015,
      "rcon": 29100
    },
    "protection": {
      "status": "online",
      "address": "10.10.10.5/29020",
      "additional": "query:29015, rcon:29100",
      "comment": "Защита игрового сервера"
    }
  }
 ],
 "total_count": 100
}

Возвращаемые ошибки:

  • HTTP 400 The start field must contain a number greater than or equal to 0.
  • HTTP 400 The length field must contain a number greater than 0.

Добавление сервера под защиту

POST [baseUrl]/[project]/v2/<ip_address>

Тело запроса:

{
  "game":"ark",
  "ports": {
    "game": 27020,
    "query": 27015,
    "rcon": 27100
  },
  "enduser": "user123"
}

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

curl -d '{"game":"ark","ports":{"game":27020,"query":27015,"rcon":27100},"enduser":"uid=123"}' -H "Content-Type: application/json" -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X POST https://api.castles.pro/myhost/v2/89.22.249.11 -k -v  

Пример ответа:

{
  "game": "ark",
  "ipAddress": "89.22.249.11",
  "enduser": "uid=123",
  "ports": {
    "query": 27015,
    "game": 27020,
    "rcon": 27100
  },
  "protection": {
    "status": "online",
    "address": "89.22.249.11/27020",
    "additional": "query:27015, rcon:27100",
    "comment": "Защита игрового сервера"
  }
}

Возвращаемые ошибки:

  • HTTP 400 Request must contain a valid IP.
  • HTTP 400 Body must contain valid json.
  • HTTP 400 The game field is required.
  • HTTP 400 The ports[] field is required.
  • HTTP 400 Game not found.
  • HTTP 400 The <port_id> port is required.
  • HTTP 400 The <port_id> port must be in the range 1-65535.
  • HTTP 400 The <ip>:<port> is overlaps with current servers.
  • HTTP 503 Service Unavailable

Удаление сервера из под защиты

DELETE [baseUrl]/[project]/v2/<ip_address>/<main_port>

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X DELETE https://api.castles.pro/myhost/v2/89.22.249.11/27020 -k -v 

Пример ответа:

{
  "status": true
}

Возвращаемые ошибки:

  • HTTP 400 Request must contain a valid IP.
  • HTTP 400 The port must be in the range 1-65535.
  • HTTP 404 Server not found.
  • HTTP 503 Service Unavailable

Справочники

Cтатусы сервера

Статус сервера можно увидеть в блоке protection.status в результатах GET и POST-запросов.

Поддерживаются следующие статусы:

  • protected - сервер поставлен на защиту;
  • online - сервер поставлен на защиту и успешно прошел ping-pong по query-порту (по протоколам, source query, miecraft query и т.д.);
  • updating - выгрузка запланирована но еще не осуществлена. Обычно в этом статусе находятся серверы, которые не выгрузились по какой-либо причине (недоступность сервера или роутера, некорректная сеть). Сервис защиты будет постоянно пробовать добавить сервер под защиту. Если сервер находится в статусе updating слишком долго - это свидетельствует об ошибке;
  • deleted - терминальный статус. Сервер удален из защиты.

Поддерживаемые игры

GET [baseUrl]/[project]/v2/games

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/games -k -v 

Пример ответа:

[
  {
    "id": "7dtd",
    "name": "7 Days to Die",
    "main_port_id": "game"
  },
  {
    "id": "ark",
    "name": "ARK: Survival Evolved",
    "main_port_id": "game"
  },
  {
    "id": "arma3",
    "name": "Arma 3",
    "main_port_id": "game"
  },
]

Перечень обслуживаемых подсетей

GET [baseUrl]/[project]/v2/network

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

curl -H "Authorization: Bearer nv73MHPHw3!eEVzuHAlAhSZH/CenIgAN=/eccBIuK2AlwHF4aYSrsV3EZnMkmo-V" -X GET https://api.castles.pro/myhost/v2/network -k -v 

Пример ответа:

[
  "10.10.10.1/24",
  "15.15.15.1/24"
]

<< Castles:Защита серверов | К началу статьи