User API, взаимодействие с другими программами и скриптами

17 ноя 2017 в 16:58
  • A-Parser поддерживает управление через API, что позволяет интегрировать парсер в состав сложных систем, используя возможности парсера из других программ и скриптов

    Версия с API доступна только подписчикам Enterprise лицензии

    Принцип работы(top)

    Взаимодействие с парсером происходит по протоколу HTTP с JSON сериализацией запроса и ответа. Необходимо выполнить POST запрос на адрес http://IP-сервера:9091/API. В качестве тела запроса используется JSON-сериализованная структура:
    Код:
    {
      "password" : "pass",
      "action" : "oneRequest",
      "data" : {
          "query" : "test",
          "parser" : "SE::Google",
          "preset" : "Pages Count use Proxy"
      }
    }
    

    Где:
    • password - пароль на A-Parser
    • action - тип запрос
    • data - параметры запросы, свои для каждого типа запроса
    Ответ в общем виде выглядит так:
    Код:
    {
      "success" : 1,
      "data" : "answer"
    }
    

    Где:
    • success - успешность запроса
    • data - ответ, может быть скалярным или структурой, зависит от типа запроса
    Доступ к API может быть многопоточным

    Модули управления A-Parser через API(top)



    Примеры кода(top)

    PHP:
    $aparser 'http://127.0.0.1:9091/API';

    $request json_encode(array(
        
    'action' => 'oneRequest',
        
    'data' => array (
            
    'parser' => 'SE::Google',
            
    'preset' => 'Pages Count use Proxy',
            
    'query' => 'test'
        
    ),
        
    'password' => 'pass'
    ));

    $ch curl_init($aparser);

    curl_setopt($chCURLOPT_POST1);
    curl_setopt($chCURLOPT_POSTFIELDS$request);
    curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
    curl_setopt($chCURLOPT_HTTPHEADER, array('Content-Length: ' strlen($request)));
    curl_setopt($chCURLOPT_HTTPHEADER, array('Content-Type: text/plain; charset=UTF-8'));

    $response curl_exec($ch);
    curl_close($ch);

    $response json_decode($responsetrue);
    echo 
    $response['data']['resultString'];

    На Perl
    Код:
    use LWP;
    use JSON::XS;
    
    my $aparser = 'http://127.0.0.1:9091/API';
    
    my $request = encode_json {
        'action' => 'oneRequest',
        'data' => {
            'parser' => 'SE::Google',
            'preset' => 'Pages Count use Proxy',
            'query' => 'test'
        },
        'password' => 'pass'
    };
    
    my $ua = LWP::UserAgent->new();
    
    my $response = $ua->post(
        $aparser,
        'Content-Type' => 'text/plain; charset=UTF-8',
        'Content-Length' => length $request,
        'Content' => $request
    );
    
    if($response->is_success) {
        my $json = decode_json $response->content();
        print $json->{'data'}->{'resultString'};
    }
    else {
        warn 'Response fail: ', $response->status_line();
    };
    


    Список поддерживаемых запросов(top)


    ping(top)


    Проверка работы сервера, пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "ping"
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : "pong"
    }
    

    info(top)



    Общая информация и список всех доступных парсеров:
    Код:
    {
      "password" : "pass",
      "action" : "info"
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
             "version" => "1.1.355",
             "availableParsers" => [
                            "SE::Google",
                            "SE::Google::PR",
                            "SE::Google::Maps",
                            "SE::Google::Images",
                            "SE::Google::Suggest",
                            "SE::Google::Position",
                            "SE::Google::Trends",
                            "SE::Google::TrustCheck",
                            "SE::Google::Compromised",
                            "SE::Google::SafeBrowsing",
                            "SE::AOL",
                            "SE::AOL::Suggest",
                            "SE::Ask",
                            "SE::Baidu",
                            "SE::Bing",
                            "SE::Bing::Images",
                            "SE::Bing::Suggest",
                            "SE::Bing::Translator",
                            "SE::Bing::LangDetect",
                            "SE::Comcast",
                            "SE::Dogpile",
                            "SE::DuckDuckGo",
                            "SE::MailRu",
                            "SE::MailRu::Position",
                            "SE::Seznam",
                            "SE::Yahoo",
                            "SE::Yahoo::Suggest",
                            "SE::Yandex",
                            "SE::Yandex::TIC",
                            "SE::Yandex::Catalog",
                            "SE::Yandex::Direct",
                            "SE::Yandex::Direct::Frequency",
                            "SE::Yandex::Register",
                            "SE::Yandex::Position",
                            "SE::Yandex::Suggest",
                            "SE::Yandex::WordStat",
                            "SE::Yandex::WordStat::ByDate",
                            "SE::Yandex::WordStat::ByRegion",
                            "SE::YouTube",
                            "SE::QIP",
                            "SE::QIP::Position",
                            "SEO::Ping",
                            "Check::BackLink",
                            "HTML::LinkExtractor",
                            "HTML::TextExtractor",
                            "HTML::TextExtractor::LangDetect",
                            "Net::Whois",
                            "Net::HTTP",
                            "Net::DNS",
                            "Rank::CMS",
                            "Rank::Ahrefs",
                            "Rank::Alexa",
                            "Rank::Alexa::API",
                            "Rank::Archive",
                            "Rank::Category",
                            "Rank::DMOZ",
                            "Rank::Linkpad",
                            "Rank::MajesticSEO",
                            "Rank::Mustat",
                            "Rank::OpenSiteExplorer",
                            "Rank::SEMrush",
                            "Util::AntiGate"
                          ],
          "tasksInQueue" => 0,
          "pid" => "35136"
      }
    }
    


    oneRequest(top)


    Одиночный запрос на парсинг, может использоваться любой парсер и пресет. В результате будет сформированная строка в соответсвии с форматом результата, заданным в пресете, а так же полный лог работы парсера.
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "oneRequest",
      "data" : {
          "query" : "test",
          "parser" : "SE::Google",
          "preset" : "Pages Count use Proxy"
      }
    }
    


    • parser - каким парсером выполнять запрос
    • preset - какой использовать пресет
    • query - сам запрос
    • rawResults - опциональный параметр, если установлен то вместо результирующей строки resultString вернет массив results со всеми результатами, который поддерживает указанный парсер
    • options - массив с дополнительными опциями применямыми к парсеру, например override - позволяет переопределять значения в пресете
    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "resultString" : "test: 3060000000\n",
          "logs" : [
            [
                0,
                1347516765,
                "Parser SE::Google::0 parse query test"
            ],
            [
                0,
                1347516765,
                "Wait for proxy"
            ],
            [
                0,
                1347516765,
                "Use proxy socks://*"
            ],
            [
                0,
                1347516765,
                "Parse page 1"
            ],
            [
                0,
                1347516779,
                "Request(1): http://www.google.com/search?ie=utf-8&oe=utf-8&hl=en&q=test1&num=10 - 200 OK (38.79 KB)"
            ],
            [
                0,
                1347516779,
                "Total grabbed 10 links"
            ],
            [
                0,
                1347516779,
                "Parse response: 1"
            ],
            [
                0,
                1347516779,
                "Thread complete work"
            ]
          ]
      }
    }
    


    • resultString - строка результата
    • logs - массив с логами выполнения запроса
    Пример запроса с указанием дополнительных параметров через options:
    Код:
    {
      "password" : "pass",
      "action" : "oneRequest",
      "data" : {
          "options" : [
            {
                "value" : 1,
                "type" : "override",
                "id" : "pagecount"
            },
            {
                "value" : 10,
                "type" : "override",
                "id" : "linksperpage"
            }
          ],
          "query" : "test",
          "rawResults" : 1,
          "parser" : "SE::Google",
          "doLog" : 0,
          "preset" : "default"
      }
    }
    

    bulkRequest(top)


    Массовый запрос на парсинг, может использоваться любой парсер и пресет, а так же указано в какое количество потоков производить парсинг. В результате будет сформированная строка в соответсвии с форматом результата, заданным в пресете, а так же полный лог работы парсера по каждому потоку.
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "bulkRequest",
      "data" : {
          "parser" : "SE::Google",
          "preset" : "Pages Count use Proxy",
          "threads" : 5,
          "rawResults" : 1,
          "queries" : [
            "test1",
            "test2",
            "test3",
            "test4",
            "test5"
          ]
      }
    }
    


    • parser - каким парсером выполнять запрос
    • preset - какой использовать пресет
    • threads - количество потоков для парсинга
    • queries - массив запросов
    • rawResults - опциональный параметр, если установлен то вместо результирующей строки resultString вернет массив results со всеми результатами, который поддерживает указанный парсер
    • options - массив с дополнительными опциями применямыми к парсеру, например override - позволяет переопределять значения в пресете
    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "logs" : {
            "4" : {
                "1" : [
                  [
                      0,
                      1350399396,
                      "Parser SE::Google::0 parse query test5"
                  ],
                  [
                      0,
                      1350399396,
                      "Wait for proxy"
                  ],
                  [
                      0,
                      1350399396,
                      "Use proxy socks://176.9.9.90:22515"
                  ],
                  [
                      0,
                      1350399396,
                      "Parse page 1"
                  ],
                  [
                      0,
                      1350399403,
                      "Request(1): http://www.google.com/search?ie=utf-8&oe=utf-8&hl=en&q=test5&num=10 - 503 Service Unavailable (0 KB)"
                  ],
                  [
                      0,
                      1350399403,
                      "Parse response: 3"
                  ],
                  [
                      0,
                      1350399403,
                      "Wait for proxy"
                  ],
                  [
                      0,
                      1350399403,
                      "Use proxy socks://176.9.9.90:21917"
                  ],
                  [
                      0,
                      1350399408,
                      "Request(2): http://www.google.com/search?ie=utf-8&oe=utf-8&hl=en&q=test5&num=10 - 200 OK (39.84 KB)"
                  ],
                  [
                      0,
                      1350399408,
                      "Total grabbed 10 links"
                  ],
                  [
                      0,
                      1350399408,
                      "Parse response: 1"
                  ],
                  [
                      0,
                      1350399408,
                      "Thread complete work"
                  ]
                ]
            },
            <вырезаны логи еще 4ёх потоков>
          },
          "results" : [
            {
                "related" : [],
                "formatresult" : "{query}: {totalcount}\\n",
                "query" : "test1",
                "serp" : [
                    <вырезан массив серпа>
                ],
                "totalcount" : "12200000",
                "origquery" : "test1"
            },
            {
                "related" : [],
                "formatresult" : "{query}: {totalcount}\\n",
                "query" : "test2",
                "serp" : [
                  <вырезан массив серпа>
                ],
                "totalcount" : "14200000",
                "origquery" : "test2"
            },
            <вырезано еще 3 результата>
          ]
      }
    }
    

    getParserPreset(top)


    Получение настроек указанного парсера и пресета
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getParserPreset",
      "data" : {
          "parser" : "SE::Google",
          "preset" : "default"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "queryformat" : "$query",
          "parsenotfound" : 1,
          "gl" : "",
          "pagecount" : 5,
          "do_gzip" : 1,
          "domain" : "www.google.com",
          "timeout" : 60,
          "useproxy" : 1,
          "antigatepreset" : "default",
          "extraquery" : "",
          "serptime" : "",
          "usesessions" : 0,
          "filter" : 1,
          "linksperpage" : 100,
          "serp" : "",
          "useantigate" : 0,
          "proxyretries" : 10,
          "requestdelay" : 0,
          "proxybannedcleanup" : 300,
          "formatresult" : "$serp.format('$link\\n')",
          "lr" : "",
          "usecaptchakiller" : 0,
          "max_size" : 204800
      }
    }
    


    getProxies(top)


    Запрос списка живых проксей. Возвращается список живых прокси со всех чекеров.
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getProxies",
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "127.0.0.1:23486" : [
            "socks"
          ],
          "127.0.0.1:23140" : [
            "socks"
          ],
          "127.0.0.1:21971" : [
            "http"
          ]
      }
    }
    

    Первым элементом массива идет тип прокси, может принимать 2 значения - http или socks. Если указана авторизация по логин\паролю то вторым и третьим элементами будет логин и пароль.

    Если дополнительно указать:
    Код:
    {
       "data" : {
          "checkers" : [
             "Elite proxies",
             "free proxies"
          ]
       }
    }
    
    то будут переданы прокси только по выбранным прокси-чекерам.

    setProxyCheckerPreset(top)


    Добавлен с версии 1.1.128
    Установка текущего пресета проверки прокси
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "setProxyCheckerPreset",
      "data" : {
        "preset" : "default"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
      }
    }
    

    addTask(top)


    Добавление задания в очередь, все параметры аналогичны тем что задаются в интерфейсе в Add Task
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "addTask",
      "data" : {
          "resultsFileName" : "api-test.txt",
          "parsers" : [
            [
                "SE::Google",
                "default",
                {
                  "value" : "$serp.format('$link\\n')",
                  "id" : "formatresult",
                  "type" : "override"
                },
                {
                  "value" : 1,
                  "id" : "parseAll",
                  "type" : "options"
                }
            ]
          ],
          "uniqueQueries" : 0,
          "keepUnique" : 0,
          "resultsPrepend" : "",
          "queries" : [
            "bla",
            "blala"
          ],
          "configPreset" : "default",
          "moreOptions" : 0,
          "queriesFrom" : "text",
          "resultsUnique" : "no",
          "doLog" : "no",
          "queryFormat" : "$query",
          "resultsSaveTo" : "file",
          "configOverrides" : [
            [
                "asyncthreads",
                10
            ]
          ],
          "resultsFormat" : "$p1.preset",
          "resultsAppend" : "",
          "queryBuilders" : []
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : "181"
    }
    

    В ответ отдаётся id добавленного задания
    Добавляем задание с запросами из файла:
    Код:
    "queriesFrom": "file",
    "queriesFile": "queries.txt",
    
    

    Можно использовать заранее созданный пресет через интерфейс
    Код:
    {
      "password" : "pass",
      "action" : "addTask",
      "data" : {
          "queriesFrom" : "text",
          "queries" : [
            "google.com",
            "yandex.ru"
          ],
          "configPreset" : "default",
          "preset" : "Analyze Domains"
      }
    }
    

    В этом случае необходимо только указать запросы. Можно так же указать любой из параметров, он будет использован поверх значения в пресете.

    Добавлено в версии 1.1.358
    Флаг removeOnRestart указывает на то, что задания будут удалятся при рестарте парсера.
    Код:
    {
      "password" : "pass",
      "action" : "addTask",
      "data" : {
          "queriesFrom" : "text",
          "queries" : [
            "google.com",
            "yandex.ru"
          ],
          "configPreset" : "default",
          "preset" : "Analyze Domains",
          "removeOnRestart" : 1
      }
    }
    

    Добавлено в версии 1.1.417
    Флаг removeOnComplete указывает на то, что задания будут удалятся после завершения.
    Код:
    {
      "password" : "pass",
      "action" : "addTask",
      "data" : {
          "queriesFrom" : "text",
          "queries" : [
            "google.com",
            "yandex.ru"
          ],
          "configPreset" : "default",
          "preset" : "Analyze Domains",
          "removeOnComplete" : 1
      }
    }
    

    getTaskState(top)


    Получение состояния задания по его id
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getTaskState",
      "data" : {
          "taskUid" : "181"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "status" : "waitSlot",
          "state" : {
            "changeTime" : 1365098637,
            "queriesCount" : 0,
            "logExists" : 0,
            "uniqueResultsCount" : 0,
            "minimized" : 0,
            "queriesDoneCount" : 0,
            "addTime" : 1365098637,
            "additionalCount" : 0,
            "lastQuery" : "none",
            "avgSpeed" : 0,
            "curSpeed" : 0,
            "activeThreads" : "none",
            "startTime" : 0,
            "started" : 0,
            "resultsCount" : 0
          }
      }
    }
    

    В ответ отдаётся статус задания и его состояние(статистика)

    getTaskConf(top)


    Получение конфигурации задания по его id
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getTaskConf",
      "data" : {
          "taskUid" : "181"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : {
          "resultsFileName" : "Aug-26_08-30-00.txt",
          "parsers" : [
            [
                "SE::Google::PR",
                "default"
            ]
          ],
          "resultsPrepend" : "",
          "queriesFrom" : "text",
          "doLog" : "no",
          "resultsSaveTo" : "file",
          "resultsFormat" : "$p1.preset",
          "queryBuilders" : [],
          "resultsAppend" : "",
          "preset" : "default",
          "uniqueQueries" : 0,
          "keepUnique" : 0,
          "configPreset" : "default",
          "queries" : [
            "google.com",
            "yandex.com"
          ],
          "resultsBuilders" : [],
          "moreOptions" : 0,
          "resultsUnique" : "no",
          "queryFormat" : "$query",
          "configOverrides" : []
      }
    }
    

    В ответ отдаётся настройки задания, в т.ч. с результирующем именем файла

    getTaskResultsFile(top)


    Добавлен с версии 1.1.5
    Получение ссылки для скачивания результата по id задания
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getTaskResultsFile",
      "data" : {
          "taskUid" : "181"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1,
      "data" : "http://127.0.0.1:9091/downloadResults?fileName=Jul-29_11-23-42.txt&token=zodrurcj"
    }
    

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

    deleteTaskResultsFile(top)


    Добавлен с версии 1.1.198
    Удаление файла результата по id задания
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "deleteTaskResultsFile",
      "data" : {
          "taskUid" : "181"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1
    }
    

    changeTaskStatus(top)


    Изменение статуса задания по его id
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "changeTaskStatus",
      "data" : {
          "taskUid" : "181",
          "toStatus" : "deleting"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1
    }
    

    Существует всего 4 состояния, в которое можно перевести задание: starting, pausing, stopping, deleting

    moveTask(top)


    Добавлен с версии 1.0.236
    Перемещение задания в очереди по его id
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "moveTask",
      "data" : {
          "taskUid" : "181",
          "direction" : "start"
      }
    }
    

    Пример ответа:
    Код:
    {
      "success" : 1
    }
    

    Возможные направления перемещения:
    • start - в начало очереди
    • end - в конец очереди
    • up - на одну позицию вверх
    • down - на одну позицию вниз

    getTasksList(top)


    Добавлен с версии 1.1.268
    Получает список активных заданий. Если передать дополнительный параметр completed: 1, то получим список завершенных заданий.
    Пример запроса:
    Код:
    {
      "password" : "pass",
      "action" : "getTasksList",
      "data" : {
          "completed" : "1"
      }
    }
    

    Пример ответа:
    Код:
    {
       "data" : [
          "2291",
          "2324",
          "2331",
          "2384",
          "2398",
          "2434",
          "2445",
          "3482",
          "3481",
          "2547",
          "2554",
          "2555",
          "2561",
          "2566",
          "2568",
          "2575",
          "2576",
          "2577",
          "2589",
          "2590",
          "2594",
          "2596",
          "2601",
          "2613",
          "2618",
          "2623",
          "2624"
       ],
       "success" : 1
    }
    

    getParserInfo(top)


    Добавлен с версии 1.1.350
    Выводит список всех доступных результатов, который может вернуть указанный парсер.
    Пример запроса:
    Код:
    {
       "password" : "123",
       "action" : "getParserInfo",
       "data" : {
          "parser" : "SE::Google"
       }
    }
    

    Пример ответа:
    Код:
    {
       "data" : {
          "results" : {
             "arrays" : {
                "serp" : [
                   "Main serp list",
                   [
                      [
                         "link",
                         "Link"
                      ],
                      [
                         "anchor",
                         "Anchor"
                      ],
                      [
                         "snippet",
                         "Snippet"
                      ]
                   ]
                ],
                "ads" : [
                   "Ads list",
                   [
                      [
                         "link",
                         "Link"
                      ],
                      [
                         "anchor",
                         "Anchor"
                      ],
                      [
                         "visiblelink",
                         "Visible link"
                      ],
                      [
                         "snippet",
                         "Snippet"
                      ],
                      [
                         "position",
                         "Block position"
                      ],
                      [
                         "page",
                         "Page"
                      ]
                   ]
                ],
                "related" : [
                   "Related keywords",
                   [
                      [
                         "key",
                         "Keyword"
                      ]
                   ]
                ],
                "pages" : [
                   "Raw data array",
                   [
                      [
                         "data",
                         "Raw data"
                      ]
                   ]
                ]
             },
             "defaultUnique" : [
                "serp",
                "link"
             ],
             "flat" : [
                [
                   "query",
                   "Formatted query"
                ],
                [
                   "query.orig",
                   "Original query"
                ],
                [
                   "query.first",
                   "First query"
                ],
                [
                   "info.success",
                   "Parsing success"
                ],
                [
                   "info.retries",
                   "Used retries"
                ],
                [
                   "info.stats",
                   "Statistics"
                ],
                [
                   "totalcount",
                   "Total results count"
                ],
                [
                   "misspell",
                   "Is query misspelling"
                ]
             ]
          }
       },
       "success" : 1
    }
    

    update(top)


    Добавлен с версии 1.1.350
    Обновляет исполняемый файл парсера до последней доступной версии, после отправки команды A-Parser будет автоматически перезапущен. API вернет ответ об успехе после того, как загрузит и обновит исполняемый файл, это может занять 1-3 минуты.
    Пример запроса:
    Код:
    {
       "action" : "update",
       "data" : {},
       "password" : "123"
    }
    

    Пример ответа:
    Код:
    {
       "success" : 1
    }
    

    getAccountsCount(top)


    Добавлен с версии 1.1.697
    Получение количества активных аккаунтов (для Яндекса)
    Пример запроса:
    Код:
    {
       "action" : "getAccountsCount",
       "data" : {},
       "password" : "123"
    }
    

    Пример ответа:
    Код:
    {
       "success" : 1,
       "data" : {
          "SE::Yandex" : 3
       }
    }
    

    Получение JSON запроса через интерфейс для метода addTask(top)

    C версии 1.1.974 добавлена возможность получить JSON запроса через интерфейс, используя Show API query
    [​IMG]
olegborzov, Oopssik, Metroid и 4 другим нравится это.