Частичная и жадная загрузка полей приложения

При работе с API получения списка элементов можно задавать правила выборки полей приложения.

Чтобы добавить правило выборки, используйте конструкцию fields:

{
  "fields": {
  }
}

Доступно два способа загрузки полей приложения:

• частичная;
  
• жадная.
  
  

Частичная загрузка полей приложения

Вы можете загружать только выбранные поля приложения и игнорировать остальные.

При этом возможны два варианта использования:

• выборка всех полей и исключение указанных;
  
• загрузка только выбранных полей.
  
  

Выборка всех полей и исключение указанных

{
  "fields": {
    "*": true,
    "Field_Name_1": false,
    "Field_Name_N": false
  }
}

В данном примере:

• "*": true — означает, что загружаются все поля приложения;
  
• "Field_Name_N": false — в строках указаны поля, которые исключаются из выборки.
  
  

Обратите внимание, поле __id загружается всегда.

Загрузка только выбранных полей

{
  "fields": {
    "Field_Name_1": true,
    "Field_Name_N": true
  }
}

В данном примере:

• "*": false — опущено, так как false является значением по умолчанию;
  
• "Field_Name_N": true — в строках указаны поля, которые добавляются в выборку.
  
  

Обратите внимание, поле __id загружается всегда.

Жадная загрузка полей приложения

Важно: жадная зарузка полей доступна только для редакции ELMA365 On-Premises начиная с версии системы 2023.9. Для её использования включите фича-флаг collectorEagerLoadEnabled.

Вы можете загружать вложенные поля следующих типов:

• Приложение;
  
• Пользователи;
  
• Роль;
  
• Таблица.
  
  

Содержимое полей типов Приложение, Пользователи и Роль сортируется по дате создания (поле __createdAt). Содержимое типа данных Таблица сортируется по порядку элементов в таблице.

Также при жадной загрузке полей приложения учитываются заданные для них права доступа.

Рассмотрим примеры.

Загрузка всех полей приложения и вложенных полей нескольких из них

{
  "fields": {
    "*": true,
    "F1": {
      "*": true
    },
    "F2": {
      "__name": true
    }
  }
}

В данном примере поле F1 загружается жадно, со всеми вложенными полями, а для поля F2 загружается только название (__name).

Пример результирующего объекта:

{
  "__id": "3a3503d2-52e6-11ee-be56-0242ac120002",
  "__name": "Item",
  "F1": [
    {
      "__id": "bd8bb825-9e86-451f-9028-9aee48adbe20",
      "__name": "Item 2",
      "Z1": 123
    }
  ],
  "F2": [
    {
      "__id": "7bebc2d4-414a-4a4d-8df1-19851dd04fae",
      "__name": "Item 3"
    }
  ]
}

Загрузка всех полей приложения с вложенными полями нескольких и ограничением объёма выборки

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "$": {
        "first": 20
      }
    },
    "F2": {
      "__name": true,
      "$": {
        "last": 10
      }
    }
  }
}

Данный пример аналогичен предыдущему, за исключением ограничения и направления выборки полей F1 и F2, которая задаётся конструкцией вида:

"$": {
  "first/last": N
}

Где first означает загрузку первых N элементов, а last — загрузку N последних.

Если явно не указаны объём и направление выборки, то по умолчанию выбираются последние 10 элементов. Максимальный объём выборки зависит от параметров системы, по умолчанию — 100 элементов.

Также не допускается одновременное использование first и last в рамках одного блока.

Загрузка полей с несколькими уровнями вложенности

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "Users": {
        "*": true,
        "$": {
          "first": 20
        }
      },
      "$": {
        "last": 10
      }
    }
  }
}

Пример результирующего объекта:

{
  "__id": "3a3503d2-52e6-11ee-be56-0242ac120002",
  "__name": "Item",
  "F1": [
    {
      "__id": "bd8bb825-9e86-451f-9028-9aee48adbe20",
      "__name": "Item 2",
      "Z1": 123,
      "Users": [
        {
          "__id": "1331b48f-87be-4938-a22c-11cefee30a41",
          "__name": "User1",
          "X1": 123
        },
        {
          "__id": "c2b2325c-d7ce-43ab-ab32-00f698c414eb",
          "__name": "User2",
          "X1": 124
        }
      ]
    }
  ]
}

Влияние прав доступа на жадную загрузку полей приложения

Жадная загрузка полей приложения происходит в соответствии с правами доступа к ним. Допустим, в запросе F1 — это поле типа Приложение:

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "Users": {
        "*": true
      }
    }
  }
}

Если у пользователя нет доступа к приложению из поля F1, то в результатах выборки оно будет пустым.
Чтобы получить идентификаторы элементов, к которым доступ отсутствует, явно укажите в запросе поле __id:

{
  "fields": {
    "*": true,
    "F1": {
      "*": true,
      "__id": true,
      "Users": {
        "*": true
      }
    }
  }
}