API Filter

Изменено Пт, 29 Дек, 2023 на 2:39 PM

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

Фильтры это не простые пары ключ/значение (key/value), а бесключевые массивы из определений фильтра. Каждое определение фильтра представляет собой массив, и значения массива изменяются для каждого типа фильтра.

Для каждого определения фильтра требуется как минимум «тип»(type). Тип ссылается на ключ конфигурации, такой как «равный», «неравный», «между»( eq, neq, between).

Для каждого определения фильтра требуется как минимум «поле»(field). Это имя поля целевого объекта.

Встроенная логика, как и (x или y), поддерживается через типы фильтров AndX и OrX.

Для получения данных всегда выполняются GET запросы.

Авторизация происходит методом Basic, где логин - публичный ключ, а пароль - secret ключ.

При этом заголовок Accept необходимо сохранить

Информацию о ваших API ключах можете найти здесь

$username = 'public key';   // ваш открытый ключ
$password = 'secret key';   // ваш закрытый ключ
$url = 'https://cdek.orderadmin.ru/api/раздел/подраздел?';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_POST,true);
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(   
    'Accept: application/json',
    'Content-Type: application/json')                                                           
);

Примеры запросов:

$request = [
    'filter' => [ 
         [      
            'type'  => 'eq',  // Тип - Equal
            'field' => 'name',   //  Поле - Сущность
            'value' => 'Tom'  // Значение - Значение сущности
         ],      
    ],
];

В URL вписываете раздел и подраздел, в котором будете фильтровать -> & добавляете запрос фильтра

Итоговый URL: https://cdek.orderadmin.ru/api/*раздел*/*подраздел*?filter[0][type]=*eq*&filter[0][field]=*name*&filter[0][value]=*Tom*

Получение данных о проводках по счету для сущности с id=1945784

Используем тип eq для получения конкретных данных:

$request = [
    'filter' => [
        [
            'type'  => 'eq',      // Тип - Equal
            'field' => 'id',          // Поле - Сущность
            'value' => '1945784'     // Значение - Значение сущности
        ],
    ],
];

Итоговый URL: https://cdek.orderadmin.ru/api/accounts/transaction?filter[0][type]=eq&filter[0][field]=id&filter[0][value]=194578

Получить данные о местоположении с типом "город"

$request =  [
        'filter'  =>  [
                [
                    'type'  => 'eq',       // Тип - eq
                    'field'  => 'state',  //  Поле - Сущность
                    'value' => 'город'    // Значения - Значение сущности    
                ],              
       ] ,
    ];

В строке URL, будет запрос выглядеть вот, так -> Пример: https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=eq&filter[0][field]=type&filter[0][value]=город

Получение транзакций по поступлению денежных средств со статусом "подтвержден"

$request =  [ 
        'filter'  =>  [ 
            [ 
                    'type'  => 'eq' ,       // Тип - Equal 
                    'field'  => 'rateModifier',   // Поле - Сущность
                    'value' => '28'  // Значение - Значение сущности (поступление денежных средств в ОА = 28 )  
            ] , 
            [ 
                    'type' => 'eq' ,       // Тип - Equal 
                    'field' => 'state' ,  // Поле - Тип сущности
                    'value' => 'confirmed'   // Значение - "подтвержден" 
            ] , 
        ] 
    ];

Итоговый URL: https://cdek.orderadmin.ru/api/accounts/transaction?filter[0][type]=eq&filter[0][field]=rateModifier&filter[0][value]=28&filter[1][type]=eq&filter[1][field]=state&filter[1][value]=confirmed

Получение данных сразу по несколько заказам (например, 601247 и 601269)

Используем тип in для получения пакетных данных:

$request =  [
        'filter'  =>  [
            [
                    'type'  => 'in' ,       // Тип - In
                    'field'  => 'id' ,      //  Поле - Сущность
                    'values' => [           // Значения - 601247 и 601269
                        '601247',           
                        '601269'
                    ] ,  
            ] ,
        ]
    ] ;

Итоговый URL: https://cdek.orderadmin.ru/api/delivery-services/requests?filter[0][type]=in&filter[0][field]=id&filter[0][values][0]=601247&filter[0][values][1]=601269

Данные о транзакциях по внешним Id

$request =  [
        'filter'  =>  [
                    'type'  => 'in' ,       // Тип - In
                    'field'  => 'extId',     //  Поле - Сущность
                    'values' =>   [        // Значения - 1964293, 1964292 и 1948335
                        '1964293', 
                        '1964292',
                        '1948335'
                    ] ,
        ] ,
    ];

Итоговый URL: https://cdek.orderadmin.ru/api/accounts/transactions?filter[0][type]=in&filter[0][field]=extId&filter[0][values][0]=1964293&filter[0][values][1]=1964292&filter[0][values][2]=1948335

Объединение Сущностей и Aliasing Запросы

Существует встроенный тип запроса для внутреннего соединения, поэтому для каждого типа фильтра имеется необязательный псевдоним(alias). Псевдоним(alias) по умолчанию это row(строка) и относится к сущности, лежащей в основе ресурса REST. Нет фильтра для добавления других сущностей о возврате данных. То есть, только оригинальный целевой ресурс, который по умолчанию - row(строка), будет возвращать результат независимо от того, какие фильтры или заказы применяются через этот модуль.

Этот пример показывает, как отчет присоединяется к полю через внутреннее соединение, уже определенное в сущности строки, а затем фильтруется для r.id = 2:

$request =  [
        'filter'  =>   [
            [
                    'type'  => 'innerjoin' ,     // Тип - Innerjoin
                    'field'  => 'report',        //  Поле - Сущность
                    'alias' => [ 'r' ]           //    Псевдоним (report => r)(необязательно)          
            ] ,
            [      'type' => 'eq',     // Тип - Equal
                    'alias' => 'r',      //  Псевдоним (report => r)(необязательно)
                    'field' => 'id',    // Поле - Сущности
                    'value' => '2'   // Значение - Имя сущности
            ],
       ] ,
    ];

Вы можете сделать внутреннее объединение таблиц из внутреннего соединения использую родителя Alias:

$request =  [
        'filter'  =>   [
              [
                    'type'  => 'innerjoin' ,     // Тип - Innerjoin
                    'parentAlias'  => 'r',    //  Родитель псевдонима
                    'field' =>  'owner',      //   Поле - сущность  
                    'alias' => 'o'           // Псевдоним (owner => o)
               ],
        ],                          
    ];

Все типы фильтров:

eq - равен

$request =  [
        'filter'  =>   [
             [
                    'type'  => 'eq' ,       // Тип - Equal
                    'field' =>  'fieldName',      //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
             ],
        ],                          
    ];

neq - не равен

$request =  [
        'filter'  =>   [
              [
                    'type'  => 'neq' ,       // Тип - Not equal
                    'field' =>  'fieldName',       //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
              ],
        ],                          
    ];

lt - меньше, чем

$request =  [
        'filter'  =>   [
              [
                    'type'  => 'lt' ,       // Тип - Less than
                    'field' =>  'fieldName',      //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
              ],
        ],                          
    ];

lte - меньше или равно, чем

$request =  [
        'filter'  =>   [
               [
                    'type'  => 'lte' ,       // Тип - Less than or Equals
                    'field' =>  'fieldName',       //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
               ],
        ],                          
    ];

gt - больше, чем

$request =  [
        'filter'  =>   [
              [
                    'type'  => 'gt' ,       // Тип - Greater than
                    'field' =>  'fieldName',       //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
              ],
        ],                          
    ];

gte - больше или равно, чем

$request  =  [
        'filter'  =>   [
                [
                    'type'  => 'gte' ,       // Тип - Greater than or Equals
                    'field' =>  'fieldName',      //   Поле -  Имя сущности  
                    'value' => 'matchValue'     // Значение - Соответствовать сущности
                ],
        ],                          
    ];

isnull - равно нулю (поле не задано)

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'isnull' ,       // Тип - Is Null
                    'field' =>  'fieldName'       //   Поле -  Имя сущности  
               ],
        ],                          
    ];

isnull - не равно нулю

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'isnotnull' ,       // Тип - Is not null
                    'field' =>  'fieldName'       //   Поле -  Имя сущности  
               ],
        ],                          
    ];

Примечание: Даты в In и NotIn фильтрах не обрабатываются как даты. Рекомендуется использовать множественные запросы для равенства вместо фильтров для типов данных даты.

in - в списке значений

$request  =  [
        'filter'  =>   [
              [
                    'type'  => 'in' ,       // Тип - In
                    'field' =>  'fieldName',      //   Поле - Имя сущности
                    'values' => [ 1, 2, 3 ]      // Значение -  значение сущности
              ],
        ],                          
    ];

notin - не в списке значений

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'notin' ,       // Тип - Not in
                    'field' =>  'fieldName',    //   Поле -  Имя сущности
                    'values' => [ 1, 2, 3 ]    // Значение -  значение сущности
                ],
        ],                          
    ];

between - между

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'between' ,       // Тип - Between
                    'field' =>  'fieldName',      // Поле - Имя Сущности
                    'from' => 'startValue',    // Значение -  начальное значение
                    'to'    => 'endValue'      // Значение -  конечное значение
               ,
        ],                          
    ];

like (% используется как символ-джокер)

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'like' ,       // Тип - Like
                    'field' =>  'fieldName',       //   Поле -  Имя сущности
                    'value' => 'like%search'      // Значение -  значение сущности
               ],
        ],                          
    ];

Ismemberof

$request  =  [
        'filter'  =>   [
               [
                    'type'  => 'ismemberof' ,       // Тип - Is member Of
                    'field' =>  'fieldName' ,      //   Поле -  Имя сущности
                    'value' => '1'     // Значение -  значение сущности
                ],
        ],                          
    ];

AndX

В запросах AndX условия представляют собой массив типов фильтров для любого из описанных здесь. Соединение всегда будет, и поэтому параметр where внутри условий игнорируется. Параметр where в типе фильтра AndX не игнорируется.

$request  =  [
        'filter'  =>   [
            [
                    'type'  => 'andx' ,       // Тип - AndX
                    'conditions' =>  [         // Условия
                          [ 'field' => 'name', 'type' => 'eq', 'value' => 'ArtistOne'],   // Поле/Тип/Значение
                          [ 'field' => 'name', 'type' => 'eq', 'value' => 'ArtistTwo'],   // Поле/Тип/Значение
            ],
                    'where' =>  'and'       //   Соединение
           ] ,
        ],                          
    ];

OrX

В запросах OrX условия представляют собой массив типов фильтров для любого из описанных здесь. Соединение всегда будет или параметр where внутри условий игнорируется. Параметр where в типе фильтра OrX не игнорируется

$request  =  [
        'filter'  =>   [
            [
                    'type'  => 'orx' ,       // Тип - OrX
                    'conditions' =>  [      // Условия
                          [ 'field' => 'name', 'type' => 'eq', 'value' => 'ArtistOne'],  // Поле/Тип/Значение
                          [ 'field' => 'name', 'type' => 'eq', 'value' => 'ArtistTwo'],  // Поле/Тип/Значение
            ],
                    'where' =>  'and'       //   Соединение
           ] ,
        ],                          
    ];

'ilike' для получения частичных совпадений строк

$request = [
    'filter' => [ 
         [      
            'type'  => 'ilike',  // Используем тип 'ilike' для получения частичных совпадений строк
            'field' => 'name',   //  Сущность - поиск по имени
            'value' => 'Новико%'  //  Значение сущности и обязательно ставим % для поиска всех комбинации 
         ],      
    ],
];

Поддержка | VK | Telegram | Сайт | Оцените нашу работу

Статья помогла?