Спецификация API для работы с сервером проверки на уникальность

Запрос к серверу:

Адрес: http://{xxx.xxx.xxx.xxx}:{порт}/etxt_antiplagiat

POST-параметры для различных действий:

1) Получение текущего состояния сервера:

try=1

2) Постановка пакета в очередь на проверку

xmlUrl={Адрес к xml-пакету с текстами на проверку}
xmlAnswerUrl={Адрес к скрипту, принимающего результаты проверки, должен в конце возвращать "ok" латинскими символами (без кавычек)}

Примечание:

• пакет успешно поставлен в очередь на проверку, если код ответа сервера Code=1
• если скрипт, принимающий результаты проверки не будет возвращать в конце "ok", то сервер будет вновь и вновь повторять попытки отправки результатов проверки

Ответ сервера (в JSON формате):

Code - Возвращает код ответа сервера:

0 - Неизвестная ошибка
1 - Задача на пакетную обработку принята
3 - Неверно указан (или вообще не указан) адрес к xml-файлу с пакетом документов для обработки
4 - Неверно указан адрес при запросе к серверу (должен быть в форме http://{xxx.xxx.xxx.xxx}:{порт}/etxt_antiplagiat)
5 - Неверно указан (или вообще не указан) адрес к скрипту, принимающего результаты обработки проверки
6 - Запрос на состояние сервера успешно обработан
7 - Отсутствует доступ к Интернет
8 - Принята команда на остановку сервера
9 - Запрос на получение трассировочной информации с сервера успешно обработан
10 - Запрос отклонен из-за невозможности проверить доступ клиента к сервису. Можно повторить попытку немного позже
11 - Запрос отклонен из-за отсутствия доступа к сервису (скорей всего из-за нулевого баланса)
12 - Запрос отклонен из-за превышения макс-го кол-ва пакетов в очереди (50 по умолчанию)
13 - Запрос отклонен из-за истечения срока тестового доступа

Description - Возвращает текстовое описание ответа сервера
NumPacketsInQueue - Возвращает текущее число пакетов в очереди
AvgDocumentTime - Возвращает среднее время обработки документа в пакете, в минутах. Будет меньше нуля, если пока эту характеристику невозможно вычислить
CurrentPacketTime - Текущее время обработки текущего пакета, в минутах (целое число). Будет =-1, если оно не вычислялось.
CurDocProgress - Прогресс обработки текущего проверяемого документа в пакете, в процентах (целое число). Будет =-1, если он не вычислялся.

Пример ответа:
{"Code":3,"Description":"В запросе отсутствует адрес с пакетом данных для обработки","NumPacketsInQueue":2,"AvgDocumentTime":-1.000000E+000, "CurrentPacketTime":-1, "CurDocProgress": -1}

Получение результата:

Результат получает скрипт, адрес которого был указан в POST-параметре при запросе к серверу. Ему будут доступны следующие POST-поля:

• XmlFileName - Имя файла Xml-пакета с документами
• NumDocsInPacket - Число документов в пакете
• PacketTime - Время обработки пакета, в минутах
• DocumentTime - Среднее время обработки документа в пакете, в минутах
• ServerType - Параметр, полученный от клиента в Xml-пакете при запросе
• TotalWords - Общее число слов всех документов из пакета после канонизации
• Xml - Результат проверки Xml-пакета, зашифрованный, а затем и кодированный в Base64
• Error - Содержит ошибку, если не удалось проверить Xml-пакет (в этом случае все строковые POST-поля будут пустыми (кроме XmlFileName), а целочисленные - нулевые). Закодирован в Base64
• ServerId - Id сервера (Ip/порт вида {xxx.xxx.xxx.xxx}:{порт})

Формат Xml-пакета (ЗАПРОС)

Примечания:

• символами [] обозначается опциональность присутствия узлов/атрибутов
• выражение (x|y|z) обозначает выбор одного из перечисленных значений, то есть либо x, либо y, либо z
• text[format] - по умолчанию равен "html", то есть html-текст в UTF-8
• text[ftext2] - если "true", то сервер вернет доп. поле ftext2 - форматированный html, где совпавшие шинглы отмечены через имена css-классов (их можно подсветить через них, сами классы соотв-х url с совпадениями пишутся в url[className])
• text[noUrlLimit] - если "true", то в ответе не будет ограничения на кол-во найденных url с совпадениями (по умолчанию передаются только максимум 5 url с наибольшими совпадениями)

<?xml version="1.0" encoding="UTF-8"?> <root> <serverType>{Строка}</serverType> [<exceptions> <url>{Url, игнорируемое при проверке на уникальность каждого документа из пакета, закодированный в Base64}</url> ... <url>...</url> <domain>{домен, игнорируемый при проверке на уникальность каждого документа из пакета, закодированный в Base64}</domain> ... <domain>...</domain> </exceptions>] [<settings> [<NumSamples>{Число выборок (целое число)}</NumSamples>] [<NumRefPerSample>{Число ссылок на выборку (целое число)}</NumRefPerSample>] [<NumSamplesPerDocument>{На весь документ или на каждую 1000 слов (False|True)}</NumSamplesPerDocument>] [<CompareMethod>{Метод обнаружения копий или рерайта или обоими методами (Shingle|Frequency|ShingleFrequency)}</CompareMethod>] [<CompareMethodUniq>{Если CompareMethod = ShingleFrequency, то задает общее значение уникальности (ftext[uniq] и url[unique]) как уникальность по методу обнаружения копий или рерайта; по умолчанию ShingleFrequency, то есть берется просто минимальная уникальность из двух (Shingle|Frequency|ShingleFrequency)}</CompareMethodUniq>] [<NumWordsInShingle>{Число слов в шингле (целое число)}</NumWordsInShingle>] [<IgnoreCitation>{Игнорировать ли цитаты, то есть текст, заключенный в тэги [quote] [/quote] (False|True)}</IgnoreCitation>] [<UniquenessThreshold>{Порог уникальности (целое число)}</UniquenessThreshold>] [<SelfUniq>{Искать ли дубли внутри проверяемого текста (False|True)}</SelfUniq>] </settings>] <entry> <id>{Число}</id> <type>{Строка}</type> <uservars>{Любые пользовательские данные в Xml формате}</uservars> <name>{Имя текста, закодированное в Base64}</name> [<text [format="(html|txt|doc|docx|rtf|pdf)"] [ftext2="true"] [noUrlLimit="true"]>{Содержимое на проверку, закодированное в Base64}</text>] [<exceptions> <url>{Url, игнорируемое при проверке на уникальность, закодированный в Base64}</url> ... <url>...</url> <domain>{домен, игнорируемый при проверке на уникальность, закодированный в Base64}</domain> ... <domain>...</domain> </exceptions>] [<settings>...</settings>] </entry> <entry> ... </entry> </root>

Формат Xml-пакета (ОТВЕТ)

Примечания:

• символами [...] обозначается опциональность присутствия узлов/атрибутов
• если уникальность проверенного текста = 100, то поле ftext отсутствует (но если text[format] был задан в отличное значение от "txt" или "html", то ftext будет возвращаться при любой уникальности)
• в полях url возвращаются (максимум 5) url страниц с наибольшим процентом совпадений с проверяемым текстом
• атрибуты uniqShin и uniqFreq присутствуют только при методе сравнения ShingleFrequency, также в этом случае ftext[uniq] и url[unique] - это уникальность по методу шинглов (если CompareMethodUniq = Shingle) либо уникальность по методу на рерайт (если CompareMethodUniq = Frequency) либо минимальное из соответствующих uniqShin и uniqFreq (если CompareMethodUniq = ShingleFrequency, задано по умолчанию)
• поле ftext2, а также атрибуты url[className] присутствуют только если в исх. запросе text[ftext2]="true" и уникальность проверенного текста < 100
• поле fcit присутствует только если опция IgnoreCitation=true и в тексте есть хотя бы одна цитата

<?xml version="1.0" encoding="UTF-8"?> <root> <numPacketsInQueue>{текущее число пакетов в очереди}</numPacketsInQueue> [<exceptions> <url>{Url, игнорировавшийся при проверке на уникальность каждого документа из пакета, закодированный в Base64}</url> ... <url>...</url> <domain>{домен, игнорировавшийся при проверке на уникальность каждого документа из пакета, закодированный в Base64}</domain> ... <domain>...</domain> </exceptions>] [<settings>...</settings>] <entry> <id>{Число}</id> <type>{Строка}</type> <uservars>{Любые пользовательские данные в Xml формате}</uservars> <name>{Имя текста, закодированное в Base64}</name> [<ftext uniq={Уникальность текста(целое число)} [uniqShin={Уникальность текста по методу шинглов (целое число, от 0 до 100)}] [uniqFreq={Уникальность текста по методу обнаружения рерайта (целое число, от 0 до 100)}] format={Формат текста, который был указан в запросе text[format], по умолчанию это "html"}> {Проверенный текст с выделенными совпавшими шинглами, закодированный в Base64} </ftext>] [<ftext2>{Проверенный текст с совпавшими шинглами, выделенными через имена css-классов, закодированный в Base64}</ftext2>] [<fcit citPercent={Процент цитат в проверенном тексте (целое число, от 0 до 100). Цитатами считается текст, обрамленный тэгами [quote]...[/quote]}> {Текст с выделенными цитатами, закодированный в Base64} </fcit>] [<urls> <url unique={уникальность проверяемого текста по отношению к содержимому данного url (целое число, от 0 до 100)} color={цвет выделения совпавших шинглов в ftext, в виде #xxxxxx} [uniqShin={Уникальность по методу шинглов (целое число, от 0 до 100)}] [uniqFreq={Уникальность по методу обнаружения рерайта (целое число, от 0 до 100)}] [title={содержимое тэга title страницы с данным Url, закодированное в Base64}]> [className={Имя css-класса, которое можно использовать для подсветки совпадений с этим url в ftext2}]> {Url, по которому нашлось совпадение с проверяемым текстом, закодированное в Base64} </url> <url ...> ...</url> ... </urls>] <statistics> <download_ratio>{Отношение общего кол-ва скачанных страниц ко всем страницам (в процентах)}</download_ratio> <total_pages>{Общее кол-во страниц, которое планировалось закачать}</total_pages> <capthas_from_yandex>{Число схваченных капч от Yandex}</capthas_from_yandex> <capthas_from_google>{Число схваченных капч от Google}</capthas_from_google> <capthas_from_nigma>{Число схваченных капч от Nigma}</capthas_from_nigma> </statistics> [<exceptions> <url>{Url, игнорировавшийся при проверке на уникальность, закодированный в Base64}</url> ... <url>...</url> <domain>{домен, игнорировавшийся при проверке на уникальность, закодированный в Base64}</domain> ... <domain>...</domain> </exceptions>] [<settings>...</settings>] </entry> <entry> ... </entry> ... </root>

PHP-класс для общения с сервером проверки на уникальность

<? define('CHECK_KEY', 'ВАШ КЛЮЧ'); class EtxtAntiPlagiat { // путь до сервера private $serverUrl = array ( 'server' => 'xxx.xxx.xxx.xxx:yyy/etxt_antiplagiat', ); // тип сервера по умолчанию public $serverType = 'server'; // путь до веб части проверки private $localServer = 'http://www.site.ru/'; // путь для получения результата public $localUrl = 'http://www.site.ru/antiplagiat/upload.php'; // массив объектов на проверку private $ItemsToCheck = array(); // папка для xml заданий private $xmlPath = '/home/user/site.ru/htdocs/antiplagiat/xml/'; // типы объектов для проверки private $typesObjects = array ('text'); // ключ использования шифра public $useCrypt = 1; // флаг соединения с сервером public $isConnect = false; // статус ошибки public $Error = ''; // флаг-значение приоритета пакета public $sort = 0; // конструктор, параметр - имя xml файла function EtxtAntiPlagiat($path = '', $my_crypt = 1, $serverType = 'server') { if ($path) $this->xmlPath .= $path; $this->useCrypt = $my_crypt; if ($this->useCrypt == 1) $this->useCrypt = CHECK_KEY; $this->serverType = $serverType; // пингуем сервер $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $this->serverUrl[$this->serverType]); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, "try=1"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 5); $json = curl_exec($ch); curl_close($ch); // устанавливаем результат пинга $this->isConnect = $json ? $json : false; $this->isConnect = str_replace('\,', ',', $this->isConnect); if (($tmp = json_decode($this->isConnect)) && $tmp->Code == 7) { $this->isConnect = false; $this->Error = $tmp->Description; } } // функция добавления объекта на проверку public function addItemToCheck($data) { if (!$data['id'] || !in_array($data['type'], $this->typesObjects)) return false; $this->ItemsToCheck[] = array ('id' => $data['id'], 'text' => (isset($data['text']) ? $this->codeText($data['text']) : ''), 'type' => $data['type'], 'name' => $this->codeText($data['name']), 'uservars' => isset($data['uservars']) ? $data['uservars'] : array()); return true; } // функция кодирования текста private function codeText($text) { return base64_encode($text); } // функция выполнения запроса на проверку public function execRequest($create = 1) { // пытаемся создать xml файл с заданиями if ($create && !$this->createXml()) return false; // отправляем запрос на сервер $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $this->serverUrl[$this->serverType]); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, "xmlUrl=".$this->localServer.'antiplagiat/xml/'.basename($this->xmlPath)."&xmlAnswerUrl=".$this->localUrl.($this->sort ? '&sort='.$this->sort : '')); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 5); $json = curl_exec($ch); curl_close($ch); return str_replace('\,', ',', $json); } // функция построения xml файла заданий private function createXml() { $string = '<?xml version="1.0" encoding="UTF-8" ?'.'><root>'; $string .= '<serverType>'.$this->serverType.'</serverType>'; foreach ($this->ItemsToCheck as $item) { $string .= ' <entry> <id>'.$item['id'].'</id> <type>'.$item['type'].'</type>'; if (isset($item['uservars']) && $item['uservars'] && is_array($item['uservars'])) { $string .= ' <uservars>'; foreach ($item['uservars'] as $key => $uservar) $string .= ' <'.$key.'>'.$uservar.'</'.$key.'>'; $string .= ' </uservars>'; } $string .=' <name>'.$item['name'].'</name>'. (isset($item['text']) && $item['text'] ? '<text>'.$item['text'].'</text>' : '').' </entry>'; } $string .= '</root>'; if (is_file($this->xmlPath)) unset($this->xmlPath); // шифруем данные if ($this->useCrypt) { // длина строки должна быть кратна 16, дополняем строку символами "\0" до достижения нужной длины $str_length = strlen($string); $pad_length = ($str_length % 16 == 0) ? $str_length : ($str_length + (16 - ($str_length % 16))); $string = str_pad($string, $pad_length, "\0", STR_PAD_RIGHT); $string = openssl_encrypt ($string, "AES-128-ECB", $this->useCrypt, (OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING)); } // сохраняем файл $f = @fopen($this->xmlPath, 'w') or die("Failed open file # ".$this->xmlPath." # on write"); fwrite($f, $string, strlen($string)); fclose($f); if (is_file($this->xmlPath)) return true; return false; } } ?>

Постановка задания на проверку

// создаем объект для формирования запроса на проверку $etxtPlagiat = new EtxtAntiPlagiat(md5(time()).'.xml', 1, 'server'); // доступность сервера if (!$etxtPlagiat->isConnect || !($tmp = json_decode($etxtPlagiat->isConnect))) { logging('*** Ошибка соединения с сервером проверки на уникальность'); exit(); } // выбираем объекты на проверку $items = SELECT * FROM table // добавляем все объекты на проверку foreach ($items as $item) { // добавляем объект на проверку $etxtPlagiat->addItemToCheck(array('id' => $item['id'], 'text' => $item['text'], 'type' => $item['type'], 'name' => $item['title'], 'uservars' => $item['usersvars'])); } // посылаем запрос серверу на проверку if ($data = $etxtPlagiat->execRequest()) { if ($data = json_decode($data)) { logging($data->Description); exit(); } }

Получение ответа от сервера

// если есть ошибка проверки, то логируем ее if (isset($_POST['Error']) && $_POST['Error']) { $errMsg = base64_decode(str_replace(' ', '+', $_POST['Error'])); ... die('ok'); } // проверка данных в ответе if (!isset($_POST['Xml']) || !$_POST['Xml']) { logging('Данные в ответе сервера не найдены'); exit(); } $_POST['Xml'] = str_replace(' ', '+', $_POST['Xml']); // расшифровываем данные $_POST['Xml'] = openssl_decrypt (base64_decode($_POST['Xml']), "AES-128-ECB", CHECK_KEY, (OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING)); // устанавливаем перехват ошибок libxml_use_internal_errors(true); // пытаемся преобразовать xml в объект if ($xml = simplexml_load_string($_POST['Xml'])) { foreach ($xml->entry as $item) { ... } } echo 'ok';