Записи (Records)
Ресурс Record — запись с данными в каталоге.
Запрос
Ответ
URL: /{api url}/catalogs/{catalogId}/records
{?viewId}
{?filters}
{?fields}
{?searchText}
{?sortField}{?sortType}
{?limit}{?offset}
Метод: GET
Параметры:
viewId
(number) — идентификатор вида каталога для фильтра записейcatalogId
(number) — идентификатор каталогаfields
(json array, опционально) — набор возвращаемых полей записей, формат: ["2", "3"]searchText
(string, опционально) — быстрый поиск по вхождениюsortField
(number, опционально) — идентификатор поля для сортировкиsortType
(number, опционально) — тип сортировки1
— по возрастанию (по умолчанию)-1
— по убыванию
limit
(number, опционально) - количество возвращаемых записей (по умолчанию: 100)offset
(number, опционально) — смещение от начала списка (по умолчанию: 0)filters
(array | json-объект, опционально) — набор фильтров по полям, формат описан ниже
Ответ: 200 OK (application/json)
[{
"id": "30991",
"title": "Record title X",
"values": {
"2": "Record title X",
"3": 333,
"4": ["1"],
"8": "2015-11-06T21:00:00.000Z",
"9": ["1"],
"10": null,
"14": [{
"id": "1",
"title": "Victor Nikitin"
}],
"15": [{
"sectionId": "2",
"catalogId": "5",
"catalogTitle": "Clients",
"catalogIcon": "users-10",
"recordId": "33",
"recordTitle": "Companyname 33"
}]
}
}, {
"id": "30990",
"title": "Record title Y",
"values": {
"2": "Record title Y",
"3": 333,
"4": ["1"],
"8": "2015-11-06T21:00:00.000Z",
"9": ["1"],
"10": null,
"14": [{
"id": "1",
"title": "Victor Nikitin"
}],
"15": [{
"sectionId": "2",
"catalogId": "5",
"catalogTitle": "Clients",
"catalogIcon": "users-10",
"recordId": "34",
"recordTitle": "Companyname 34"
}]
}
}]
Пример:
http://company.bpium.ru/api/v1/catalogs/21/records
?limit=50
&filters[0][fieldId]=4
&filters[0][value][at]=2015-10-27T00:00:00+03:00
&filters[0][value][to]=2015-11-19T23:59:59+03:00
&filters[1][fieldId]=15
&filters[1][value][0][catalogId]=18
&filters[1][value][0][recordId]=9
&filters[1][value][1][catalogId]=18
&filters[1][value][1][recordId]=10
filters
— массив фильтров. Поэтому в GET-параметрах каждый добавленный к поисковому запросу фильтр имеет свой последовательный идентификатор: filters[№]
. Каждый фильтр это объект, состоящий из параметра fieldId
(указывает на ID поля для фильтрации данных) и объекта value
(параметры поискового запроса). Value для разных типов полей имеет разную структуру. filters = [
{
fieldId : X,
value : String, или {}, или [], или [ {}, ... ]
},
...
]
- Для текстовых полей — поиск по вхождению:
[value] = текст
- Для чисел, прогресса — поиск по диапазону:
[value][at] = Число1, [value][to] = Число2
- Для дат — поиск по диапазону:
[value][at] = Дата1, [value][to] = Дата2
- Для категории, набора галочек, вопроса, звёзд — поиск по вхождению:
[value][0] = 1, [value][1] = 2
. Для категории и вопроса доступен также формат:[value]=[1,2,3,5]
- Для контактов — поиск по вхождению:
[value] = текст
- Для связанных объектов:
[value][0][catalogId]=18, [value][0][recordId]=9
- Для сотрудников:
[value][0]=21, [value][1]=22, [value][2]=CURRENT_USER
Это расширенный способ указания фильтров для поиска записей по полям. Он позволяет использовать конструкции И и ИЛИ и их комбинации.
Filters
в таком формате необходимо передавать GET-параметром со значением в формате сериализованного JSON-объекта.В примерах ниже значения
filters
передано без сериализации и в многострочном формате (для наглядности).- 1.Пример указания фильтров по полям:
http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
filedId1: value1,
filedId2: value2,
filedIdX: valueX
}
Где
fieldIdX
— идентификатор поля, а valueX
— значения фильтра по полю (формат для разных полей описан выше).
2. Пример с вариантами значения поля:
http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
filedId1: { "$or": [ value1_1, value1_2, value1_3 ] },
filedId2: { "$and": [ value2_1, value2_2, value2_3 ] }
}
Где
$or
— задает условие, что значение поля у найденных записей должно иметь хотя бы одно из перечисленных значений, $and
— задает условие, что значение поля у найденных записей должно содержать (то есть иметь как минимум их) все перечисленные значения.
3. Пример с вариантами условий фильтра по полям:
http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
"$or" : [
{ fieldId1: value1 },
{ fieldId2: value2 }
],
"$and" : [
{ fieldId3: value3 },
{ fieldId4: value4 }
],
}
Где
$or
— одно из условий фильтра по полям должно быть выполнено, $and
— все условия фильтров должны быть выполнены. Условия $or
и $and
могут быть входить друг в друга.
4. Пример с комбинацией вариантов условий по полям и вариантами значений поля:
http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
"$or" : [
{
"$and": [
{filedId1: {"$or": [value1_2, value1_1]}},
{filedId2: value2},
]
},
{
"$and": [
{filedId3: value3},
{filedId4: value4},
]
}
]
}
Параметр
fields
позволяет ограничить набор полей каталога в получаемых записях. Если параметр не указан, то будут получены значения всех полей. Ограничение списка получаемых полей позволяет уменьшать размер получаемых данных, и увеличивает скорость их получения. Также параметр позволяет получить вложенные поля у связанных записей.
fields
необходимо передавать в GET-запросе параметром со значением в формате массива приведенного к строковому формату( например, методом JSON.stringify() ). Массив состоит из идентификаторов (API ID) полей каталога, и/или JSON-объектов с описанием вложенных полей связанных записей.Формат массива для получении обычных полей (без расширенных полей в связанных записях):
[ fieldId1, fieldId2, ... ]
Пример:
[4, 7, 12]
Данный пример получает значения 4, 7 и 12 полей в полученных записях.
Формат JSON-объекта для получения расширенных полей в связанных записях:
{
fieldId: IDполя1,
fields: {
IDкаталога1: [ IDрасширенногоПоля1, IDрасширенногоПоля2, ... ],
IDка талога2: [ IDрасширенногоПоля3, IDрасширенногоПоля4, ... ],
...
}
}
IDполя1
— поле каталога, из которого получаем записиIDкаталогаХ
— Идентификатор каталога связанного в полеIDполя1.
Поле «связанный каталог» может иметь несколько источников. Для каждого каталога источника можно указать какие именно поля нужно получить.IDрасширенногоПоляХ
— идентификаторы полей связанного каталога, которые нужно получить.
Пример:
{
fieldId: 5,
fields: {
27: [ 2, 6 ],
31: [ 7, 12 ]
}
}
Данный пример получает связанные записи из 5-го поля. В связанных записях из 27го каталога получает поля 2 и 6, а в связанных записях из 31го каталога получает поля 7 и 12.
Пример массива с комбинацией получения обычных полей и вложенных полей для связанных записей:
[ {
fieldId: 5,
fields: {
27: [2]
}
},
{
fieldId: 9,
fields: {
19: [3,4]
}
}, 4, 8 ]
Данный пример получает 4, 5, 8 и 9 поля. Для 5 поля дополнительно получает 2 поле у связанных записей из каталога 27, а для 9 поля — 3 и 4 поле у записей из каталога 19.
Обратите внимание, что массив должен быть приведен к строковому виду для передачи в параметр fields. Так, массив из последнего примера в итоговом виде должен выглядеть так:
[{"fieldId":5,"fields":{"27":[2]}},{"fieldId":9,"fields":{"19":[3,4]}},4,8]
Запрос
Ответ
URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}
{?fields}
Метод: GET
Параметры:
catalogId
(number) — идентификатор каталогаrecordId
(number) — идентификатор записиfields
(json array, опционально) — набор возвращаемых полей записей, формат: ["2", "3"]
Ответ: 200 OK (application/json)
{
"id": "31007",
"title": "Record Title",
"privilegeCode": "access", // право на запись
"values": {
"2": "Record Title", // текстовое поле
"3": 333, // число
"4": ["1"], // категория, набор галочек, вопрос
"8": "2015-11-06T21:00:00.000Z", // дата в 0-м часовом поясе
"11": [{ // контакт
"contact": "8-901-234-56-78",
"comment":"основной"
},{
"contact":"8-987-654-32-10",
"comment":""
}]
"14": [{ // сотрудник
"id": "1",
"title": "Victor Nikitin"
}],
"15": [{ // связанный объект
"sectionId": "2",
"catalogId": "5",
"catalogTitle": "Clients",
"catalogIcon": "users-10",
"recordId": "33",
"recordTitle": "Companyname"
}],
"16": [{ // файл
"id": "5",
"title": "bpium_logo.png",
"url": "https://..."
"size": "8513",
"mimeType": "image/png",
"metadata": { // уменьшенные копии для изображений
"preview" : "https://...",
"thumbnail" : "https://..."
}
}]
}
}
Для получения записи со значениями расширенных полей "Связанный каталог" используется опция ?withFieldsAdditional=true. В ответ добавляется свойство recordValues, где перечислены каталоги выведенные в расширенной форме и их значения
"recordValues": {
"2": [
{
"sectionId": "2",
"catalogId": "14",
"catalogTitle": "Связанный каталог",
"catalogIcon": "leisure-15",
"recordId": "32",
"recordTitle": "Наименование записи",
"isRemoved": false
}
],
"4": 100
}
Запрос
Ответ
URL: {domain}/api/v1/catalogs/{catalogId}/records
Метод: POST
Параметры:
catalogId
(number) — идентификатор каталога
Запрос: (application/json)
{
"values": {
"2": "Text", // текстовое поле
"3": 333, // число
"4": ["1","2"], // категория, набор галочек, вопрос
"8": "2015-11-06T21:00:00.000Z", // дата в 0-м часовом поясе
"11": [{ // контакт
"contact": "8-901-234-56-78",
"comment":"основной"
},{
"contact":"8-987-654-32-10",
"comment":""
}]
"14": [{ // сотрудник
"id": "1"
}],
"15": [{ // связанный объект
"catalogId": "5",
"recordId": "35"
}],
"16": [{ // файл
"src": "https://link.com/voice.mp3",
"title": "Awesome voice",
"mimeType": "audio/mp3" // необязательный параметр
}]
}
}
Ответ: 200 OK (application/json)
{
"id": "31015" // идентификатор созданной записи
}
Запрос
Ответ
URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}
Метод: PATCH
Параметры:
catalogId
(number) — идентификатор каталогаrecordId
(number) — идентификатор записи
Запрос: (application/json)
{
"values": {
"2": "text field value",
"4": ["2", "4"],
"11": [{ // контакт
"contact": "8-901-234-56-78",
"comment":"основной"
},{
"contact":"8-987-654-32-10",
"comment":""
}]
"14": [{ // сотрудник
"id": "2"
},{
"id": "3"
}],
"15": [{ // связанный объект
"catalogId": "5",
"recordId": "33"
},{
"catalogId": "5",
"recordId": "34"
}],
"16": [ // файл
// 96, 97 файлы уже существовали и не были изменены
{
"id": "96"
}, {
"id": "97"
},
// прикрепить новый файл, хранящийся на стороннем сервере
{
"src": "https://link.com/image.jpg",
"title": "Логотип",
"mimeType": "image/jpeg" // необязательный параметр
}
]
}
}
Ответ: 200 OK
Запрос
Ответ
URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}
Метод: DELETE
Параметры:
catalogId
(number) — идентификатор каталогаrecordId
(number) — идентификатор записи
Ответ: 200 OK
Last modified 1mo ago