СтатьиDiscussions
Статьи

TD API 2.0 - How to begin working

Suggest Edits

📘

Адрес для отправки запросов

https://tdm4.adcloud.org/api/v2/?method=MethodName

В качестве get-параметра необходимо передавать название метода, что позволит динамически определить метод через URL-строку.

API Trading Desk основана на использовании протокола JSON-RPC 2.0.

JSON-RPC 2.0

JSON-RPC 2.0 работает, отсылая запросы к серверу, реализующему протокол. Клиентом обычно является программа, которой нужно вызвать метод на удалённой системе. Множество входных параметров может быть передано удалённому методу как массив или запись. Метод также может вернуть множество выходных данных. Удалённый метод вызывается отправлением запроса на удалённый сервер посредством HTTP или TCP/IP-сокета При использовании HTTP заголовок Content-Type определяется как application/json.

Все передаваемые данные - простые записи, сериализованные в JSON.

Запрос

Запрос - вызов определённого метода, предоставляемого удалённой системой. Он должен содержать три обязательных свойства:

  • method - строка с именем вызываемого метода.
  • params - массив данных, которые должны быть переданы методу, как параметры.
  • id - значение любого типа, которое используется для установки соответствия между запросом и ответом.

Ответ

Сервер отсылает правильный ответ на каждый полученный запрос. Ответ должен содержать следующие свойства:

  • result - данные, которые вернул метод. Если произошла ошибка во время выполнения метода, это свойство должно быть установлено в null.
  • error - код ошибки, если произошла ошибка во время выполнения метода, иначе null.
  • id - то же значение, что и в запросе, к которому относится данный ответ.

Для ситуаций, когда ответ не требуется, были введены уведомления. Уведомление отличается от запроса отсутствием свойства id, которое не требуется, так как не будет передан ответ. В таком случае свойство id будет пропущено (для версия 2.0).

Подробнее о спецификации протокола можете прочитать в официальных источниках.

Токен доступа

Токен нужен, чтобы иметь возможность выполнять доступные пользователю методы API.

В TD существует два способа авторизации для получения токена доступа:

  1. Через Администратора

Чтобы получить токен доступа пользователю необходимо написать Администратору, сообщить ему почту и все необходимые для авторизации данные. Такой токен имеет время жизни 3 месяца.

  1. Методом авторизации

Как только токен получен, то далее можно его использовать в запросах к API. Запрос к API должен содержать HTTP-заголовок Authorization с OAuth-токеном пользователя, от имени которого выполняется запрос:

-H 'Authorization: Bearer TOKEN'
  • Authorization - название HTTP-заголовка.
  • Bearer - служебная константа протокола OAuth (обязательна к указанию).
  • TOKEN - полученный пользователем токен.

Например,

curl -X POST -H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ0..._7JU'
-X POST -d '
{
  "jsonrpc": "2.0", 
  "method": "Statistic.getTarget", 
  "params": {...}, 
  "id": 1 
}' https://tdm4.adcloud.org/api/v2/?method=Statistic.getTarget

Пользовательские методы

Метод "User.auth"

Чтобы получить токен доступа пользователю необходимо вызвать метод "User.auth". Токен, полученный с использованием данного метода, имеет время жизни 7 дней.

Параметры запроса:

  • "email" - e-mail пользователя,
  • "password" - пароль пользователя.

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

  • "access_token" - токен доступа,
  • "refresh_token" - токен обновления,
  • "expire_access_token" - время жизни токена доступа,
  • "expire_refresh_token" - время жизни токена обновления.

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

// Запрос
{
  "jsonrpc": "2.0",
  "method": "User.auth",
  "params": {
    "email": "string",
    "password": "string"
  },
  "id": 1
}

// Ответ
{
  "jsonrpc": "2.0",
  "result": {
    "access_token": "string",
    "refresh_token": "string",
    "expire_access_token": 0,
    "expire_refresh_token": 0
  },
  "id": 1
}

Метод "User.tokenRefresh"

Для обновления токена доступа, полученного самостоятельно методом авторизации, необходимо вызвать метод "user.tokenRefresh". Refresh token имеет время жизни 60 дней.

Refresh token используется для обновления access и refresh токенов. Помимо обновления использование схемы refresh + access токенов ограничивает время, на которое атакующий может получить доступ к сервису, что обеспечивает дополнительную защиту и безопасность.

Параметры запроса:

  • "refresh_token" - значение Refresh токена, полученное методом авторизации.

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

  • "access_token" - токен доступа,
  • "refresh_token" - токен обновления,
  • "expire_access_token" - время жизни токена доступа,
  • "expire_refresh_token" - время жизни токена обновления.

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

// Запрос
{
  "jsonrpc": "2.0",
  "method": "User.tokenRefresh",
  "params": {
    "refresh_token": "string"
  },
  "id": 1
}

// Ответ
{
  "jsonrpc": "2.0",
  "result": {
    "access_token": "string",
    "refresh_token": "string",
    "expire_access_token": 0,
    "expire_refresh_token": 0
  },
  "id": 1
}

📘

Обратите внимание

У пользователя может быть одновременно два токена доступа: полученный на 3 месяца от Администратора и полученный самостоятельно вызовом метода авторизации.

Метод "User.getInfo"

Для получения основной информации о пользователе необходимо вызвать метод "User.getInfo".

Параметры запроса: метод вызывается без параметров.

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

  • "email" - почта пользователя,
  • "auth_token" - токен доступа, выданный администратором. Данный токен имеет время жизни 3 месяца, подробнее читайте в разделе,
  • "tags" - список РК, доступных пользователю,
  • "groups" - список ролей, доступных пользователю, для просмотра статистики достаточно роли "default"
  • "methods" - список доступных методов,
  • "isActive" - статус пользователя: true - активен, false - заблокирован.
  • "date_create" - информация о регистрации пользователя (дата, сведения о таймзоне)

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

// Запрос
{
  "jsonrpc": "2.0",
  "method": "User.getInfo",
  "params": {},
  "id": 1
}

// Ответ
{
    "jsonrpc": "2.0",
    "result": {
        "email": "[email protected]",
        "auth_token": "eyJ...pLo",
        "tags": [
            {
                "title": "Test1_Jul23"
            },
            {
                "title": "Test2_Jul23"
            }
        ],
        "groups": [
            {
                "id": 1,
                "title": "default"
            }
        ],
        "methods": [
            "User.auth",
            "User.tokenRefresh",
            "Campaign.getList",
            "Campaign.getInfo",
            "Partner.getClients",
            "Report.getCoverageAndInspection",
            "User.getInfo"
        ],
        "isActive": false,
        "date_create": {
            "date": "2023-10-27 14:21:52.000000",
            "timezone_type": 3,
            "timezone": "Europe/Moscow"
        }
    },
    "id": 1
}

Updated 6 months ago