Search Queries
The information is not available in your language.
Некоторые методы BYTEHAND API позволяют задавать условия подсчёта, поиска, изменения и удаления объектов с помощью специального языка. В этом руководстве они помечены как "поддерживающие семантику поисковых запросов". Кроме того, подобные методы для подсчёта и поиска объектов возвращают дополнительную информацию в заголовках ответа.
Язык запросов
Для задания условий поиска используется специальный язык запросов. Обычно при вызове метода BYTEHAND API условия поиска передаются через HTTP параметр запроса query.
Поля, которые можно использовать в условиях поиска, определяются типом объектов и совпадают с названиями его полей.
| Оператор | Описание | Примеры |
|---|---|---|
| text | Поиск объектов, у которых важные поля содержат значение text. Если значение состоит из нескольких слов, то каждое слово ищется отдельно, а результаты поиска будут содержать объекты, в которых есть все слова. Важные поля для поиска определяются типом объектов. | Заказ принят |
| "text" | Поиск объектов, у которых важные поля содержат значение text. Значение ищется целиком и не разбивается на отдельные слова. Важные поля для поиска определяются типом объектов. | "Заказ принят" |
| field:value | Поиск объектов, у которых поле field содержит значение value. Значение можно заключить в двойные кавычки. | id:398453812751341541 text:"Заказ принят" state:delivered |
field=value field!=value field>value field>=value field<value field<=value | Поиск объектов, у которых результат сравнения поля field и значения value является истиной. Значение можно заключить в двойные кавычки. Если поле содержит дату и время, то для значения допускается использовать любые форматы даты и времени. | from=bytehand state!=new price>1 posted_at>=-1day |
| field:id1,id2... | Поиск объектов, у которых поле field имеет одно из перечисленных значений. Значение можно заключить в двойные кавычки. Этот оператор можно использовать только с полями, являющимися идентификаторами объектов. | id:41,42,43 id:"41, 42, 43" |
field field: | Поиск объектов, у которых значение поля field не пустое. | text: |
| -query | Используется для исключения условия query из результатов поиска. | акция -код -text:"Заказ принят" -price: |
query1 or query2 query1 || query2 query1 | query2 | Поиск, соответствующий условию query1 или условию query2. | text:код or text:code |
query1 and query2 query1 && query2 query1 & query2 | Поиск, соответствующий условию query1 и условию query2. По умолчанию все части запроса объединяются с таким условием. | from:bytehand and text:code код code |
| (query) | Используется для группировки условий поиска. | from:bytehand and (text:код or text:code) |
Подсчёт объектов
Поисковые методы, которые вызываются с помощью HTTP метода HEAD, подсчитывают количество объектов, удовлетворяющих заданному условию поиска.
При успешном выполнении запроса возвращается пустой ответ, информация о количестве объектов передаётся в заголовках HTTP ответа.
| Заголовок | Описание | Пример |
|---|---|---|
| Content-Range | Количество найденных объектов в формате type */count. | Sms */518 |
Если объекты не найдены, возвращается ответ с HTTP статусом 404 и объект типа ErrorResponse с кодом 4000 и ошибкой no_results_found.
Поиск объектов
Поисковые методы, которые вызываются с помощью HTTP метода GET, возвращают массив объектов, удовлетворяющих заданному условию поиска.
В заголовках HTTP ответа возвращаются дополнительные данные.
| Заголовок | Описание | Примеры |
|---|---|---|
| Content-Range | Количество найденных объектов в формате type first-last/count. Если указывалось не подсчитывать общее количество объектов, удовлетворяющих поисковому запросу, то count будет иметь значение *. | Sms 0-9/518 Sms 0-9/* |
| Link | Ссылки на следующую, предыдущую, первую и последнюю страницы поиска (если таковые есть). Используйте для навигации по результатам поиска, в соответствии с RFC-5988. | <campaigns/99/ads?page=2>; rel="next", <campaigns/99/ads?page=52>; rel="last" |
Если объекты не найдены, возвращается ответ с HTTP статусом 404 и объект типа ErrorResponse с кодом 4000 и ошибкой no_results_found.
Изменение объектов
Поисковые методы, которые вызываются с помощью HTTP методов PATCH или PUT, позволяют изменять поля объектов, удовлетворяющих заданному условию поиска.
При успешном выполнении запроса обычно возвращается объект типа Response с результатом updated и количеством изменённых объектов.
Если объекты не были найдены и/или изменены, возвращается ответ с HTTP статусом 404 и объект типа ErrorResponse с кодом 4003 и ошибкой nothing_to_update.
Удаление объектов
Поисковые методы, которые вызываются с помощью HTTP метода DELETE, позволяют удалять объекты, удовлетворяющие заданному условию поиска.
При успешном выполнении запроса обычно возвращается объект типа Response с результатом deleted и количеством удалённых объектов.
Если объекты не были найдены и/или изменены, возвращается ответ с HTTP статусом 404 и объект типа ErrorResponse с кодом 4002 и ошибкой nothing_to_delete.