.. only:: html
.. _capi-xml-rpc:
Интерфейс к файловому хранилищу Cargador по протоколу XML-RPC
===============================================================
Вступление
--------------------
Cargador поддерживает API посредством XML-RPC поверх протокола
HTTP. Доступ протестирован на совместимость с XML-RPC клиентами языков
Python и PHP.
В системе Cerebro файлы идентифицируются по хэшам их содержимого.
Именно значения хэшей хранятся в базе данных. Cargador обеспечивает
доступ и работу с файлами по значению хэша.
Перед началом работы с файлом его необходимо импортировать в каталог
Cargador посредством вызова функций importFile(), ingestFile() или
прямой отправкой по HTTP-протоколу. Система вычисляет его хэш.
Дальнейшие операции с файлом происходят через этот хэш.
Физическое расположение файла можно узнать, вызвав catalogResolve().
Файл можно отправить в каталог удаленного Cargador путем вызова
catalogUpload(). Аналогично, отсутствующий файл можно скачать с
удаленного Cargador, вызвав catalogDownload(). Эти операции
асинхронные.
Для мониторинга текущих очередей скачки/закачки используется функция
statusTables() . Для управления очередями используется controlIO() .
Методы
-------------------
Ниже приведен список поддерживаемых методов с описаниями.
**statusInfo()**
Получить доступную для чтения пользователем информацию о статусе
сервиса Cargador
returns:info STR
**statusTables(tablesBitMask INT, flags INT)**
Получить таблицу с данными о текущих или прошедших файловых операциях.
*statusTableMask* : битовая маска с желаемыми к получению таблицами.
Смотрите описание TableKind ниже.
*flags* :модифицирующие результат флаги. Смотрите описание
StatusTableFlags ниже.
*TableKind*
::
{
pc_tkDomestricDown = 1, // загрузки, запрошенные внутренними пользователями
pc_tkDomestricUp = 2, // выгрузки, запрошенные внутренними
пользователями
pc_tkForeignArrive = 4, // прибывающие от внешних пользователей файлы
pc_tkForeignDepart = 8,// отправляемые внешним пользователям файлы
pc_tkArchiveDown = 0x10, // архивные записи о прошедших операциях
pc_tkArchiveUp = 0x20,
pc_tkArchiveArrive = 0x40,
pc_tkArchiveDepart = 0x80,
};
*StatusTableFlags*
::
{
tqIncludeTemporar = 1, // "Временные" закачки фактически относятся к
загрузке миниатюр. Получение данных о них может вернуть большое
количество случайно возникающих/исчезающих закачек.
};
*Status*
::
{
tsReady = 10, // готова к старту, ждет очереди
tsFirstCheck = 20, // сервисный статус, первичная проверка
tsInstantDown = 30, // сервисный статус, скачивание по контрольному соединению
tsSecondCheck = 40,// сервисный статус, вторичная проверка
tsConnecting = 50, //// сервисный статус, соединение с удаленным Cargador
tsRun = 60, // идет закачка
tsRestarting = 70, // перезапуск после ошибки
tsCompleted = 80, // завершено
tsStopped = 90, // остановлено пользователем
tsError = 0x7fffffff, // ошибка
};
returns: SET OF
::
{
tableKind INT
hash HASH
status INT // см. Status ниже
creationTime TIMESTAMP
user STR
url STR // дружелюбный к пользователю путь к файлу
fileName STR
fileSize INT
fileOfs INT // если status==tsRun (закачка в процессе), текущее обрабатываемое положение
}
**catalogResolve(hash HASH)**
Определяет путь к файлу и его атрибуты в каталоге Cargador
returns:SET OF
::
{
path (net-rooted) TXT
mtm TIMESTAMP
size INT
}
**catalogDelete(hash HASH, password STR)**
Удаляет (фактически переносит во временную директорию) файл в
каталоге.
*hash* - хэш файла к удалению
*password* - должно совпадать со значением, заданным в конфигурационном
файле cargador.conf/config/catalog/del_password.
Операция удаления будет отвергаться в случае, когда параметр
'password' не задан в конфигурационном файле.
Имейте в виду: пароль пересылается в открытом виде.
returns: VOID
**catalogUpload(hash HASH, siteList STR, CommenceFlags INT, userName STR, url STR, retryCount INT)**
**catalogDownload(hash HASH, siteList STR, CommenceFlags INT, userName STR, url STR, retryCount INT)**
Дает команду Cargador приступить к загрузке или выгрузке файла на
удаленный(-ые) Cargador. Метод не дожидается завершения операции,
вместо этого он размещает задание в очереди и завершается.
Используйте statusTables() для мониторинга текущих операций и
controlIO() для их контроля
*hash* - хэш файла для загрузки / выгрузки
*siteList* - строка соспискомудаленных систем Cargador. Формат строки:
::
addr1:port1[?name1][;addr2:port2[?name2]]
*addr* - IP или DNS имя удаленного cargador.
*port* - 'foreign' порт (обычно 45431).
*'name'* - необязательное дружелюбное к пользователю название удаленного
сервера Cargador.
*CommenceFlags* - смотрите ниже
*userName* - имя создавшего файловую операцию. Для информационных целей.
url - дружелюбный к пользователю путь до файла. пример://task
/sub-task/file.name
*retryCount* - количество попыток перед тем, как задача перейдет в
статус ошибки. Система в любом случае перезапускает ошибочные задачи, но
делает это реже.
returns: VOID
**controlIO(hash HASH, TableKind INT, Action INT)**
Контролирует текущие файловые операции.
*hash* -хэш файла.
*TableKind* - таблица, в которой контролируем. Только текущие (т.е. не
архивные) таблицы могут использоваться.
*Action* - что делать (смотрите ниже).
returns: VOID
*Action*
::
{
kUp = 0,
kDown = 1,
kTop = 2,
kBottom = 3,
kStop = 4,
kGo = 6,
kDelete = 7,
}
**importFile(absLocalPath TEXT, [localCargadorFile TEXT])**
**ingestFile(absLocalPath TEXT, localCargadorFile TEXT)**
Импортирует файл по абсолютному пути absLocalPath в каталог Cargador.
ingestFile при этом перемещает файл в каталог Cargador, в то время как
importFile оставляет файл как есть.
absLocalPath должен указывать на доступный для cargador-сервера файл,
т.е. вы не можете, используя этот метод, импортировать локальный файл
со своей рабочей станции в Cargador.
Вы можете использовать HTTP PUT метод для того, чтобы импортировать файл
в каталог Cargador. В составе библиотеки Python API имеется функция
для этого.
returns: importedHash HASH