API управления подпиской

• Сквозная авторизация на партнерском портале ООО “СкайДНС”
• Документация модуля skydns_website.api.subscription (API Подписки)
• Документация модуля skydns_website.api.application (API Агентов)
• Использование API подписки SkyDNS

Сквозная авторизация на партнерском портале ООО “СкайДНС”

Для кого эта документация

Документация написана для партнеров ООО "СкайДНС". Описывает механизм создания ссылки на партнёрский портал, для обеспечения прозрачной авторизации пользователей.

Принцип действия

Принцип основан на безопасной передаче данных через небезопасную среду, проще говоря с помощью криптографической подписи.

Рассмотрим на примере: Допустим есть партнер "Рога и Копыта", который предоставляет услуги доступа в интернет. Есть кабинет партнера, через который клиенты партнера управляют услугами. Есть кабинет партнерского портала, через который пользователь может управлять сервисом ООО "СкайДНС". Требуется организовать бесшовную авторизацию на партнерском портале из кабинета партнера для его клиентов.

Для этого с помощью ключей доступа формируется подписанный URL, ведущий на партнерский портал. После перехода по URL пользователь авторизуется без ввода пароля. При этом, если неавторизованный пользователь попадает на партнерский портал, он перенаправляется на кабинет партнера для получения ссылки для авторизации.

Требования

1. Ключи доступа к API ООО "СкайДНС" и доменное имя портала. Ключи и доменное имя можно получить связавшись с отделом продаж;
2. Передать в ООО "СкайДНС" URL, где неавторизованный пользователь может получить ссылку для авторизации на партнерском портале;
3. Идентификатор пользователя на партнерском портале ООО "СкайДНС", его можно получить при создании пользователя, с помощью Provider Api ООО "СкайДНС";
4. Библиотека для криптографической подписи, см. далее.

Есть готовые реализации библиотеки криптографической подписи:

1. python - в фреймворке Django "django.core.signing";
2. python - библиотека "itsdangerous";
3. php - библиотека "itsdangerous-php";
4. javascript - библиотека "nobi".

Если используемый вами язык программирования не перечислен выше, вам необходимо самостоятельно найти или написать аналог вышеописанных библиотек.

Создание URL

Для создания URL вам потребуется private_key и доменное имя портала. Далее пример кода для формирования URL. Так же потребуется идентификатор пользователя, для которого мы генерируем ссылку.

Далее следует код на python:

from django.utils.crypto import get_random_string
from django.core import signing

key = 'private key'
domain = 'skydns.example'
username = 'user@partner'

data = {'ident': username, 'token': get_random_string()}
signer = signing.Signer(key, salt='skydns')
json = signing.JSONSerializer().dumps(data)
b64 = signing.b64_encode(json)
token = signer.sign(b64)

print 'https://%s/welcome?%s' % (domain, token)

Где key это приватный ключ, domain доменное имя портала, username это идентификатор пользователя. Полученный URL можно разместить в месте доступном пользователю.

Данным URL можно воспользоваться только один раз, и в течение некоторого времени, после этого данный токен становится не валидным.

Использование URL

Далее полученный URL нужно отобразить пользователю, что бы он перешел по нему на портал.

Так же необходимо передать нам URL, по которому пользователь, не авторизованный на нашем портале, мог бы авторизоваться. Как правило это URL личного кабинета партнера.

Пример кода на php

При возможности заменить функцию generateRandomString на криптографически безопасную random_bytes из модуля CSPRNG.

<?php
require("itsdangerous.php");

function generateRandomString($length = 10) {
    $characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
    $charactersLength = strlen($characters);
    $randomString = '';
    for ($i = 0; $i < $length; $i++) {
        $randomString .= $characters[rand(0, $charactersLength - 1)];
    }
    return $randomString;
}

$key = "private key";
$domain = "skydns.example";
$username = "user@partner";
$complex = array(
    "ident" => $username,
    "token" => generateRandomString(10)
);
$ser = new ItsDangerous\Signer\Serializer($key);
$c = $ser->dumps($complex);



$url = sprintf("https://%s/welcome?%s", $domain, base64_encode($c));

print $url;

Документация модуля skydns_website.api.subscription (API Подписки)

Набор представлений для методов Subscription API v 1.9.

skydns_website.api.subscription.views.activate_user(provider, data)

Активировать пользователя провайдера.

skydns_website.api.subscription.views.add_ip(provider,user,profile,data)

Метод добавляет один или несколько статических адресов без замены.

Если при этом адрес находится на другом профиле этого же пользователя, то происходит его перепривязка к указанному профилю. Если адрес привязан к профилю другого пользователя, то выдается ошибка для этого или нескольких адресов. Добавление других адресов в наборе происходит без ошибки.

Параметр comment который будет применен ко всем ip

Необязательные параметры:

skydns_website.api.subscription.views.add_vpn(provider,data)

Метод пытается создать сертификат vpn-соединения.

Возможные ошибки:

• при попытке создать для пользователя впн-соединение с именем уже использующимся в его впн-соединениях
• при попытке создать впн-соединений больше определённого для пользователя планфичей vpn
• при попытке создать соединение на несуществующий или принадлежащий другому пользователю профиль(по profile_id)
• при попытке реселлера создать соединение не своему пользователю

skydns_website.api.subscription.views.clear_ip(provider,data)

Метод очищает все адреса привязанные к профилю.

skydns_website.api.subscription.views.clear_vpn_for_profile(provider,data)

Метод удаляет все vpn-соединения для профиля пользователя

skydns_website.api.subscription.views.clear_vpn_for_user(provider,data>)

Метод удаляет все vpn соединения пользователя

skydns_website.api.subscription.views.create_profile(provider,data)

Метод создает профиль пользователю.

skydns_website.api.subscription.views.deactivate_user(provider,data)

Деактивировать пользователя провайдера.

skydns_website.api.subscription.views.get_active_users(provider,data)

Метод возвращает список активных пользователей реселлера и их тарифы.

[
{‘username’: ‘username1’, ‘plan_name’: ‘plan name’}, {‘username’: ‘username2’, ‘plan_name’: ‘plan name’}, ... 
]

skydns_website.api.subscription.views.get_activity(provider,data)

Информация об активности пользователя за определенную дату. В зависимости от настроек реселлера возвращается старая статистика или аналитика.

Необязательные параметры:

skydns_website.api.subscription.views.get_activity_report(provider,data)

Отчет об активности пользователя за определенный период времени.

Необязательный параметр: :param profile_id: идентификатор профиля пользователя, для которого запрашивается отчет

{
   “labels”: [
      “2016-06-29 14:00:00”, “2016-06-29 15:00:00”,

   ], “datasets”: [
      {“label”: “Requests”, “data”: [375, 275]}, {“label”: “Blocks”, “data”: [13, 0]}
   ]
}

skydns_website.api.subscription.views.get_category_report(provider,data)

Отчет по категориям пользователя за определенный период времени.

Необязательный параметр: :param profile_id: идентификатор профиля пользователя, для которого запрашивается отчет

{
“Movies & Video”: “5”, “File Storage”: “2”, “Home & Family”: “3”
}

skydns_website.api.subscription.views.get_daily_stat(provider,data)

Возвращает реселлеру статистику за день для указанного пользователя

Необязательные параметры:

Отчет содержит следующие столбцы: “Timestamp”, “Domain name”, “Visits”, “Blocks”, “Categories”, “Profile”, “Username”, “User’s timestamp”.

skydns_website.api.subscription.views.get_list_activity_report(provider,data)

Отчет об активности пользователя за определенный период времени.

{
   “2019-08-01”: {
      “username”: {
         “visits”: 262972530, “blocks”: 567080
      },....
   },....
}

skydns_website.api.subscription.views.get_popular_report(provider,data)

Отчет о популярных запросах пользователя за определенный период времени.

Необязательный параметр: :param profile_id: идентификатор профиля пользователя, для которого запрашивается отчет

{
   “labels”: [“example.com”, “google.com”, “asdfg.com”], “datasets”: [

      {“label”: “Requests”, “data”: [630, 474, 290]}, {“label”: “NXdomain”, “data”: [0, 0, 290]}, 
      {“label”: “Blocks”, “data”: [630, 0, 0]}

   ]

}

skydns_website.api.subscription.views.get_vpn_list(provider,data)

Метод для получения списка vpn соединений пользователя

skydns_website.api.subscription.views.list_ip(provider,data)

Необязательный параметр: :param profile: числовой id профиля

skydns_website.api.subscription.views.method_not_found(*args,**kwargs)

Метод-пустышка-заглушка.

Нужен, чтобы, согласно спецификации jsonrpc, отдавать удобочитаемую ошибку. Ответ полностью соответствует спецификации: https://www.jsonrpc.org/specification.

skydns_website.api.subscription.views.profiles(provider,data)

Метод возвращает список активных профилей пользователя.

{
   70749: u’Основной’, 93773: u’ДхтСкий’,
}

skydns_website.api.subscription.views.prolongate(provider,data)

Включение и изменение платного тарифа для пользователя. Этот метод всегда должен вызываться после метода subscribe для включения услуги пользователю.

Необязательный параметр: :param plan: код тарифного плана

skydns_website.api.subscription.views.remove_ip(provider,data)

Удаление IP адреса пользователя.

skydns_website.api.subscription.views.remove_vpn(provider, data)

Метод для удаления vpn соединения пользователя

send_monthly_stat(provider, data)

Отправка статистики за месяц пользователю по электронной почте.

Необязательный параметр: :param profile_id: идентификатор профиля пользователя, для которого запрашивается статистика.

Отчет содержит следующие столбцы: “Timestamp”, “Domain name”, “Visits”, “Blocks”, “Profile”, “Categories”.

skydns_website.api.subscription.views.subscribe(provider, data)

Регистрация пользователя в системе с переданными реквизитами и установка тарифа по умолчанию.

Необязательные параметры:

skydns_website.api.subscription.views.subscribe_plans(provider, data)

Метод возвращает список доступных тарифов, назначаемых при создании/изменении карточки пользователя.

skydns_website.api.subscription.views.subscription_info(provider, data)

Информация о подписке. На текущий момент возвращает наступила ли дата окончания подписки.

skydns_website.api.subscription.views.unsubscribe(provider, data)

Отключение пользователя. Пользователь переключается на бесплатный тариф.

skydns_website.api.subscription.views.update_email(provider, data)

Изменение email пользователя для восстановления пароля и информационных сообщений.

skydns_website.api.subscription.views.update_ip(provider, data)

Создать или обновить динамический IP адрес пользователя и привязать его к необходимому профилю фильтрации.

Необязательные параметры:

skydns_website.api.subscription.views.update_nat(provider, data)

Метод для добавления или обновления привязки профиля пользователя реселлера к одному из NAT DNS

skydns_website.api.subscription.views.update_password(provider, data)

Обновление пароля пользователя.

skydns_website.api.subscription.views.update_profile(provider, data)

Метод для изменения параметров профиля пользователя реселлера

Необязательные параметры:

Документация модуля skydns_website.api.application (API Агентов)

Доступные методы API

Модуль хранения представлений JSON-RPC API. Используется агентами.

Curl запросы для тестирования выглядит так:

curl -X POST http://localhost:8000/api/json/v2 -L –user user:password > -d ‘{“id”:0, “jsonrpc”:”2.0”,”method”:”renameProfile”,”params”:[1234, “abcd”]}’

В простейшем случае связку кредитов можно использовать такую:

plantest-premium@skydns.ru:plantest

skydns_website.api.application.views.add_domain(request, profile, choice, domain, ip=None, comment='')

JSONRPC Method: addDomain

Добавить домен.

skydns_website.api.application.views.add_profile(request, name)

JSONRPC Method: addProfile

Метод создает профиль и возвращает словарь с данными о профиле.

{

‘id’: id профиля, 
‘default’: является ли профиль профилем по умолчанию, 
‘token’: токен, 
‘name’: название профиля, 
‘white_list_only’: включена ли фильтрация только по белому списку, 
‘is_schedule_enabled’: включено ли расписание, 
‘safe_search_enabled’: статус безопасного поиска, 
‘safe_youtube_enabled’: статус фильтрации YouTube (для API v2), 
‘block_unknown_enabled’: статус фильтрации неизвестных сайтов (для API v2)

}

skydns_website.api.application.views.categories(request, language='en')

JSONRPC Method: categories

Получить список сгруппированных категорий.

[
   {
      “title”: “group1”, “items”: [
         {
            “title”: “item1”, “id”: 1
      ]

]

skydns_website.api.application.views.change_schedule(request, profile, segments)

JSONRPC Method: setSchedule

Установить расписание фильтрации.

skydns_website.api.application.views.clear_domains(request, profile, choice )

JSONRPC Method: clearDomains

Удалить все домены определенного типа у профиля.

skydns_website.api.application.views.domains(request, profile, choice)

JSONRPC Method: domains

Получить список доменов определенного типа для профиля.

Параметры:	profile – профиль пользователя choice – тип домена (‘black’, ‘white’ или ‘alias’)
Результат:	для запроса чёрных или белых доменов - список словарей в формате:    { “domain”: домен, “id”: id домена ] для запроса алиасов - список словарей в формате: [ { “domain”: домен, “id”: id домена, “ip”: ip-адрес ]

Тип результата:	list

skydns_website.api.application.views.enable_schedule(request, profile, flag)

JSONRPC Method: setScheduleEnabled

Включить/выключить расписание для профиля.

Параметры:	profile – профиль пользователя flag – флаг включить/выключить
Результат:	flag
Тип результата:	bool

skydns_website.api.application.views.feedback(request, title, message)

JSONRPC Method: feedback

Отправить сообщение обратной связи пользователя.

Параметры:	title – заголовок сообщения для отправки message – сообщение для отправки
Результат:	None

skydns_website.api.application.views.get_advertising(request)

JSONRPC Method: getAdvertising

Получить информацию об акции.

Результат:	[<strAdvUrl>, <strImageUrl>]
Тип результата:	list

skydns_website.api.application.views.get_agent_profile(request, uid, hostname, version, os_info, address)

JSONRPC Method: getProfile

Возвращает необходимые настройки (токен, UID) для работы агентского приложения. Если передан UID - метод вернёт информацию об уже существующем профиле с этим UID. Если UID пуст, но переданы все остальные параметры - будет создан новый профиль.

Параметры:	uid – uid hostname – имя хоста version – версия os_info – информация address – IP адрес
Результат:	список с данными профиля агента: [uid, token, profile_id]
Тип результата:	list

skydns_website.api.application.views.get_categories_daily_stat(request, profile, lang='en', categories_list=None)

JSONRPC Method: getCategoriesDailyStats

Получить статистику по категориям за сутки для нужного профиля.

Параметры:	profile – профиль пользователя lang – язык выдачи categories_list – список идентификаторов категорий. Если его нет, то будет получена статистика блокировок по всем категориям для профиля пользователя
Результат:	словарь формата: { <category_name>: <value> ... }
Тип результата:	dict

skydns_website.api.application.views.get_filtering_status(request)

JSONRPC Method: getFilteringStatus

Получить состояние фильтрации пользователя. :return: <состояние фильтрации> :rtype: bool

skydns_website.api.application.views.get_limited_agent_profile(request, uid, hostname, version, os_info, address)

JSONRPC Method: getLimitedProfile

Это модификация метода get_agent_profile (getProfile). Этот метод проверяет, сколько уже выдано токенов пользователю (мобильных или десктопных Linux), и если это число превышает максимум (ПФ max_mobile_agents и max_desktop_agents соответственно), отдаёт фейловые токены (‘’, 9999999999, <profile_id>) Если запрос не мобильного или десктопного Linux агента, токены генерируются без условий. Если передан UID - метод вернёт информацию об уже существующем профиле с этим UID. Если UID пуст, но переданы все остальные параметры - будет создан новый профиль.

Параметры:	uid – uid hostname – имя хоста version – версия os_info – информация address – IP адрес
Результат:	список с данными профиля агента: [uid, token, profile_id]
Тип результата:	list

skydns_website.api.application.views.get_linux_supporting(request, tag=None, version=None)

JSONRPC Method: getLinuxSupporting

Получить версии Linux-агента: минимальную поддерживаемую (подлежащую принудительному обновлению) и текущую.

Параметры:	tag – тег для получения версий (по умолчанию - самая новая без разбора версии ОС) version – текущая версия установленного агента
Результат:	словарь вида: { ‘minimalSupported’: <минимально поддерживаемая версия (целое неотрицательное число)>, ‘current’: <текущая версия мобильного агента (целое неотрицательное число)>, ‘url’: <url до пакета>, ‘checksum’: <контрольная сумма пакета>, ‘announces’: анонсы версий, от version до последней, если version не указан, то все [ { ‘version’: <номер версии> ‘announce’: <анонс для этой версии> ] }
Тип результата:	dict

skydns_website.api.application.views.get_plans_list(request, mobile=False)

JSONRPC Method: getPlans

Получить список тарифных планов.

Параметры:	mobile – True - выдавать только мобильные планы, False - все
Результат:	список тарифов в формате: [ { ‘code’: код тарифа, ‘name’: название тарифа, ‘price’: стоимость тарифа, ‘trialPeriod’: сколько дней триального периода на тарифе, ‘period’: на сколько месяцев покупается тариф, ‘isMobile’: является ли тариф мобильным, ‘description’: URL страницы сайта с описанием тарифа ]
Тип результата:	list

skydns_website.api.application.views.get_popular_report(request, start, end, profile_id=None)

JSONRPC Method: getPopularReport

Отчет о популярных запросах пользователя за определенный период времени.

Параметры:	start – дата начала периода для получения статистики в формате YYYY-MM-DD end – дата окончания периода для получения статистики в формате YYYY-MM-DD profile_id – id профиля. Если не задан, будет создан отчёт по всем профилям пользователя
Результат:	словарь вида: { “labels”: [“example.com”, “google.com”, “asdfg.com”], “datasets”: [ {“label”: “Requests”, “data”: [630, 474, 290]}, {“label”: “NXdomain”, “data”: [0, 0, 290]}, {“label”: “Blocks”, “data”: [630, 0, 0]} ] }

skydns_website.api.application.views.get_ssl_certificate(request, version=1)

JSONRPC Method: getSSLCertificate

Получить ссылку на корневой SSL-сертификат СкайДНС.

Результат:	<прямая ссылка до сертификата>
Тип результата:	str

skydns_website.api.application.views.get_ssl_certificate_data_v2(request, version=1)

Получить ссылки на скачивание SSL-сертификатов СкайДНС.

 :return: {

“certs”: [
“cert/url”, “cert/url”
], “expires”: “YYYY-MM-DDTHH:MM:SS”

} :rtype: dict curl test request: curl –location –request POST ‘https://skynds.ru/api/json/v2‘ –header ‘Content-Type: application/json’ –data-raw ‘{

“id”: 0, “jsonrpc”: “2.0”, “method”: “getSSLCertificatesDataV2”, “params”: [“3”]
}’

>{
“id”:0,”jsonrpc”:”2.0”, “result”:{

“expires”:”2028-01-19T00:00:00”, “certs”:[

“https://www.skynds.ru/userfiles/certs/skydns_iss.crt”, “https://www.skynds.ru/userfiles/certs/skydns_root.crt“
]

}

}

skydns_website.api.application.views.get_user_plan_info(request)

JSONRPC Method: getPlan

Получить информацию о тарифе пользователя.

Результат:	информация о тарифе в формате: { ‘name’: название плана, ‘expired’: количество дней до истечения оплаченного периода, ‘isMobile’: поддерживает ли тариф мобильные устройства (true | false) }
Тип результата:	dict

skydns_website.api.application.views.get_version(request, tag=None)

JSONRPC Method: getAPCVersion

Получить версии мобильного приложения.

Параметры:	tag – тег для получения версий, по умолчанию ‘default’
Результат:	словарь вида: { ‘minimalSupported’: <минимально поддерживаемая версия (целое неотрицательное число)>, ‘current’: <текущая версия мобильного агента (целое неотрицательное число)> }
Тип результата:	dict

skydns_website.api.application.views.intentional_crash(request)

JSONRPC Method: intentionalCrash

Специальный метод, всегда выдающий JsonRpcRuntimeError.

Результат:	None

skydns_website.api.application.views.multi_schedule(request, profile)

JSONRPC Method: multiSchedule

Получить расписание фильтрации.

Параметры:	profile – профиль пользователя
Результат:	расписание фильтрации в формате: [ [<offset1>, <True|False>], [<offset2>, <True|False>], ... ]
Тип результата:	list

skydns_website.api.application.views.my_ip(request)

JSONRPC Method: myip

Получение текущего IP адреса клиента.

Результат:	IP адрес клиента
Тип результата:	str

skydns_website.api.application.views.profile_schedule_activity(request, profile)

JSONRPC Method: profileScheduleActivity

Получить количество минут до изменения состояния фильтрации профилей.

Параметры:	profile – профиль пользователя
Результат:	[<флаг: работает ли фильтрация по профилю>, <количество минут до смены состояния>] количество минут = -1, если расписание выключено или нет других состояний.

Пример:

first segment state last segment current offset
change | /

v v v v

|//////////| False |///////////////X/| 0———260———1090————–10k | True |///////////| True |

Тип результата:	list

skydns_website.api.application.views.profiles(request)

JSONRPC Method: profiles

Получение списка профилей.

Результат:

список профилей в формате: [ { ‘id’: id профиля, ‘default’: является ли профиль профилем по умолчанию, ‘token’: токен, ‘name’: название профиля, ‘white_list_only’: включена ли фильтрация только по белому списку, ‘is_schedule_enabled’: включено ли расписание, ‘safe_search_enabled’: статус безопасного поиска, ‘safe_youtube_enabled’: статус фильтрации YouTube (для API v2), ‘block_unknown_enabled’: статус фильтрации неизвестных сайтов (для API v2) ]

Тип результата:

list

skydns_website.api.application.views.register_user(request, username, password)

JSONRPC Method: register

Регистрация нового пользователя в облачном сервисе контент-фильтрации SkyDNS.

Параметры:	username – имя пользователя password – пароль создаваемого пользователя
Результат:	[True], если регистрация прошла успешно, [False, “error”] в противном случае
Тип результата:	list

skydns_website.api.application.views.remove_agent_profile(request, uid)

JSONRPC Method: removeAgentProfile

Метод удаляет AgentInfo отфильтрованный по заданному uid атрибуту.

Параметры:	uid – uid
Результат:	количество удалённых записей
Тип результата:	int

skydns_website.api.application.views.remove_domain(request, profile, choice, id)

JSONRPC Method: removeDomain

Удалить домен у заданного профиля.

TODO: параметр choice можно убрать и выбирать домен только по id.

Параметры:	profile – профиль пользователя choice – тип домена id – id домена
Результат:	None

skydns_website.api.application.views.remove_profile(request, profile)

JSONRPC Method: removeProfile

Метод удаляет указанный профиль.

Параметры:	profile – числовой id удаляемого профиля
Результат:	None

skydns_website.api.application.views.rename_profile(request, profile_id, name)

JSONRPC Method: renameProfile

Метод устанавливает новое имя для профиля. Возвращает актуальное имя.

Параметры:	profile_id – числовой id профиля, имя которого необходимо изменить name – новое имя профиля
Результат:	новое имя профиля
Тип результата:	string

skydns_website.api.application.views.send_debug_info(request, uid, info)

Отправить логи для отладки.

Параметры:	info – информация лога формата [{“command_title”: <log_name>, “command_info”” <log_message>}, ... ]
Результат:	количество созданных объектов

curl запрос для тестирования выглядит так: 

$ curl -X POST http://localhost:8000/api/json/v2 -L –user plantest-premium@skydns.ru:plantest1 -d ‘{“id”:0, > “jsonrpc”:”2.0”, “method”:”sendDebugInfo”, > “params”: [“uid”, [{“command_title”: <log_name>, “command_info”” <log_message>}]}’

skydns_website.api.application.views.send_log(request, profile_id=None, log_content='', os_info=None)

JSONRPC Method: sendLog

Фиксация в лог-файл лога пользователя с агентского решения.

Параметры:	profile – профиль пользователя log_content – лог пользователя os_info – версия системы
Результат:	True
Тип результата:	boolean

skydns_website.api.application.views.send_package(request, package, file_name, system_tag, version, checksum, announce)

JSONRPC Method: sendPackage

Загрузка новых версий агентов на сервер.

Параметры:	package – содержимое пакета в Base64 file_name – имя файла system_tag – тег версии ОС version – версия агента checksum – контрольная сумма announce – анонс версии
Результат:	True
Тип результата:	boolean

skydns_website.api.application.views.set_agent_profile(request, uid, profile_id)

JSONRPC Method: setProfile

Установить профиль AgentInfo.

Параметры:	uid – uid AgentInfo profile_id – id профиля, который требуется установить
Результат:	None

skydns_website.api.application.views.set_block_unknown_enabled(request, profile, flag)

JSONRPC Method: setBlockUnknownEnabled

Включить/выключить блокировку неизвестных сайтов.

Параметры:	profile – профиль пользователя flag – флаг включить/выключить
Результат:	None

skydns_website.api.application.views.set_categories(request, profile_id, cat_ids_list)

JSONRPC Method: setFilterCats

Метод привязывает список категорий фильтрации к профилю пользователя и возвращает актуальный список категорий.

Параметры:	profile_id – числовой id профиля cat_ids_list – список id категорий
Результат:	актуальный список id категорий
Тип результата:	list

skydns_website.api.application.views.set_category(request, profile, cat, state)

JSONRPC Method: setFilterCat

Метод позволяет изменить состояние фильтра для категории.

Параметры:	profile – профиль пользователя cat – числовой id категории state – булево значение состояния категории (true/false)
Результат:	None

skydns_website.api.application.views.set_filtering_status(request, enabled)

JSONRPC Method: setFilteringStatus

Установить состояние фильтрации пользователя. :param enabled: состояние фильтрации для установки

Результат:	<состояние фильтрации>
Тип результата:	bool

skydns_website.api.application.views.set_networks(request, profile, hostname)

JSONRPC Method: updateNic

Установить динамический IP адрес. IP адрес определяется автоматически из запроса.

Параметры:	profile – профиль пользователя hostname – имя хоста
Результат:	установленный IP адрес
Тип результата:	str

skydns_website.api.application.views.set_safe_search(request, profile, flag)

JSONRPC Method: setSafeSearchEnabled

Включить/выключить работу по безопасному поиску.

Параметры:	profile – профиль пользователя flag – флаг включить/выключить
Результат:	None

skydns_website.api.application.views.set_safe_youtube(request, profile, flag)

JSONRPC Method: setSafeYoutubeEnabled

Включить/выключить безопасный Youtube.

Параметры:	profile – профиль пользователя flag – флаг включить/выключить
Результат:	None

skydns_website.api.application.views.set_whitelist(request, profile, flag)

JSONRPC Method: setWhiteListOnly

Включить/выключить работу по белому списку.

Параметры:	profile – профиль пользователя flag – флаг включить/выключить
Результат:	None

skydns_website.api.application.views.system_info(request)

JSONRPC Method: systemInfo

Получение информации о настройках системы.

Результат:	системная информация в формате: { ‘public_dns’: DNS, ‘nxdomain’: NX domain, ‘blockpage’: blockpage, ‘blockpage_token’: blockpage token, ‘blockapi’: block api }
Тип результата:	dict

skydns_website.api.application.views.test_auth(request, username, password)

JSONRPC Method: testAuth

Аутентификация пользователя.

Результат:	результат аутентификации (true или false)
Тип результата:	bool

skydns_website.api.application.views.user_filter(request, profile)

JSONRPC Method: userFilter

Получить список категорий профиля пользователя.

Результат:	список id категорий профиля
Тип результата:	list

skydns_website.api.application.views.user_info(request)

JSONRPC Method: userInfo

Получить информацию о пользователе.

Результат:	информация о пользователе в формате: { ‘username’: юзернейм, ‘plan’: { ‘name’: название тарифного плана, ‘code’: код тарифного плана, ‘date_end’: дата конца оплаченного периода, ‘features’: { название_опции: значение, ... }, }, ‘tz’: смещение от UTC в часах, ‘tz_minutes’: смещение от UTC в минутах }
Тип результата:	dict

Использование API подписки SkyDNS

Провайдеру выдается публичный ключ, который используется для аутентификации и подписывания запросов.

Все запросы выполняются через протокол HTTPS. С помощью GET запросов. Каждый запрос должен содержать публичный ключ провайдера с именем параметра key.

Например:

curl "https://www.skydns.ru/provider_api/{имя метода}?key=abcd&a=1&b=1"

Предупреждение

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

На данный момент доступны следующие методы API:

• subscribe - зарегистрировать пользователя в системе с переданными реквизитами и установить тариф провайдера по умолчанию.
• subscribe_plans - получить список доступных тарифов для создания/изменения пользователя реселлером.
• activate - активировать пользователя провайдера.
• deactivate - деактивировать пользователя провайдера.
• update_email - обновить email пользователя для восстановления пароля и получения информационных сообщений.
• update_password - обновить пароль пользователя.
• prolongate - включить или изменить платный тариф для пользователя. Этот метод всегда должен вызываться после метода subscribe для включения услуги пользователю.
• unsubscribe - отключить пользователя и переключить на бесплатный тариф.
• subscription_info - получить информацию о дате окончания подписки.
• profiles – получить список активных профилей пользователя.
• create_profile - создать профиль.
• update_profile – изменить параметры профиля пользователя реселлера.
• add_ip - добавить один или несколько статических IP адресов пользователя.
• clear_ip - удалить все статические IP адреса на профиле пользователя.
• list_ip - получить список всех статических IP адресов пользователя.
• update_ip - создать или обновить динамический IP адрес пользователя и привязать его к необходимому профилю фильтрации.
• remove_ip - удалить IP адрес пользователя.
• add_vpn - создать VPN-сертификат для профиля и получить профиль настройки OpenVPN.
• clear_vpn_for_profile - удалить все vpn-соединения на профиле пользователя.
• clear_vpn_for_user - удалить все vpn-соединения на всех профилях пользователя.
• get_vpn_list - получить список всех vpn-соединений пользователя.
• remove_vpn - удалить vpn-соединение пользователя.
• update_nat - добавить или обновить привязку профиля к DNS адресам для пользователей за NAT.
• get_activity - получить информацию об активности пользователя за определенную дату.
• get_activity_report - получить отчет об активности пользователя за определенный период времени.
• get_list_activity_report - отчет об активности пользователя за определенный период времени.
• get_popular_report - получить отчет о популярных запросах пользователя за определенный период времени.
• get_category_report - получить отчет по категориям пользователя за определенный период времени.
• send_monthly_stat - отправить статистику за месяц пользователю по электронной почте.
• get_daily_stat - получить статистику пользователя за день.
• get_active_users - получить список активных пользователей и их тарифы.

Внимание

API доступно по адресу: https://www.skydns.ru/provider_api/

Примечание

Вызывается по схеме: https://www.skydns.ru/provider_api/{имя метода}?{GET параметры запроса}

Доступные методы

subscribe

Зарегистрировать пользователя в системе с переданными реквизитами и установить тариф по умолчанию.

Передается 1 обязательный параметр:

Может передаваться 4 необязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "username": "username",
            "email": "email",
            "plan": "tariff_name"
        }
    }
}

subscribe_plans

Получить список доступных тарифов для создания/изменения пользователя реселлером.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "plan1": "tariff_name1",
            "plan2": "tariff_name2"
        }
    }
}

activate

Активировать пользователя провайдера.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

deactivate

Деактивировать пользователя провайдера.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

update_email

Обновить email пользователя для восстановления пароля и получения информационных сообщений.

Передается 2 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

update_password

Обновить пароль пользователя.

Передается 2 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

prolongate

Включить или изменить платный тариф для пользователя. Этот метод всегда должен вызываться после метода subscribe для включения услуги пользователю.

Передается 1 обязательный параметр:

Может передаваться 1 необязательный параметр:

Eсли параметр plan не передан, то по умолчанию включается план PREMIUM.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

unsubscribe

Отключить пользователя и переключить на бесплатный тариф.

Передается 1 параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

subscription_info

Получить информацию о дате окончания подписки.

Передается 1 параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "date_end": 1390930655
        }
    }
}

Примечание

Дата окончания в unix time.

Предупреждение

В настоящее время не используется, зарезервировано для будущего использования.

profiles

Получить список активных профилей пользователя.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "ид профиля 1": "имя профиля",
            "ид профиля 2": "имя профиля",
            "ид профиля 3": "имя профиля"
        }
    }
}

Примечание

“имя профиля” передается в кодировке utf-8.

create_profile

Создать профиль.

Передается 2 обязательных параметра:

Дополнительно можно передать 2 необязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

update_profile

Изменить параметры профиля пользователя реселлера.

Передается 1 обязательный параметр:

Дополнительно можно передать 2 необязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "id": "profile_id",
            "name": "profile_name",
            "tls": "True|False"
        }
    }
}

add_ip

Добавить один или несколько статических IP адресов пользователя.

Передаeтся 2 обязательных параметра:

Дополнительно можно передать 2 необязательных параметра:

Если параметр profile не будет передан, то IP адреса будут привязаны к профилю “По умолчанию”.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "added_addresses": ["1.1.1.1", "1.1.1.2"]
        }
    }
}

Если какие-то из переданных адресов не удалось добавить, то дополнительно будет выведен их список:

{
    "response": {
        "status": "ok",
        "data": {
            "added_addresses": ["1.1.1.1", "1.1.1.2"],
            "invalid_adresses": [
                {"1.invalid.ip.adress": "IP address is invalid"},
                {"0.0.0.0": "This address is not public"}
            ]
        }
    }
}

clear_ip

Удалить все статические IP адреса на профиле пользователя.

Передается 2 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

list_ip

Получить список всех статических IP адресов пользователя.

Передается 1 обязательный параметр:

Дополнительно можно передать 1 необязательный параметр:

Если параметр profile не будет передан, то IP адреса будут получены для всех профилей.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "ip": [
                {"address": "1.2.3.4", "comment": "example.com"},
                {"address": "1.2.3.5", "comment": "example.com"}
            ],
        }
    }
}

update_ip

Создать или обновить динамический IP адрес пользователя и привязать его к необходимому профилю фильтрации.

Передается 2 обязательных параметра:

Предоставленный IP адрес будет установлен на профиле Основной указанного пользователя. Если предоставленный IP уже привязан к другому пользователю провайдера, то привязка будет убрана и IP адрес будет привязан к указанному в методе пользователю.

Дополнительно можно передать 2 необязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

remove_ip

Удалить IP адрес пользователя.

Передается 2 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

add_vpn

Создать VPN-сертификат для профиля и получить профиль настройки OpenVPN.

Передается 3 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "ovpn": "client\nremote vpn.skydns.ru 1194 udp\nnobind\ndev tun\npersist-tun\npersist-key\nverify-x509-name vpn.skydns.ru name\nremote-cert-tls server\ncipher AES-128-CBC\n\n<ca>\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</ca>\n<cert>\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</cert>\n<key>\n-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n</key>\n"
        }
    }
}

Примечание

Если лимит VPN-соединений исчерпан, попытка добавить новое завершится ошибкой.

clear_vpn_for_profile

Удалить все vpn-соединения на профиле пользователя.

Передается 1 обязаетельный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

clear_vpn_for_user

Удалить все vpn-соединения на всех профилях пользователя.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

get_vpn_list

Получить список всех vpn-соединений пользователя.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": [
            {"id": "vpn_id1", "profile": "profile_name", "ip": "vpn_hostname1", "name": "vpn_name1"},
            {"id": "vpn_id2", "profile": "profile_name", "ip": "vpn_hostname2", "name": "vpn_name2"}
        ]
    }
}

remove_vpn

Удалить vpn-соединение пользователя.

Передается 1 обязательный параметр:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

update_nat

Добавить или обновить привязку профиля к DNS адресам для пользователей за NAT.

Передается 2 обязательных параметра:

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

get_activity

Получить информацию об активности пользователя за определенную дату.

Передается 1 обязательный параметр:

Дополнительно можно передать 2 необязательных параметра:

Значение параметра date должно быть не ранее, чем 1 января предыдущего года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "requests": "2600",
            "blocks": "581"
        }
    }
}

Примечание

Где requests - это общее количество запросов за указанную дату, blocks - количество блокировок.

get_activity_report

Получить отчет об активности пользователя за определенный период времени.

Передается 3 обязательных параметра:

Дополнительно можно передать 1 необязательный параметр:

Если диапазон start - end охватывает более чем 30 суток, то в отчет попадают только последние 30 из них.

Начало периода start должно быть не ранее, чем 1 января предыдущего года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "labels": [
                "2016-06-29 14:00:00",
                "2016-06-29 15:00:00"
            ],
            "datasets": [
                {
                    "label": "Requests",
                    "data": [375, 275]
                },
                {
                    "label": "Blocks",
                    "data": [13, 0]
                }
            ]
        }
    }
}

Примечание

Где labels - список значений для оси времени. datasets - список словарей содержащих наборы данных по определенном параметрам отчета, label - название параметра отчета, data - список значений соответстующих датам из списка labels.

Примечание

В datasets используются следующие наборы данных: Requests - количество запросов, Blocks - количество блокировок.

get_list_activity_report

Получить отчет об активности пользователя за определенный период времени.

Передается 3 обязательных параметра:

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

https://skydns.ru/provider_api/get_list_activity_report/?key=supersecretkey&start=2023-04-01&end=2023-04-17&ident=username1&ident=username2

Ответ возвращается в формате JSON следующего вида:

{
    "data": {
        "2023-04-03": {
            "username1": {
                "visits": 28251,
                "blocks": 1106
            },
            "username2": {
                "visits": 4854,
                "blocks": 760
            }
        },
    }
}

get_popular_report

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

Передается 3 обязательных параметра:

Дополнительно можно передать 1 необязательный параметр:

Если диапазон start - end охватывает более чем 30 суток, то в отчет попадают только последние 30 из них.

Начало периода start должно быть не ранее, чем 1 января предыдущего года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "labels": ["example.com", "google.com", "asdfg.com"],
            "datasets": [
                {
                    "label": "Requests",
                    "data": [630, 474, 290]
                },
                {
                    "label": "NXdomain",
                    "data": [0, 0, 290]
                },
                {
                    "label":"Blocks",
                    "data":[630, 0, 0]
                }
            ]
        }
    }
}

Примечание

Где labels - список значений для оси времени. datasets - список словарей содержащих наборы данных по определенном параметрам отчета, label - название параметра отчета, data - список значений соответстующих датам из списка labels.

Примечание

в datasets используются следующие наборы данных: Requests - количество запросов, Blocks - количество блокировок, NXdomain - количество неразрезолвенных доменов.

get_category_report

Получить отчет по категориям пользователя за определенный период времени.

Передается 3 обязательных параметра:

Дополнительно можно передать 1 необязательный параметр:

Если диапазон start - end охватывает более чем 30 суток, то в отчет попадают только последние 30 из них.

Начало периода start должно быть не ранее, чем 1 января предыдущего года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "Фильмы и видео онлайн": "5",
            "Файловые архивы": "2",
            "Дом, семья, хобби": "3"
        }
    }
}

Примечание

Где data - представляет собой словарь, ключ - название категории, значение - количество посещений.

send_monthly_stat

Отправить пользователю по электронной почте статистику за месяц.

Передается 3 обязательных параметра:

Дополнительно можно передать 1 необязательный параметр:

На email пользователя будет выслан отчет в формате CSV со статистикой за указанный месяц. Отчет содержит следующие столбцы: “Timestamp”, “Domain name”, “Visits”, “Blocks”, “Profile”, “Categories”.

Значение параметра year должно быть не меньше прошлого года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok"
    }
}

get_daily_stat

Получить статистику пользователя за день.

Передается 2 обязательных параметра:

Дополнительно можно передать 2 необязательных параметра:

Значение параметра date должно быть не ранее, чем 1 января предыдущего года.

Ответ возвращается в формате JSON следующего вида:

{
    "response": {
        "status": "ok",
        "data": {
            "result": "ссылка на файл"
        }
    }
}

get_active_users

Получить список активных пользователей и их тарифы.

Ответ возвращается в формате JSON следующего вида:

{
    "data": [
        {
            "username": "username1",
            "plan_name": "Бизнес"
        },
        {
            "username": "username1",
            "plan_name": "Школа"
        },
    ]
}