Вы можете подключиться к Manticore Search через HTTP/HTTPS.
По умолчанию Manticore прослушивает HTTP, HTTPS и бинарные запросы на портах 9308 и 9312.
В разделе "searchd" вашего конфигурационного файла вы можете определить HTTP-порт с помощью директивы listen следующим образом:
Обе строки являются допустимыми и имеют одинаковый смысл (за исключением номера порта). Они обе определяют слушателей, которые будут обслуживать все протоколы API/HTTP/HTTPS. Нет никаких специальных требований, и для подключения к Manticore можно использовать любой HTTP-клиент.
- HTTP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9312:http
...
}Все HTTP-эндпоинты возвращают тип содержимого application/json. В большинстве случаев эндпоинты используют JSON-полезные данные для запросов. Однако есть некоторые исключения, которые используют NDJSON или простые URL-кодированные полезные данные.
В настоящее время аутентификация пользователя отсутствует. Поэтому убедитесь, что HTTP-интерфейс недоступен для всех за пределами вашей сети. Поскольку Manticore функционирует как любой другой веб-сервер, вы можете использовать обратный прокси, такой как Nginx, для реализации HTTP-аутентификации или кэширования.
Протокол HTTP также поддерживает шифрование SSL:
Если вы укажете :https вместо :http, будут приниматься только защищенные соединения. В противном случае, если действительный ключ/сертификат не предоставлен, но клиент пытается подключиться через https - соединение будет разорвано. Если вы сделаете не HTTPS, а HTTP-запрос на порт 9443, он ответит с HTTP-кодом 400.
- HTTPS
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9443:https
...
}Отдельный HTTP-интерфейс может использоваться для 'VIP'-соединений. В этом случае соединение обходит пул потоков и всегда создает новый выделенный поток. Это полезно для управления Manticore Search в периоды сильной перегрузки, когда сервер может зависнуть или не позволять подключения к обычному порту.
Для получения дополнительной информации о директиве listen см. этот раздел.
- VIP
searchd {
...
listen = 127.0.0.1:9308
listen = 127.0.0.1:9318:_vip
...
}Manticore предоставляет эндпоинты /sql, /cli и /cli_json для выполнения SQL-запросов через HTTP. Каждый эндпоинт предназначен для конкретных случаев использования:
/sql: Подходит для программного использования из приложений.- Эндпоинт
/sqlпринимает только операторы SELECT и возвращает ответ в формате HTTP JSON. - Эндпоинт
/sql?mode=rawпринимает любой SQL-запрос и возвращает ответ в сыром формате, аналогично тому, что вы получили бы через mysql.
- Эндпоинт
/cli: Предназначен только для ручного использования (например, через curl или браузер). Не рекомендуется для скриптов./cli_json: Аналогичен/cli, но возвращает результаты в формате JSON. Не рекомендуется для скриптов.
Общий синтаксис:
curl "localhost:6780/sql[?mode=raw]&query={URL_ENCODED_QUERY}"curl localhost:6780/sql[?mode=raw] -d "[query={URL_ENCODED_QUERY}|{NOT_URL_ENCODED_QUERY}]"
Эндпоинт /sql принимает SQL-запрос через HTTP JSON-интерфейс:
- Без
mode=raw- разрешены только SELECT, возвращающие ответ в формате JSON. - С mode=raw - разрешен любой SQL-запрос, возвращающий ответ в сыром формате.
Эндпоинт может обрабатывать HTTP-запросы с использованием либо метода GET, либо метода POST. Для отправки запросов вы можете:
- Используя GET: Включите запрос в параметр
queryURL, например/sql?query=your_encoded_query_here. Важно URL-кодировать этот параметр, чтобы избежать ошибок, особенно если запрос включает знак=, который может быть интерпретирован как часть синтаксиса URL, а не запроса. - Используя POST: Вы также можете отправить запрос в теле POST-запроса. При использовании этого метода:
- Если вы отправляете запрос как параметр с именем
query, убедитесь, что он URL-кодирован. - Если вы отправляете запрос напрямую как обычный текст (сырое тело POST), не URL-кодируйте его. Это полезно, когда запрос длинный или сложный, или если запрос хранится в файле и вы хотите отправить его как есть, указав на него ваш HTTP-клиент (например,
curl).
- Если вы отправляете запрос как параметр с именем
Этот подход сохраняет использование GET и POST различным и избегает путаницы в объединении методов в одном запросе.
Без mode=raw ответ представляет собой JSON, содержащий информацию о совпадениях и времени выполнения. Формат ответа такой же, как у эндпоинта json/search. Обратите внимание, что эндпоинт /sql поддерживает только одиночные поисковые запросы. Для обработки мульти-запроса см. раздел ниже о сыром режиме.
- POST
- POST URL-encoded
- GET URL-encoded
POST /sql
select id,subject,author_id from forum where match('@subject php manticore') group by author_id order by id desc limit 0,5{
"took": 0,
"timed_out": false,
"hits": {
"total": 2,
"total_relation": "eq",
"hits": [
{
"_id": 2,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 12
}
},
{
"_id": 1,
"_score": 2356,
"_source": {
"subject": "php manticore",
"author_id": 11
}
}
]
}
}Эндпоинт /sql также включает специальный "сырой" режим, который позволяет отправлять любые допустимые SQL-запросы, включая мульти-запросы. Ответ представляет собой JSON-массив, содержащий один или несколько наборов результатов. Вы можете активировать этот режим, используя опцию mode=raw.
- POST
- POST URL-encoded
- POST URL-encoded 2nd way
- GET URL-encoded
- curl examples
POST /sql?mode=raw
desc test[
{
"columns": [
{
"Field": {
"type": "string"
}
},
{
"Type": {
"type": "string"
}
},
{
"Properties": {
"type": "string"
}
}
],
"data": [
{
"Field": "id",
"Type": "bigint",
"Properties": ""
},
{
"Field": "title",
"Type": "text",
"Properties": "indexed"
},
{
"Field": "gid",
"Type": "uint",
"Properties": ""
},
{
"Field": "title",
"Type": "string",
"Properties": ""
},
{
"Field": "j",
"Type": "json",
"Properties": ""
},
{
"Field": "new1",
"Type": "uint",
"Properties": ""
}
],
"total": 6,
"error": "",
"warning": ""
}
]ПРИМЕЧАНИЕ:
/cliтребует Manticore Buddy. Если он не работает, убедитесь, что Buddy установлен.
ПРИМЕЧАНИЕ: Эндпоинт
/cliпредназначен для ручного взаимодействия с Manticore с использованием таких инструментов, как curl или браузер. Он не предназначен для использования в автоматизированных скриптах. Вместо этого используйте эндпоинт/sql.
Хотя эндпоинт /sql полезен для программного управления Manticore из вашего приложения, существует также эндпоинт /cli. Это упрощает ручное обслуживание экземпляра Manticore с помощью curl или вашего браузера. Он принимает оба HTTP-метода POST и GET. Всё, что введено после /cli?, понимается Manticore, даже если оно не экранировано вручную с помощью curl или автоматически закодировано браузером. Параметр query не требуется. Важно, что знак + не заменяется на пробел, что устраняет необходимость его кодирования. Для метода POST Manticore принимает всё как есть, без каких-либо изменений. Ответ представлен в табличном формате, аналогичном результату SQL, который вы можете видеть в клиенте MySQL.
- POST
- GET
- Browser
- curl example
POST /cli
desc test
+-------+--------+----------------+
| Field | Type | Properties |
+-------+--------+----------------+
| id | bigint | |
| body | text | indexed stored |
| title | string | |
+-------+--------+----------------+
3 rows in set (0.001 sec)ПРИМЕЧАНИЕ: Эндпоинт
/cli_jsonпредназначен для ручного взаимодействия с Manticore с использованием таких инструментов, как curl или браузер. Он не предназначен для использования в автоматизированных скриптах. Вместо этого используйте эндпоинт/sql.
Эндпоинт /cli_json предоставляет те же функции, что и /cli, но формат ответа — JSON. Он включает:
- раздел
columns, описывающий схему. - раздел
dataс фактическими данными. - Сводный раздел с "total", "error" и "warning".
- POST
- GET
- curl example
POST /cli_json
desc test[
{
"columns":[
{
"Field":{
"type":"string"
}
},
{
"Type":{
"type":"string"
}
},
{
"Properties":{
"type":"string"
}
}
],
"data":[
{
"Field":"id",
"Type":"bigint",
"Properties":""
},
{
"Field":"body",
"Type":"text",
"Properties":"indexed stored"
},
{
"Field":"title",
"Type":"string",
"Properties":""
}
],
"total":3,
"error":"",
"warning":""
}
]Постоянное соединение означает, что клиент держит TCP-соединение открытым и отправляет по нему несколько запросов, вместо того чтобы открывать новое соединение для каждого запроса. Это позволяет избежать повторного разрешения имён и установки соединения, а также позволяет демону сохранять состояние для каждого соединения, такое как метаинформация и профили запросов.
При использовании HTTP/1.0 добавьте Connection: keep-alive для запроса постоянного соединения.
При использовании HTTP/1.1 соединения по умолчанию являются постоянными. Отправьте Connection: close в последнем запросе, чтобы явно завершить сеанс.
На постоянном соединении демон сохраняет некоторое состояние, которое могут использовать последующие запросы. Это состояние сохраняется для эндпоинтов /sql, /sql?mode=raw и /cli_json, но не для /cli. Это позволяет осуществлять взаимодействия с сохранением состояния через HTTP JSON. Например, при использовании /cli_json вы можете выполнить SHOW META после SELECT на том же соединении, аналогично использованию клиента MySQL.
Чтобы выполнить несколько запросов с использованием sphinxql через одно соединение с помощью curl, вам нужно объединить ваши команды с помощью ключа
--next:
curl -s localhost:9312/cli_json -d "CALL PQ ('pq', ('{"title":"angry", "gid":3 }'))" --next localhost:9312/cli_json -d 'show meta'Обратите внимание, однако, что это НЕ сработает:
curl -s localhost:9312/cli_json -d "CALL PQ ('pq', ('{"title":"angry", "gid":3 }')); show meta"Это связано с тем, что Manticore рассматривает пакет SQL, разделённый точкой с запятой, как мультизапрос, который имеет своё собственное поведение и ограничения.