2Safe API — различия между версиями

Материал из Rosalab Wiki
Перейти к: навигация, поиск
Строка 1: Строка 1:
h1.  Модель вызова функций в API (JSON)  
+
= Модель вызова функций в API (JSON) =
  
 
Передаём параметры любым способом (POST, GET)
 
Передаём параметры любым способом (POST, GET)
 
 
https://api.2safe.com/?cmd=команда
 
https://api.2safe.com/?cmd=команда
 
 
https://apiqa.2safe.com/?cmd=команда        QA сервер
 
https://apiqa.2safe.com/?cmd=команда        QA сервер
  
Строка 12: Строка 10:
 
{
 
{
 
"error_code": "006", // код ошибки, в случае ошибки
 
"error_code": "006", // код ошибки, в случае ошибки
"error_msg": "Command not found" // сообщение, в случае ошибки
+
"error_msg": "Command not found" // сообщение, в случае ошибки
 
}
 
}
 
</pre>
 
</pre>
 
Код ошибки и сообщение с ошибкой возвращается во всех командах, ТОЛЬКО при возникновении ошибки.
 
Код ошибки и сообщение с ошибкой возвращается во всех командах, ТОЛЬКО при возникновении ошибки.
  
h2. Проверка доступности e-mail
+
== Пользовательские функции ==
  
<cmd: chk_mail
+
=== Проверка доступности e-mail ===
  
 +
<cmd: '''chk_mail'''
 
<email:
 
<email:
  
Строка 32: Строка 31:
 
</pre>
 
</pre>
  
h2. Проверка доступности логина
+
=== Проверка доступности логина ===
 
+
<cmd: chk_login
+
  
 +
<cmd: '''chk_login'''
 
<login:
 
<login:
  
Строка 47: Строка 45:
 
</pre>
 
</pre>
  
h2. Получение капчи
+
===Получение капчи===
  
<cmd: get_captcha
+
<cmd: '''get_captcha'''
  
 
Ответ будет получен как при обычном GET запросе (изображение image/png) с заголовком "Set-Cookie: captcha2safe=1000", где 1000 - id капчи.
 
Ответ будет получен как при обычном GET запросе (изображение image/png) с заголовком "Set-Cookie: captcha2safe=1000", где 1000 - id капчи.
 
Код действителен в течении 10 минут.
 
Код действителен в течении 10 минут.
  
h2. Регистрация пользователя
+
===Регистрация пользователя===
 
+
<cmd: add_login
+
  
 +
<cmd: '''add_login'''
 
<login:
 
<login:
 
 
<password:
 
<password:
 
 
<email:
 
<email:
 
 
<captcha:  // защитный код, полученный предварительным запросом get_captcha, если код не верен, то необходимо заново получить капчу.
 
<captcha:  // защитный код, полученный предварительным запросом get_captcha, если код не верен, то необходимо заново получить капчу.
 
 
<id:  // id капчи, который находится в заголовке ответа на запрос get_captcha или в cookie c именем captcha2safe
 
<id:  // id капчи, который находится в заголовке ответа на запрос get_captcha или в cookie c именем captcha2safe
  
Строка 72: Строка 65:
 
"response" : {
 
"response" : {
 
"success" : "true", // true в случае успеха
 
"success" : "true", // true в случае успеха
"root" : "17050000001", // id корневой папки
+
"root" : "17050000001", // id корневой папки
 
"id" : "1033000001" // id пользователя
 
"id" : "1033000001" // id пользователя
 
}
 
}
Строка 78: Строка 71:
 
</pre>
 
</pre>
  
h2. Авторизация пользователя
+
===Авторизация пользователя===
 
+
<cmd:auth  // команда
+
  
 +
<cmd: '''auth'''  // команда
 
<login:
 
<login:
 
 
<password:
 
<password:
 
+
Опциональные параметры:
<format: // по умолчанию JSON - параметр может использоваться во всех запросах к API  
+
<format: // по умолчанию JSON - параметр может использоваться во всех запросах к API
 
+
<captcha_id: // После трёх и более неправильных попыток авторизации необходимо получить новую капчу '''get_captcha'''
 +
<captcha: // и передать эти два параметра
  
 
<pre>
 
<pre>
Строка 93: Строка 85:
 
"response" : {
 
"response" : {
 
"success" : "true",
 
"success" : "true",
"id" : "1033000001", // id пользователя
+
"id" : "1033000001", // id пользователя
 
"token" : "e726e3df64a55ceff84754e3157053cc" // token для дальнейших действий
 
"token" : "e726e3df64a55ceff84754e3157053cc" // token для дальнейших действий
 
}
 
}
Строка 99: Строка 91:
 
</pre>
 
</pre>
  
h2. Удаление пользователя
+
Срок действия token - 24 часа. После каждого обращения к API - срок действия токена обновляется и становится равным 24 часам.
 +
По истечении token'а необходимо заново авторизоваться.
  
<cmd: remove_login
+
===Удаление пользователя===
  
 +
<cmd: '''remove_login'''
 
<login:
 
<login:
 
 
<password:
 
<password:
  
Строка 119: Строка 112:
 
</pre>
 
</pre>
  
h2. Удаление сессии (logout)
+
===Удаление сессии (logout)===
 
+
<cmd: logout
+
  
 +
<cmd: '''logout'''
 
<token:
 
<token:
  
Строка 133: Строка 125:
 
</pre>
 
</pre>
  
h2. Просмотр квоты
+
===Просмотр квоты===
 
+
<cmd: get_disk_quota
+
  
 +
<cmd: '''get_disk_quota'''
 
<token:
 
<token:
  
Строка 143: Строка 134:
 
"response" : {
 
"response" : {
 
"quotas" : {
 
"quotas" : {
"used_bytes" : 121404289,     // использовано
+
"used_bytes" : 121404289, // использовано
"total_bytes" : 2048000000   // всего
+
"total_bytes" : 2048000000 // всего
 
},
 
},
 
"success" : "true"
 
"success" : "true"
Строка 151: Строка 142:
 
</pre>
 
</pre>
  
h2. Получение карточки юзера
+
===Получение карточки юзера===
 
+
<cmd: get_personal_data
+
  
 +
<cmd: '''get_personal_data'''
 
<token:
 
<token:
  
Строка 177: Строка 167:
 
</pre>
 
</pre>
  
h2. Изменение карточки юзера
+
===Изменение карточки юзера===
 
+
<cmd: set_personal_data
+
  
 +
<cmd: '''set_personal_data'''
 
<token:
 
<token:
 
 
<personal:  // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"}
 
<personal:  // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"}
 
+
Опциональный параметр:
 
<props:      // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 
<props:      // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 +
<password // обязательное поле только при смене email
  
 
<pre>
 
<pre>
 
 
{
 
{
 
"response" : {
 
"response" : {
Строка 196: Строка 184:
 
</pre>
 
</pre>
  
h2. Смена пароля
+
При изменении email необходимо передавать текущий пароль в параметр password.
  
<cmd: change_password
+
===Смена пароля===
  
 +
<cmd: '''change_password'''
 
<login:
 
<login:
 
 
<password:
 
<password:
 
 
<new_password:
 
<new_password:
  
Строка 214: Строка 201:
 
</pre>
 
</pre>
  
h2. Получение файла
+
===Активация промо кода===
  
<cmd: get_file
+
<cmd: '''activate_promo_code'''
 +
<token:
 +
<\code:
  
<id:         // id файла
+
<pre>
 +
{
 +
"response" : {
 +
"quotas" : {
 +
"used_bytes" : 121404289, // использовано
 +
"total_bytes" : 5368709120, // всего
 +
"difference": 2048000000 // сколько добавлено за счёт активации кода
 +
},
 +
"success" : "true"
 +
}
 +
}
 +
</pre>
  
<token:
+
После трёх неудачных попыток введения промо кода - таймаут 5 минут.
  
<size:
+
== Функции по работе с файловой системой --
  
 +
===Получение файла===
 +
 +
<cmd: '''get_file'''
 +
<id:        // id файла
 +
<token:
 +
Опциональные параметры:
 +
<size:
 
<offset:
 
<offset:
  
 
Ответ будет получен как при обычном GET запросе, без учёта формата запроса (JSON,XML и т.д.)
 
Ответ будет получен как при обычном GET запросе, без учёта формата запроса (JSON,XML и т.д.)
  
h2. Заливка файла
+
===Заливка файла===
  
 
Загрузка файлов производится методом POST (multipart/form-data)
 
Загрузка файлов производится методом POST (multipart/form-data)
  
<cmd: put_file
+
<cmd: '''put_file'''
 
+
 
<dir_id:        // id папки назначения
 
<dir_id:        // id папки назначения
 
 
<file:      // файл
 
<file:      // файл
 
 
<token:
 
<token:
 
 
Опциональные параметры:
 
Опциональные параметры:
 
 
<overwrite // автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка
 
<overwrite // автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка
 
+
<versioned: // если файл существует, то создаётся новая версия файла, независимо от флага overwrite
<versioned: // если файл существует, то создаётся новая версия файла
+
 
+
 
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 
 
<ctime            // дата создания (в формате timestamp)
 
<ctime            // дата создания (в формате timestamp)
 
 
<mtime            // дата модификации (в формате timestamp)  
 
<mtime            // дата модификации (в формате timestamp)  
 +
<name            // имя для файла в системе
  
 
<pre>
 
<pre>
Строка 260: Строка 259:
 
"chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4",
 
"chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4",
 
"name" : "Brazil - Lagoa.jpg",
 
"name" : "Brazil - Lagoa.jpg",
"oid" : "17330000001",
+
"version_id" : "17330000001",
 
"type" : "image/jpeg",
 
"type" : "image/jpeg",
 
"id" : "17329000001",
 
"id" : "17329000001",
Строка 269: Строка 268:
 
</pre>
 
</pre>
  
h2. Копирование файлов
+
===Копирование файлов===
 
+
<cmd: copy_file
+
  
 +
<cmd: '''copy_file'''
 
<id:                //  id файла
 
<id:                //  id файла
 
 
<dir_id:      // id папки куда, копируется файл
 
<dir_id:      // id папки куда, копируется файл
 
+
<token:
<token:
+
Опциональные параметры:
 
+
 
<overwrite: // если файл существует, то он перезаписывается
 
<overwrite: // если файл существует, то он перезаписывается
 
 
<versioned: // если файл существует, то создаётся новая версия файла
 
<versioned: // если файл существует, то создаётся новая версия файла
 
 
<file_name:    // новое имя файла (для копирования с переименовыванием)
 
<file_name:    // новое имя файла (для копирования с переименовыванием)
  
Строка 293: Строка 287:
 
</pre>
 
</pre>
  
h2. Перемещение файлов
+
===Перемещение файлов===
  
<cmd: move_file
+
<cmd: '''move_file'''
 
+
<id:                 //  id файла
<id:
+
                //  id файла
+
 
<dir_id:      // id папки куда, перемещаем файл
 
<dir_id:      // id папки куда, перемещаем файл
 
+
<token:
<token:
+
Опциональные параметры:
 
+
 
<overwrite: // если файл существует, то он перезаписывается
 
<overwrite: // если файл существует, то он перезаписывается
 
 
<versioned: // если файл существует, то создаётся новая версия файла
 
<versioned: // если файл существует, то создаётся новая версия файла
 
+
<file_name:   // новое имя файла (для перемещения с переименовыванием либо переименовыванием)
<file_name:   // новое имя файла (для перемещения с переименовыванием)
+
  
 
<pre>
 
<pre>
 
{
 
{
 
"response" : {
 
"response" : {
"success" : "true", // true в случае успеха
+
"success" : "true", // true в случае успеха
                "id" : "17329000001"               // новый id файла
+
"id" : "17329000001" // новый id файла
 
}
 
}
 
}
 
}
 
</pre>
 
</pre>
  
h2. Удаление файлов
+
id файла изменяется только при перемещении, кроме перемещения в корзину.
 +
Переименовывание файла происходит так же со сменой id.
  
<cmd: remove_file
+
===Удаление файлов===
  
 +
<cmd: '''remove_file'''
 
<id:                //  id файла
 
<id:                //  id файла
 
 
<token:
 
<token:
 +
Опциональный параметр:
 +
<remove_now      // удаление минуя корзину (Аналог Shift+Del)
  
 
<pre>
 
<pre>
Строка 334: Строка 326:
 
</pre>
 
</pre>
  
h2. Создание директорий
+
При первом удалении файл удаляется в корзину (папка Trash), при повторном выполнении ф-ии - файл удаляется навсегда.
 +
При попадании в корзину файлу присваивается флаг '''old_path''' с полным путём, откуда он был удалён.
  
<cmd: make_dir
+
===Создание директорий===
  
 +
<cmd: '''make_dir'''
 
<dir_id:              // id корневой паки
 
<dir_id:              // id корневой паки
 
 
<dir_name:  // имя папки
 
<dir_name:  // имя папки
 
 
<token:
 
<token:
 
 
Опциональные параметры:
 
Опциональные параметры:
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение  
+
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
{"key1":"value1","key2":"value2","keyN":"valueN"}
+
 
<ctime            // дата создания (в формате timestamp)
 
<ctime            // дата создания (в формате timestamp)
 
 
<mtime            // дата модификации (в формате timestamp)  
 
<mtime            // дата модификации (в формате timestamp)  
  
Строка 360: Строка 349:
 
</pre>
 
</pre>
  
h2. Копирование директорий
+
===Копирование директорий===
 
+
<cmd: copy_dir
+
  
 +
<cmd: '''copy_dir'''
 
<id:                //  id src каталога
 
<id:                //  id src каталога
 
 
<dir_id:      // id корневого dst каталога
 
<dir_id:      // id корневого dst каталога
 
+
<token:
<token:
+
Опциональные параметры:
 
+
 
<overwrite: // автоматически перезаписывать файлы и папки
 
<overwrite: // автоматически перезаписывать файлы и папки
 
 
<versioned: // если файл существует, то создаётся новая версия файла
 
<versioned: // если файл существует, то создаётся новая версия файла
 
 
<dir_name:    // новое имя папки (для копирования с переименовыванием)
 
<dir_name:    // новое имя папки (для копирования с переименовыванием)
  
Строка 384: Строка 368:
 
</pre>
 
</pre>
  
h2. Перемещение директорий
+
===Перемещение директорий===
 
+
<cmd: move_dir
+
  
 +
<cmd: '''move_dir'''
 
<id:                //  id src каталога
 
<id:                //  id src каталога
 
 
<dir_id:      // id корневого dst каталога
 
<dir_id:      // id корневого dst каталога
 
+
<token:
<token:
+
Опциональные параметры:
 
<overwrite: // автоматически перезаписывать файлы
 
<overwrite: // автоматически перезаписывать файлы
 
 
<versioned: // если файл существует, то создаётся новая версия файла
 
<versioned: // если файл существует, то создаётся новая версия файла
 
+
<dir_name:    // новое имя папки (для перемещения с переименовыванием либо переименовыванием)
<dir_name:    // новое имя папки (для перемещения с переименовыванием)
+
  
 
<pre>
 
<pre>
Строка 407: Строка 387:
 
</pre>
 
</pre>
  
h2. Удаление директорий
+
===Удаление директорий===
 
+
<cmd: remove_dir
+
  
 +
<cmd: '''remove_dir'''
 
<dir_id:                // id каталога
 
<dir_id:                // id каталога
 
 
<token:
 
<token:
 
+
Опциональные параметры:
<recursive           // рекурсивное удаление
+
<recursive // рекурсивное удаление
 +
<remove_now // удаление минуя корзину (Аналог Shift+Del)
  
 
<pre>
 
<pre>
Строка 425: Строка 404:
 
</pre>
 
</pre>
  
h2. Просмотр директорий
+
При первом удалении папка удаляется в корзину (в папку Trash), при повторном выполнении ф-ии - папка удаляется навсегда.
 +
При попадании в корзину папке присваивается флаг '''old_path''' с полным путём, откуда она была удалёна.
 +
 
 +
===Просмотр директорий===
  
 
Получение списка файлов, каталогов, шар
 
Получение списка файлов, каталогов, шар
  
<cmd: list_dir
+
<cmd: '''list_dir'''
 
+
 
<dir_id:                // id каталога, при пустом значении выдаёт список файлов и папок корневого каталога
 
<dir_id:                // id каталога, при пустом значении выдаёт список файлов и папок корневого каталога
 
 
<token:
 
<token:
  
Строка 451: Строка 431:
 
"owner" : "test123",
 
"owner" : "test123",
 
"shared" : 1,
 
"shared" : 1,
                                "versioned": 1,                // если каталог для версионных файлов, то 1
+
"versioned": 1,                // если каталог для версионных файлов, то 1
                  "c_type" : "httpd/unix-directory"
+
"c_type" : "httpd/unix-directory"
 
},
 
},
 
{
 
{
 +
"owner":"test123",
 +
"ctime":1343139621,
 +
"special_dir":"shared", // Для спец. дирректорий поле принимает значение trash|shared
 +
"creator":"test456",
 +
"mtime":1343394246,
 +
"name":"Shared",
 +
"shared":0,
 +
"versioned":0,
 +
"props":{},
 +
"id":"4561000001",
 +
"c_type":"httpd/unix-directory"
 +
            },
 +
{
 +
"owner":"test123",
 +
"creator":"test456",
 
"ctime" : 1337003026,
 
"ctime" : 1337003026,
 
"mtime" : 1337003026,
 
"mtime" : 1337003026,
 
"name" : "new_dir4",
 
"name" : "new_dir4",
 
"id" : "17106000001",
 
"id" : "17106000001",
                                "versioned": 0,
+
"versioned": 0,
"c_type" : "httpd/unix-directory"
+
"c_type" : "httpd/unix-directory",
 +
"is_trash" : 1, // Если объект находится в папке Trash, в остальных случаях флаг отсутствует
 +
"is_shared" : 1, // см. логику флагов
 +
"shared_parents" : ["56531000001","40562000001"], // см. логику флагов
 +
"perms" : "read", // см. логику флагов
 +
"versioned_parent" : "17330000001", // см. логику флагов
 +
"old_path" : "/new_dir2/new_dir4/" // При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
 
}
 
}
 
],
 
],
 
"root" : {
 
"root" : {
"tree" : "/new_dir2/", // дерево где находимся в данный момент
+
"tree" : "/new_dir2/", // дерево где находимся в данный момент
 
"name" : "new_dir2",
 
"name" : "new_dir2",
"id" : "17068000001", // id просматриваемого каталога, если входной id не задан, то id корня
+
"id" : "17068000001", // id просматриваемого каталога, если входной id не задан, то id корня
"parent_id" : "17058000001"
+
"parent_id" : "17058000001",
 +
"versioned" : 0, // если данный каталог, либо каталог уровнем ниже версионный. Если 1 то все файлы и папки в этом каталоге по умолчанию версионные.
 +
"is_trash" : 1, // Если объект находится в папке Trash, в остальных случаях флаг отсутствует
 +
"is_shared" : 1, // см. логику флагов
 +
"shared_parents" : ["40562000001"], // см. логику флагов
 +
"perms" : "read", // см. логику флагов
 +
"versioned_parent" : "17330000001" // см. логику флагов
 
},
 
},
 
"list_files" : [
 
"list_files" : [
Строка 479: Строка 486:
 
"chksum" : "f436859c01b419731a6c7bc9c81c795f",
 
"chksum" : "f436859c01b419731a6c7bc9c81c795f",
 
"c_type" : "plain/text",
 
"c_type" : "plain/text",
                                "version_count" => 1,     // Количество версий файла
+
"versioned" : 1, // версионный файл
                                "shared" : 1,
+
"version_count" : 2, // Количество версий файла
                                'public_link' => 'http://devel.2safe.com:8082/17089000001/null_bytes_file.txt',
+
"shared" : 1,
"size" : 0
+
"public_link" : "http://cdn.2safe.com/17089000001/null_bytes_file.txt",
 +
"public_expires": 1348697574, // Срок истечения публичности
 +
"size" : 0,
 +
"total_size" : 30 // Итоговый размер всех версий
 
},
 
},
 
{
 
{
 +
"owner":"test123",
 +
"creator":"test456",
 
"ctime" : 1337004875,
 
"ctime" : 1337004875,
 
"current_version" : "17330000001",
 
"current_version" : "17330000001",
Строка 491: Строка 503:
 
"id" : "17329000001",
 
"id" : "17329000001",
 
"c_type" : "image/jpeg",
 
"c_type" : "image/jpeg",
                                'version_count' => 2,     // Количество версий файла
+
"versioned" : 0,
"size" : 150197
+
"version_count" : 2, // Количество версий файла
 +
"size" : 150197,
 +
"total_size": 150197,
 +
"is_trash" : 1, // Если объект находится в папке Trash, в остальных случаях флаг отсутствует
 +
"is_shared" : 1, // см. логику флагов
 +
"shared_parents" : ["56531000001","40562000001"], // см. логику флагов
 +
"perms" : "read", // см. логику флагов
 +
"versioned_parent" : "17330000001", // см. логику флагов
 +
"old_path" : "/new_dir2/Brazil - Lagoa.jpg" // При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
 
}
 
}
 
]
 
]
Строка 499: Строка 519:
 
</pre>
 
</pre>
  
h2. Очистка корзины
+
===Логика флагов===
  
<cmd: purge_trash
+
Для функций '''get_props''' и '''list_dir''':
  
<token:
+
+У владельца:+
  
<container        // необязательный параметр
+
'''shared''' = 1 - только у того объекта, для которого была выполнена команда '''share_object''', соответственно для этого объекта можно выполнить команду '''list_shares'''
 +
'''shared_parents''' = массив id_родителей - у тех объектов, которые являются потомками, где первый элемент массива означает текущую ближайшую шару, а остальные в порядке удаления от потомка, т.е. данный флаг имеют падпапки расшаренного объекта, у данных объектов shared = 0
 +
'''versioned_parent''' = id_родителя - у тех объектов, которые являются потомками, т.е. падпапки версионной папки, у них так-же versioned = 1
  
<pre>
+
+У того, кому расшарили (в папке Shared):+
{
+
 
"response" : {
+
'''shared''' = 0 - у всех объектов, перерасшаривание и публикация так же запрещена/
"success" : "true" // true в случае успеха
+
'''perms''' = read|write - права на объекты (файлы и папки)
}
+
'''is_shared''' = 1 - у всех объектов в папке Shared.
}
+
</pre>
+
  
h2. Получение свойств объекта
+
===Получение свойств объекта===
  
 
а так же получение id объекта, если на входе url или получение url, если на входе id
 
а так же получение id объекта, если на входе url или получение url, если на входе id
  
<cmd: get_props
+
<cmd: '''get_props'''
 
+
 
<url:       // путь к файлу или каталогу ИЛИ
 
<url:       // путь к файлу или каталогу ИЛИ
 
 
<id:                // id объекта
 
<id:                // id объекта
 
 
<token:
 
<token:
 
+
Опциональный параметр:
 
<container    // имя контейнера (по умолчанию default), если используем url
 
<container    // имя контейнера (по умолчанию default), если используем url
  
 +
Для файлов:
 +
<pre>
 +
{
 +
    "response":{
 +
        "success":"true",
 +
        "object":{
 +
"dir_id":"16137033537",
 +
"creator":"user_test",
 +
"tree":"/Shared/sql_sync.files",
 +
"size":1510178, // Размер
 +
"shared":1,
 +
"current_version":"16125033025",
 +
"version_count":3, // Количество версий файла
 +
"chksum":"cc16eb82a3314053d94cb390df9cb149",
 +
"id":"16140033537",
 +
"owner":"user_test",
 +
"ctime":1343203344,
 +
"mtime":1343215109,
 +
"name":"sql_sync.files",
 +
"total_size":4530534, // Итоговый размер (сумма размеров всех версий)
 +
"versioned":0,
 +
"props":{
 +
"flags":"136",
 +
"mode":"33204"
 +
},
 +
"c_type":"application/octet-stream",
 +
"public_link" : "http://cdn.2safe.com/16140033537/sql_sync.files",
 +
"public_expires": 1348697574, // Срок истечения публичности
 +
"is_trash" : 1, // Если объект находится в папке Trash, в остальных случаях флаг отсутствует
 +
"is_shared" : 1, // см. логику флагов
 +
"shared_parents" : ["56531000001","40562000001"], // см. логику флагов
 +
"perms" : "read", // см. логику флагов
 +
"versioned_parent" : "17330000001", // см. логику флагов
 +
"old_path" : "/Shared/sql_sync.files" // При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
Для папок:
 
<pre>
 
<pre>
 
{
 
{
Строка 536: Строка 593:
 
"owner" : "test123",
 
"owner" : "test123",
 
"ctime" : 1337004875,
 
"ctime" : 1337004875,
"tree" : "/new_dir2/Brazil - Lagoa.jpg",
+
"tree" : "/new_dir2/",
"dir_id" : "17068000001",
+
"creator" : "test456",
"creator" : "test123",
+
 
"mtime" : 1337004875,
 
"mtime" : 1337004875,
"name" : "Brazil - Lagoa.jpg",
+
"name" : "new_dir2",
"size" : 150197,
+
 
"parent_id" : "17068000001",
 
"parent_id" : "17068000001",
 
"props" : {
 
"props" : {
Строка 547: Строка 602:
 
"key3" : "value3"
 
"key3" : "value3"
 
},
 
},
"current_version" : "17330000001",
 
"chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4",
 
 
"id" : "17329000001",
 
"id" : "17329000001",
"c_type" : "image/jpeg",
+
"c_type" : "httpd/unix-directory",
                        "shared" : 1,
+
"shared" : 1,
                        "versioned": 1,               // свойство каталога (если каталог для версионных файлов, то 1)
+
"versioned": 1,
                        "version_count" => 1,     // Количество версий файла
+
"special_dir" : "", // Для спец. дирректорий поле принимает значение trash|shared в остальных случаях отсутствует             
                        "public_link" => 'http://devel.2safe.com:8082/17329000001/Brazil - Lagoa.jpg',
+
"is_trash" : 1, // Если объект находится в папке Trash, в остальных случаях флаг отсутствует
                        "perms" : "read",
+
"is_shared" : 1, // см. логику флагов
 +
"shared_parents" : ["56531000001","40562000001"], // см. логику флагов
 +
"perms" : "read", // см. логику флагов
 +
"versioned_parent" : "17330000001", // см. логику флагов
 +
"old_path" : "/new_dir2/" // При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
 
}
 
}
 
}
 
}
Строка 561: Строка 618:
 
</pre>
 
</pre>
  
h2. Установка свойств объекта
+
===Установка свойств объекта===
 
+
<cmd: set_props
+
  
 +
<cmd: '''set_props'''
 
<id:                // id объекта  
 
<id:                // id объекта  
 
 
<token:
 
<token:
 
 
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 
<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
  
Строка 579: Строка 633:
 
</pre>
 
</pre>
  
h2. Получение родительского дерева каталогов
+
===Получение родительского дерева каталогов===
 
+
<cmd: get_tree
+
  
 +
<cmd: '''get_tree_parent'''
 
<token:
 
<token:
 
 
<dir_id
 
<dir_id
  
Строка 610: Строка 662:
 
</pre>
 
</pre>
  
h2. Блокировка объекта
+
===Очистка корзины===
  
<cmd: lock_object
+
<cmd: '''purge_trash'''
 +
<token:
 +
Опциональный параметр:
 +
<container        // необязательный параметр
  
 +
<pre>
 +
{
 +
"response" : {
 +
"success" : "true" // true в случае успеха
 +
}
 +
}
 +
</pre>
 +
 +
===Просмотр действий пользователя===
 +
 +
<cmd:  '''get_events'''
 
<token:
 
<token:
 +
Опциональные параметры:
 +
<after: // timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся первые 300 событий)
 +
<last: // вывести только последнее событие
  
<id: // id объекта
+
<pre>
 +
{
 +
"response" : {
 +
"success" : "true",
 +
"events" : [
 +
                      {
 +
                        "timestamp" : 1340713368454494,
 +
                        "name" : "new_dir",
 +
                        "id" : "12749000001",
 +
                        "event" : "dir_created",
 +
                        "parent_id" : "12741000001"
 +
                      },
 +
                      {
 +
                        "timestamp" : 1340713368576917,
 +
                        "name" : "new_dir2",
 +
                        "id" : "12751000001",
 +
                        "event" : "dir_created",
 +
                        "parent_id" : "12741000001"
 +
                      },
 +
                      {
 +
                        "event" : "file_moved",
 +
                        "timestamp" : 1340715512685817,
 +
                        "old_parent_id" : "14307000001",
 +
                        "new_id" : "14308000001",
 +
                        "new_parent_id" : "14228000001",
 +
                        "old_id" : "14308000001",
 +
                        "old_name" : "file_30_bytes",
 +
                        "new_name" : "file_30_bytes"
 +
                      }
 +
]
 +
}
 +
}
 +
</pre>
  
<exclusive: // св-ва блокировки
+
Функция '''get_events''' без опциональных параметров выводит первые 300 событий, для получения следующий событий, необходимо передавать параметр '''after''', в котором указывать '''timestamp''' последнего элемента массива из предудущего запроса.
  
<inheritable:
+
== Функции по работе с блокировками ==
  
<timeout:
+
===Блокировка объекта===
  
 +
<cmd: '''lock_object'''
 +
<token:
 +
<id: // id объекта
 +
Опциональные параметры:
 +
<exclusive: // св-ва блокировки
 +
<timeout:
 
<userdata: // пользовательские данные
 
<userdata: // пользовательские данные
  
Строка 635: Строка 742:
 
</pre>
 
</pre>
  
h2. Разблокировка объекта
+
===Разблокировка объекта===
 
+
<cmd: unlock_object
+
  
 +
<cmd: '''unlock_object'''
 
<token:
 
<token:
 
 
<lock_token:
 
<lock_token:
  
Строка 651: Строка 756:
 
</pre>
 
</pre>
  
h2. Получение списка всех блокировок
+
===Получение списка всех блокировок===
 
+
<cmd: list_object_locks
+
  
 +
<cmd: '''list_object_locks'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
  
Строка 667: Строка 770:
 
"userdata" : "",
 
"userdata" : "",
 
"token" : "6c27f95fa4b946e7a6015d742b0998d2", // lock_token
 
"token" : "6c27f95fa4b946e7a6015d742b0998d2", // lock_token
"expires" : "2147483647",
+
"expires" : 2147483647,
"exclusive" : "0",
+
"exclusive" : 0
"inheritable" : "0"
+
 
}
 
}
 
]
 
]
Строка 676: Строка 778:
 
</pre>
 
</pre>
  
h2. Обновление таймаута блокировки
+
===Обновление таймаута блокировки===
 
+
<cmd: refresh_lock_timeout
+
  
 +
<cmd: '''refresh_lock_timeout'''
 
<token:
 
<token:
 
 
<lock_token:
 
<lock_token:
 
 
<timeout:
 
<timeout:
  
Строка 691: Строка 790:
 
"success" : "true",
 
"success" : "true",
 
"userdata" : "",
 
"userdata" : "",
"exclusive" : "0",
+
"exclusive" : 0
"inheritable" : "0"
+
 
}
 
}
 
}
 
}
 
</pre>
 
</pre>
  
h2. Расшаривание объекта
+
== Функции расшаривания и публикации объектов ==
  
<cmd: share_object
+
===Расшаривание объекта===
  
 +
<cmd: '''share_object'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
 
 
<login: // логин друга, для кого расшариваем
 
<login: // логин друга, для кого расшариваем
 
+
Опциональные параметры:
 
<write:    // для расшаривания на запись параметр = 1
 
<write:    // для расшаривания на запись параметр = 1
 
 
<expires:  // срок расшаривания в формате timestamp
 
<expires:  // срок расшаривания в формате timestamp
  
Строка 719: Строка 815:
 
</pre>
 
</pre>
  
h2. Отменить расшаривание объекта
+
Права на '''write''' означают возможность производить любые операции над объектом, кроме ф-ий расшаривания и версионности.
 +
Перерасшаривание и установка/снятие версионности при флаге '''write''' ЗАПРЕЩЕНА!
  
<cmd: unshare_object
+
===Отменить расшаривание объекта===
  
 +
<cmd: '''unshare_object'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
 
 
<login: // логин друга, для кого было расшарен объект
 
<login: // логин друга, для кого было расшарен объект
  
Строка 737: Строка 833:
 
</pre>
 
</pre>
  
h2. Отменить все шары объекта
+
Команда '''unshare_object''' применима только к тем объетам, к которым применялась команда '''share_object'''
  
<cmd: unshare_all
+
===Отменить все шары объекта===
  
 +
<cmd: '''unshare_all'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
  
Строка 753: Строка 849:
 
</pre>
 
</pre>
  
h2. Список шар объекта
+
Команда '''unshare_all''' применима только к тем объетам, к которым применялась команда '''share_object'''
  
<cmd: list_shares
+
===Список шар объекта===
  
 +
<cmd: '''list_shares'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
  
Строка 767: Строка 863:
 
{
 
{
 
"login" : "test-a7f",
 
"login" : "test-a7f",
                                "write" : 1,
+
"write" : 1,
                                "expires" : 1340797745,    // либо 0, если нет ограничений по сроку
+
"inherited_from" : "12741000001", // id родительской шары, либо отсутствует, если шара не наследуемая
 +
"expires" : 1340797745,    // либо 0, если нет ограничений по сроку
 
}
 
}
 
],
 
],
Строка 776: Строка 873:
 
</pre>
 
</pre>
  
h2. Публичность объекта
+
Флаг '''inherited_from''' указывает id родительской шары, если помимо шары для данного объекта, существуют вложенные шары верхнего уровня и их действие так же распространяется на этот объект. Например:
 +
/dir1-shared_for_login1_rw/dir2-shared_for_login2-r/
 +
При выполнении команды list_shares для dir2 ответ:
 +
{login=login2,write=0},{login=login1,write=1,inherited_from=12741000001}
 +
При выполнении команды list_shares для dir1 ответ:
 +
{login=login1,write=1}
  
<cmd: public_object
+
Команда '''list_shares''' применима только к тем объетам, к которым применялась команда '''share_object'''
  
 +
===Публичность объекта===
 +
 +
<cmd: '''public_object'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
 
+
Опциональный параметр:
 
<expires:  // срок публичности в формате timestamp
 
<expires:  // срок публичности в формате timestamp
  
Строка 795: Строка 899:
 
</pre>
 
</pre>
  
h2. Отменить публичность объекта
+
Команда '''public_object''' применима только к файлам.
  
<cmd: unpublic_object
+
===Отменить публичность объекта===
  
 +
<cmd: '''unpublic_object'''
 
<token:
 
<token:
 
 
<id: // id объекта
 
<id: // id объекта
  
Строка 811: Строка 915:
 
</pre>
 
</pre>
  
h2. Просмотр действий пользователя
+
Команда '''unpublic_object''' применима только к файлам, для которых была выполнена команда '''public_object'''
  
<cmd:  get_events
+
== Функции по работе с версионностью ==
  
 +
===Получение списка версий файла===
 +
 +
<cmd: '''list_versions'''
 
<token:
 
<token:
 
+
<id: // id файла
<after: // timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся все события)
+
 
+
<last: // вывести только последнее событие
+
  
 
<pre>
 
<pre>
 
{
 
{
"response" : {
+
    "response":{
"success" : "true",
+
        "versions":[
"events" : [
+
            {
                      {
+
                "owner":"user_test",
                        "timestamp" : 1340713368454494,
+
                "ctime":1343203344,
                        "name" : "new_dir",
+
                "creator":"user_test",
                        "id" : "12749000001",
+
                "mtime":1343204013,
                        "event" : "dir_created",
+
                "name":"sql_sync.files",
                        "parent_id" : "12741000001"
+
                "size":1510178,
                      },
+
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                      {
+
                "id":"16008033025",
                        "timestamp" : 1340713368576917,
+
                "c_type":"application/octet-stream"
                        "name" : "new_dir2",
+
},
                        "id" : "12751000001",
+
{
                        "event" : "dir_created",
+
                "owner":"user_test",
                        "parent_id" : "12741000001"
+
                "ctime":1343203344,
                      },
+
                "creator":"user_test",
                      {
+
                "mtime":1343203344,
                        "event" : "file_moved",
+
                "name":"sql_sync.files",
                        "timestamp" : 1340715512685817,
+
                "size":1510178,
                        "old_parent_id" : "14307000001",
+
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                        "new_id" : "14308000001",
+
                "id":"16141033537",
                        "new_parent_id" : "14228000001",
+
                "c_type":"application/octet-stream"
                        "old_id" : "14308000001",
+
            }
                        "old_name" : "file_30_bytes",
+
        ],
                        "new_name" : "file_30_bytes"
+
        "success":"true",
                      }
+
"current":"16141033537", // Текущая версия
]
+
"file_id":"79397000001" // id файла
}
+
    }
 
}
 
}
 
</pre>
 
</pre>
  
h2. Получение списка версий файла
+
===Получение текущей версии файла===
 
+
<cmd: list_versions
+
  
 +
<cmd: '''get_current_version'''
 
<token:
 
<token:
 
 
<id: // id файла
 
<id: // id файла
  
Строка 867: Строка 969:
 
"response" : {
 
"response" : {
 
               "success" : "true",
 
               "success" : "true",
               "versions" : [
+
               "current_version" : "18518000001"
                          {
+
                            "ctime" : 1340797746,
+
                            "owner" : "test123",
+
                            "mtime" : 1340797754,
+
                            "name" : "file_name",
+
                            "size" : 0,
+
                            "chksum" : "d41d8cd98f00b204e9800998ecf8427e",
+
                            "id" : "18408000001",
+
                            "c_type" : "plain/text"
+
                          },
+
                          {
+
                            "ctime" : 1340797745,
+
                            "owner" : "test123",
+
                            "mtime" : 1340797750,
+
                            "name" : "file_name",
+
                            "size" : 60,
+
                            "chksum" : "f436859c01b419731a6c7bc9c81c795f",
+
                            "id" : "18395000001",
+
                            "c_type" : "plain/text"
+
                          }
+
                  ]
+
 
         }
 
         }
 
}
 
}
 
</pre>
 
</pre>
  
h2. Получение текущей версии файла
+
===Установка текущей версии файла===
 
+
<cmd: get_current_version
+
  
 +
<cmd: '''set_current_version'''
 
<token:
 
<token:
 
 
<id: // id файла
 
<id: // id файла
 +
<v_id:      // id версии
  
 
<pre>
 
<pre>
 
{
 
{
 
"response" : {
 
"response" : {
              "success" : "true",
+
"success" : "true"
              "current_version" : "18518000001"
+
}
        }
+
 
}
 
}
 
</pre>
 
</pre>
  
h2. Установка текущей версии файла
+
===Удаление версии файла===
 
+
<cmd: set_current_version
+
  
 +
<cmd: '''remove_version'''
 
<token:
 
<token:
 +
<id: // id версии
  
<id: // id файла
+
<pre>
 +
{
 +
"response" : {
 +
"success" : "true"
 +
}
 +
}
 +
</pre>
  
<v_id:     // id версии
+
===Установка флага версионности для объекта===
 +
 
 +
Если флагом помечается каталог, то все файлы в этом и во вложенных каталогах будут версионными
 +
 
 +
<cmd: '''set_versioned'''
 +
<token:
 +
<id: // id файла или каталога
  
 
<pre>
 
<pre>
Строка 928: Строка 1019:
 
</pre>
 
</pre>
  
h2. Удаление версии файла
+
===Снятие флага версионности для объекта===
  
<cmd: remove_version
+
Если флаг снимается с каталога, то все файлы в этом и во вложенных каталогах больше не будут версионными, за исключением случая, если на вложенный файл не проставлялся этот флаг
  
 +
<cmd: '''unset_versioned'''
 
<token:
 
<token:
 
+
<id: // id файла или каталога
<id: // id версии
+
  
 
<pre>
 
<pre>
Строка 943: Строка 1034:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
Команда '''unset_versioned''' применима только к тем объектам, для которых была выполнена команда '''set_versioned'''

Версия 17:26, 1 октября 2012

Содержание

Модель вызова функций в API (JSON)

Передаём параметры любым способом (POST, GET) https://api.2safe.com/?cmd=команда https://apiqa.2safe.com/?cmd=команда QA сервер

Ответ от API сервера в формате JSON. При возникновении ошибки выдаётся сообщение с кодом ошибки:

{
	"error_code": "006",				// код ошибки, в случае ошибки
	"error_msg": "Command not found"	// сообщение, в случае ошибки
}

Код ошибки и сообщение с ошибкой возвращается во всех командах, ТОЛЬКО при возникновении ошибки.

Пользовательские функции

Проверка доступности e-mail

<cmd: chk_mail <email:

{
	"response" : {
		"success" : "true",			// true в случае успеха
		"available": "true"			// true - доступен, false - занят
		}
}

Проверка доступности логина

<cmd: chk_login <login:

{
	"response" : {
		"success" : "true",			// true в случае успеха
		"available": "true"			// true - доступен, false - занят
		}
}

Получение капчи

<cmd: get_captcha

Ответ будет получен как при обычном GET запросе (изображение image/png) с заголовком "Set-Cookie: captcha2safe=1000", где 1000 - id капчи. Код действителен в течении 10 минут.

Регистрация пользователя

<cmd: add_login <login: <password: <email: <captcha: // защитный код, полученный предварительным запросом get_captcha, если код не верен, то необходимо заново получить капчу. <id: // id капчи, который находится в заголовке ответа на запрос get_captcha или в cookie c именем captcha2safe

{
	"response" : {
		"success" : "true",			// true в случае успеха
		"root" : "17050000001",		// id корневой папки
		"id" : "1033000001"			// id пользователя
	}
}

Авторизация пользователя

<cmd: auth // команда <login: <password: Опциональные параметры: <format: // по умолчанию JSON - параметр может использоваться во всех запросах к API <captcha_id: // После трёх и более неправильных попыток авторизации необходимо получить новую капчу get_captcha <captcha: // и передать эти два параметра

{
	"response" : {
		"success" : "true",
		"id" : "1033000001",							// id пользователя
		"token" : "e726e3df64a55ceff84754e3157053cc"	// token для дальнейших действий
	}
}

Срок действия token - 24 часа. После каждого обращения к API - срок действия токена обновляется и становится равным 24 часам. По истечении token'а необходимо заново авторизоваться.

Удаление пользователя

<cmd: remove_login <login: <password:

{
	"response" : {
		"success" : "true",
		"user" : {
			"id" : "1034000001",
			"login" : "test22"
			}
	}
}

Удаление сессии (logout)

<cmd: logout <token:

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Просмотр квоты

<cmd: get_disk_quota <token:

{
	"response" : {
		"quotas" : {
			"used_bytes" : 121404289,	// использовано
			"total_bytes" : 2048000000	// всего
			},
		"success" : "true"
	}
}

Получение карточки юзера

<cmd: get_personal_data <token:

{
	"response" : {
		"success" : "true",
		"props" : {
			"key2" : "val2",
			"key1" : "value1",
			"keyN" : "valueN"
			},
		"personal" : {
			"email" : "test-17786c8b1@mail.ru",
			"lang" : "en",
			"last_name" : "Testovich",
			"first_name" : "Test",
			"avatar" : "21212000001"
			}
	}
}

Изменение карточки юзера

<cmd: set_personal_data <token: <personal: // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"} Опциональный параметр: <props: // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <password // обязательное поле только при смене email

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

При изменении email необходимо передавать текущий пароль в параметр password.

Смена пароля

<cmd: change_password <login: <password: <new_password:

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

Активация промо кода

<cmd: activate_promo_code <token: <\code:

{
	"response" : {
		"quotas" : {
			"used_bytes" : 121404289,	// использовано
			"total_bytes" : 5368709120,	// всего
			"difference": 2048000000	// сколько добавлено за счёт активации кода
			},
		"success" : "true"
	}
}

После трёх неудачных попыток введения промо кода - таймаут 5 минут.

== Функции по работе с файловой системой --

Получение файла

<cmd: get_file <id: // id файла <token: Опциональные параметры: <size: <offset:

Ответ будет получен как при обычном GET запросе, без учёта формата запроса (JSON,XML и т.д.)

Заливка файла

Загрузка файлов производится методом POST (multipart/form-data)

<cmd: put_file <dir_id: // id папки назначения <file: // файл <token: Опциональные параметры: <overwrite // автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка <versioned: // если файл существует, то создаётся новая версия файла, независимо от флага overwrite <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <ctime // дата создания (в формате timestamp) <mtime // дата модификации (в формате timestamp) <name // имя для файла в системе

{
	"response" : {
		"success" : "true",
		"file" : {
			"mtime" : 1337004875,
			"chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4",
			"name" : "Brazil - Lagoa.jpg",
			"version_id" : "17330000001",
			"type" : "image/jpeg",
			"id" : "17329000001",
			"size" : 150197
			}
	}
}

Копирование файлов

<cmd: copy_file <id: // id файла <dir_id: // id папки куда, копируется файл <token: Опциональные параметры: <overwrite: // если файл существует, то он перезаписывается <versioned: // если файл существует, то создаётся новая версия файла <file_name: // новое имя файла (для копирования с переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Перемещение файлов

<cmd: move_file <id: // id файла <dir_id: // id папки куда, перемещаем файл <token: Опциональные параметры: <overwrite: // если файл существует, то он перезаписывается <versioned: // если файл существует, то создаётся новая версия файла <file_name: // новое имя файла (для перемещения с переименовыванием либо переименовыванием)

{
	"response" : {
		"success" : "true",		// true в случае успеха
		"id" : "17329000001"		// новый id файла
		}
}

id файла изменяется только при перемещении, кроме перемещения в корзину. Переименовывание файла происходит так же со сменой id.

Удаление файлов

<cmd: remove_file <id: // id файла <token: Опциональный параметр: <remove_now // удаление минуя корзину (Аналог Shift+Del)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

При первом удалении файл удаляется в корзину (папка Trash), при повторном выполнении ф-ии - файл удаляется навсегда. При попадании в корзину файлу присваивается флаг old_path с полным путём, откуда он был удалён.

Создание директорий

<cmd: make_dir <dir_id: // id корневой паки <dir_name: // имя папки <token: Опциональные параметры: <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <ctime // дата создания (в формате timestamp) <mtime // дата модификации (в формате timestamp)

{
	"response" : {
		"success" : "true",                    // true в случае успеха
		"dir_id" : "17750000001"           // id новой директории
	}
}

Копирование директорий

<cmd: copy_dir <id: // id src каталога <dir_id: // id корневого dst каталога <token: Опциональные параметры: <overwrite: // автоматически перезаписывать файлы и папки <versioned: // если файл существует, то создаётся новая версия файла <dir_name: // новое имя папки (для копирования с переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Перемещение директорий

<cmd: move_dir <id: // id src каталога <dir_id: // id корневого dst каталога <token: Опциональные параметры: <overwrite: // автоматически перезаписывать файлы <versioned: // если файл существует, то создаётся новая версия файла <dir_name: // новое имя папки (для перемещения с переименовыванием либо переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Удаление директорий

<cmd: remove_dir <dir_id: // id каталога <token: Опциональные параметры: <recursive // рекурсивное удаление <remove_now // удаление минуя корзину (Аналог Shift+Del)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

При первом удалении папка удаляется в корзину (в папку Trash), при повторном выполнении ф-ии - папка удаляется навсегда. При попадании в корзину папке присваивается флаг old_path с полным путём, откуда она была удалёна.

Просмотр директорий

Получение списка файлов, каталогов, шар

<cmd: list_dir <dir_id: // id каталога, при пустом значении выдаёт список файлов и папок корневого каталога <token:

{
	"response" : {
		"success" : "true",
		"list_dirs" : [
				{
				"ctime" : 1337003006,
				"props" : {
					"key4" : "value4",
					"key3" : "value3"
					},
				"mtime" : 1337003006,
				"name" : "sub_new_dir",
				"id" : "17071000001",
				"owner" : "test123",
				"shared" : 1,
				"versioned": 1,                // если каталог для версионных файлов, то 1
				"c_type" : "httpd/unix-directory"
				},
				{
				"owner":"test123",
				"ctime":1343139621,
				"special_dir":"shared",		// Для спец. дирректорий поле принимает значение trash|shared
				"creator":"test456",
				"mtime":1343394246,
				"name":"Shared",
				"shared":0,
				"versioned":0,
				"props":{},
				"id":"4561000001",
				"c_type":"httpd/unix-directory"
            			},
				{
				"owner":"test123",
				"creator":"test456",			
				"ctime" : 1337003026,
				"mtime" : 1337003026,
				"name" : "new_dir4",
				"id" : "17106000001",
				"versioned": 0,
				"c_type" : "httpd/unix-directory",
				"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
				"is_shared" : 1,					// см. логику флагов
				"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
				"perms" : "read",					// см. логику флагов 
				"versioned_parent" : "17330000001",	// см. логику флагов
				"old_path" : "/new_dir2/new_dir4/"	// При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
				}
			],
		"root" : {
			"tree" : "/new_dir2/",			// дерево где находимся в данный момент
			"name" : "new_dir2",
			"id" : "17068000001",			// id просматриваемого каталога, если входной id не задан, то id корня
			"parent_id" : "17058000001",
			"versioned" : 0,					// если данный каталог, либо каталог уровнем ниже версионный. Если 1 то все файлы и папки в этом каталоге по умолчанию версионные.
			"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
			"is_shared" : 1,					// см. логику флагов
			"shared_parents" : ["40562000001"],	// см. логику флагов
			"perms" : "read",					// см. логику флагов 
			"versioned_parent" : "17330000001"	// см. логику флагов
			},
		"list_files" : [
				{
				"ctime" : 1337003021,
				"current_version" : "17090000001",
				"mtime" : 1337003021,
				"name" : "null_bytes_file.txt",
				"id" : "17089000001",
				"owner" : "test123",
				"chksum" : "f436859c01b419731a6c7bc9c81c795f",
				"c_type" : "plain/text",
				"versioned" : 1,	// версионный файл
				"version_count" : 2,	// Количество версий файла
				"shared" : 1,
				"public_link" : "http://cdn.2safe.com/17089000001/null_bytes_file.txt",
				"public_expires": 1348697574,	// Срок истечения публичности
				"size" : 0,
				"total_size" : 30	// Итоговый размер всех версий
				},
				{
				"owner":"test123",
				"creator":"test456",
				"ctime" : 1337004875,
				"current_version" : "17330000001",
				"mtime" : 1337004875,
				"name" : "Brazil - Lagoa.jpg",
				"id" : "17329000001",
				"c_type" : "image/jpeg",
				"versioned" : 0,
				"version_count" : 2,			// Количество версий файла
				"size" : 150197,
				"total_size": 150197,
				"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
				"is_shared" : 1,					// см. логику флагов
				"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
				"perms" : "read",					// см. логику флагов 
				"versioned_parent" : "17330000001",	// см. логику флагов
				"old_path" : "/new_dir2/Brazil - Lagoa.jpg"	// При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
				}
			]
	}
}

Логика флагов

Для функций get_props и list_dir:

+У владельца:+

shared = 1 - только у того объекта, для которого была выполнена команда share_object, соответственно для этого объекта можно выполнить команду list_shares shared_parents = массив id_родителей - у тех объектов, которые являются потомками, где первый элемент массива означает текущую ближайшую шару, а остальные в порядке удаления от потомка, т.е. данный флаг имеют падпапки расшаренного объекта, у данных объектов shared = 0 versioned_parent = id_родителя - у тех объектов, которые являются потомками, т.е. падпапки версионной папки, у них так-же versioned = 1

+У того, кому расшарили (в папке Shared):+

shared = 0 - у всех объектов, перерасшаривание и публикация так же запрещена/ perms = read|write - права на объекты (файлы и папки) is_shared = 1 - у всех объектов в папке Shared.

Получение свойств объекта

а так же получение id объекта, если на входе url или получение url, если на входе id

<cmd: get_props <url: // путь к файлу или каталогу ИЛИ <id: // id объекта <token: Опциональный параметр: <container // имя контейнера (по умолчанию default), если используем url

Для файлов:

{
    "response":{
        "success":"true",
        "object":{
		"dir_id":"16137033537",
		"creator":"user_test",
		"tree":"/Shared/sql_sync.files",
		"size":1510178,		// Размер
		"shared":1,
		"current_version":"16125033025",
		"version_count":3,		// Количество версий файла
		"chksum":"cc16eb82a3314053d94cb390df9cb149",
		"id":"16140033537",
		"owner":"user_test",
		"ctime":1343203344,
		"mtime":1343215109,
		"name":"sql_sync.files",
		"total_size":4530534,	// Итоговый размер (сумма размеров всех версий)
		"versioned":0,
		"props":{
			"flags":"136",
			"mode":"33204"
		},
		"c_type":"application/octet-stream",
		"public_link" : "http://cdn.2safe.com/16140033537/sql_sync.files",
		"public_expires": 1348697574,			// Срок истечения публичности
		"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
		"is_shared" : 1,					// см. логику флагов
		"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
		"perms" : "read",					// см. логику флагов 
		"versioned_parent" : "17330000001",	// см. логику флагов
		"old_path" : "/Shared/sql_sync.files"	// При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
        }
    }
}

Для папок:

{
	"response" : {
		"success" : "true",
		"object" : {
			"owner" : "test123",
			"ctime" : 1337004875,
			"tree" : "/new_dir2/",
			"creator" : "test456",
			"mtime" : 1337004875,
			"name" : "new_dir2",
			"parent_id" : "17068000001",
			"props" : {
				"key4" : "value4",
				"key3" : "value3"
				},
			"id" : "17329000001",
			"c_type" : "httpd/unix-directory",
			"shared" : 1,
			"versioned": 1,
			"special_dir" : "",			// Для спец. дирректорий поле принимает значение trash|shared в остальных случаях отсутствует               
			"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
			"is_shared" : 1,					// см. логику флагов
			"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
			"perms" : "read",					// см. логику флагов 
			"versioned_parent" : "17330000001",	// см. логику флагов
			"old_path" : "/new_dir2/"	// При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
			}
	}
}

Установка свойств объекта

<cmd: set_props <id: // id объекта <token: <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

Получение родительского дерева каталогов

<cmd: get_tree_parent <token: <dir_id

{
	"response" : {
		"success" : "true",
		"tree" : [
				{
				"owner" : "test123",
				"level" : "0",
				"name" : "Shared",
				"id" : "17053000001",
				"parent_id" : "17050000001"
				},
				{
				"owner" : "test123",
				"level" : "1",
				"name" : ".root",
				"id" : "17050000001"
				}
			]
	}
}

Очистка корзины

<cmd: purge_trash <token: Опциональный параметр: <container // необязательный параметр

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

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

<cmd: get_events <token: Опциональные параметры: <after: // timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся первые 300 событий) <last: // вывести только последнее событие

{
	"response" : {
		"success" : "true",
		"events" : [
                      {
                        "timestamp" : 1340713368454494,
                        "name" : "new_dir",
                        "id" : "12749000001",
                        "event" : "dir_created",
                        "parent_id" : "12741000001"
                      },
                      {
                        "timestamp" : 1340713368576917,
                        "name" : "new_dir2",
                        "id" : "12751000001",
                        "event" : "dir_created",
                        "parent_id" : "12741000001"
                      },
                      {
                        "event" : "file_moved",
                        "timestamp" : 1340715512685817,
                        "old_parent_id" : "14307000001",
                        "new_id" : "14308000001",
                        "new_parent_id" : "14228000001",
                        "old_id" : "14308000001",
                        "old_name" : "file_30_bytes",
                        "new_name" : "file_30_bytes"
                      }
		]
	}
}

Функция get_events без опциональных параметров выводит первые 300 событий, для получения следующий событий, необходимо передавать параметр after, в котором указывать timestamp последнего элемента массива из предудущего запроса.

Функции по работе с блокировками

Блокировка объекта

<cmd: lock_object <token: <id: // id объекта Опциональные параметры: <exclusive: // св-ва блокировки <timeout: <userdata: // пользовательские данные

{
	"response" : {
		"success" : "true",
		"lock_token" : "a9151295e505db40c3e147da16354f22"
	}
}

Разблокировка объекта

<cmd: unlock_object <token: <lock_token:

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Получение списка всех блокировок

<cmd: list_object_locks <token: <id: // id объекта

{
	"response" : {
		"success" : "true",
		"list_locks" : [
				{
				"userdata" : "",
				"token" : "6c27f95fa4b946e7a6015d742b0998d2",		// lock_token
				"expires" : 2147483647,
				"exclusive" : 0
				}
			]
	}
}

Обновление таймаута блокировки

<cmd: refresh_lock_timeout <token: <lock_token: <timeout:

{
	"response" : {
		"success" : "true",
		"userdata" : "",
		"exclusive" : 0
	}
}

Функции расшаривания и публикации объектов

Расшаривание объекта

<cmd: share_object <token: <id: // id объекта <login: // логин друга, для кого расшариваем Опциональные параметры: <write: // для расшаривания на запись параметр = 1 <expires: // срок расшаривания в формате timestamp

{
	"response" : {
		"success" : "true"
	}
}

Права на write означают возможность производить любые операции над объектом, кроме ф-ий расшаривания и версионности. Перерасшаривание и установка/снятие версионности при флаге write ЗАПРЕЩЕНА!

Отменить расшаривание объекта

<cmd: unshare_object <token: <id: // id объекта <login: // логин друга, для кого было расшарен объект

{
	"response" : {
		"success" : "true"
	}
}

Команда unshare_object применима только к тем объетам, к которым применялась команда share_object

Отменить все шары объекта

<cmd: unshare_all <token: <id: // id объекта

{
	"response" : {
		"success" : "true"
	}
}

Команда unshare_all применима только к тем объетам, к которым применялась команда share_object

Список шар объекта

<cmd: list_shares <token: <id: // id объекта

{
	"response" : {
		"shares" : [
				{
				"login" : "test-a7f",
				"write" : 1,
				"inherited_from" : "12741000001",		// id родительской шары, либо отсутствует, если шара не наследуемая
				"expires" : 1340797745,     // либо 0, если нет ограничений по сроку
				}
			],
		"success" : "true"
	}
}

Флаг inherited_from указывает id родительской шары, если помимо шары для данного объекта, существуют вложенные шары верхнего уровня и их действие так же распространяется на этот объект. Например: /dir1-shared_for_login1_rw/dir2-shared_for_login2-r/ При выполнении команды list_shares для dir2 ответ: {login=login2,write=0},{login=login1,write=1,inherited_from=12741000001} При выполнении команды list_shares для dir1 ответ: {login=login1,write=1}

Команда list_shares применима только к тем объетам, к которым применялась команда share_object

Публичность объекта

<cmd: public_object <token: <id: // id объекта Опциональный параметр: <expires: // срок публичности в формате timestamp

{
	"response" : {
		"link" : "http://cdn808.2safe.com/43190000001/litmus.jpg",
		"success" : "true"
	}
}

Команда public_object применима только к файлам.

Отменить публичность объекта

<cmd: unpublic_object <token: <id: // id объекта

{
	"response" : {
		"success" : "true"
	}
}

Команда unpublic_object применима только к файлам, для которых была выполнена команда public_object

Функции по работе с версионностью

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

<cmd: list_versions <token: <id: // id файла

{
    "response":{
        "versions":[
            {
                "owner":"user_test",
                "ctime":1343203344,
                "creator":"user_test",
                "mtime":1343204013,
                "name":"sql_sync.files",
                "size":1510178,
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                "id":"16008033025",
                "c_type":"application/octet-stream"
	},
	{
                "owner":"user_test",
                "ctime":1343203344,
                "creator":"user_test",
                "mtime":1343203344,
                "name":"sql_sync.files",
                "size":1510178,
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                "id":"16141033537",
                "c_type":"application/octet-stream"
            }
        ],
        "success":"true",
	"current":"16141033537",	// Текущая версия
	"file_id":"79397000001"		// id файла
    }
}

Получение текущей версии файла

<cmd: get_current_version <token: <id: // id файла

{
	"response" : {
               "success" : "true",
               "current_version" : "18518000001"
        }
}

Установка текущей версии файла

<cmd: set_current_version <token: <id: // id файла <v_id: // id версии

{
	"response" : {
		"success" : "true"
	}
}

Удаление версии файла

<cmd: remove_version <token: <id: // id версии

{
	"response" : {
		"success" : "true"
	}
}

Установка флага версионности для объекта

Если флагом помечается каталог, то все файлы в этом и во вложенных каталогах будут версионными

<cmd: set_versioned <token: <id: // id файла или каталога

{
	"response" : {
		"success" : "true"
	}
}

Снятие флага версионности для объекта

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

<cmd: unset_versioned <token: <id: // id файла или каталога

{
	"response" : {
		"success" : "true"
	}
}

Команда unset_versioned применима только к тем объектам, для которых была выполнена команда set_versioned