Фильтры (filters и id)

Фильтры используются для получения, редактирования или удаления определенных объектов.
id используется для получения, редактирования или удаления конкретного объекта.

Структура параметра filters

filters представляет собой массив, содержащий объекты фильтров fieldFilter.
Фильтр имеет следующие характеристики:

fieldFilter.name - имя поля
fieldFilter.operator - оператор сравнения
fieldFilter.values - массив со значениями фильтра

fieldFilter.values - всегда массив, в том числе для операторов сравнения с одним значением (например, EQUALS)

{"filters":[{"name": /* Имя поля (строка) */, "operator": /* Оператор сравнения (строка) */, "values":[ /* Значения фильтра */ ]}, /*...*/]}

Значения фильтра

fieldFilter.values может содержать числа, строки или имена полей

Для указания поля в качестве значения фильтра, его необходимо указывать в таком формате: "Field:{Имя_поля}".
При сравнении с другим полем нельзя испоьзовать операторы BETWEEN, REGEXP и NOT_REGEXP

Доступные операторы сравнения

Оператор	Описание сравнения	Функция
EQUALS	равно указанному значению	=
NOT_EQUALS	не равно указанному значению	!=
IN	есть в указанных значениях	IN()
NOT_IN	нет в указанных значениях	NOT IN()
GREATER_THAN	больше, чем указанное значение	>
GREATER_THAN_EQUALS	больше или равно указанному значению	>=
LESS_THAN	меньше, чем указанное значение	<
LESS_THAN_EQUALS	меньше или равно указанному значению	<=
BETWEEN	в промежутке между значениями 1 и 2. Последовательно можно перечислять несолько промежутков: values = [10,20,50,100]; // 10..20 или 50..100	BETWEEN
STARTS_WITH	начинается с указанного значения	LIKE '%_'
CONTAINS	содержит подстроку с указанным значением	LIKE '%_%'
DOES_NOT_CONTAIN	не содержит подстроку с указанным значением	NOT LIKE '%_%'
REGEXP	удовлетворяет указанному регулярному выражению	REGEXP()
NOT_REGEXP	не удовлетворяет указанному регулярному выражению	NOT REGEXP()
IS_NULL	поле установлено в null	IS NULL
IS_NOT_NULL	поле не установлено в null	IS NOT null

* Регулярные выражения на wiki, пример записи:

^w+$

Параметр id

Обратите внимание, если в запросе передан параметр id, он будет добавлен к фильтрам в виде:

{"name":"id", "operator":"EQUALS", "values":["{Значение_параметра_id}"]}

Таким образом, параметр id есть краткая запись фильтра по id.
Этот параметр рекомендуется использовать при редактировании одного объекта.

Примеры

Для вывода номеров тегов в примере используется параметр fields

Для примера получим список ключевых слов, добавленных в ядро проекта NN, у которых установлен тег 2 или 3.

Без указания filters С указанием filters С указанием id

Запрос

POST /v2/json/get/keywords_2/keywords/

{"project_id": /* id проекта (число) */,"fields":["id","name","tags"]}

Результат

			{"result":[{"id":"80764821","name":"тестовый запрос 1","tags":"2"},{"id":"80764822","name":"тестовый запрос 2","tags":"2"},{"id":"80764823","name":"тестовый запрос 3","tags":"3"},{"id":"80764824","name":"тестовый запрос 4","tags":"4"},{"id":"80764825","name":"тестовый запрос 5","tags":"5"}]}

Запрос

POST /v2/json/get/keywords_2/keywords/

{"project_id": /* id проекта (число) */,"fields":["id","name","tags"],"filters":[{"name":"tags","operator":"IN","values":[2,3]}]}

Результат

			{"result":[{"id":"80764821","name":"тестовый запрос 1","tags":"2"},{"id":"80764822","name":"тестовый запрос 2","tags":"2"},{"id":"80764823","name":"тестовый запрос 3","tags":"3"}]}

Запрос

POST /v2/json/get/keywords_2/keywords/

{"project_id": /* id проекта (число) */,"fields":["id","name","tags"],"id":80764821}

Результат

			{"result":[{"id":"80764821","name":"тестовый запрос 1","tags":"2"}]}

Пример SDK

Для примера получим список ключевых слов, добавленных в ядро проекта NN, у которых установлен тег 2 или 3.

	<?php

	$projectId = '%NN%'; // ID of your project

	$TVSession = new TVSession();

	$selectorKeywords = new TVPen($TVSession, 'get', 'keywords_2', 'keywords');
	$selectorKeywords->setFields(['id', 'name', 'tags']);
	$selectorKeywords->setData(['project_id' => $project_id]);
	$selectorKeywords->setFilters([
		TVFields::genFilterData('tags', 'IN', [2, 3])
	]);

	$page = $selectorKeywords->exec();
	if(is_null($page->getResult())) return var_dump($page->getErrors());

	// $page - array of keywords
	foreach($page->getResult() as $resultItem){
		var_dump($resultItem);
	}