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

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

Добавление правил выборки осуществляется путем вставки конструкции fields, например:

{
  "fields": {
  }
}

Различают 2 способа загрузки полей приложения:

1. Частичная загрузка;
   
2. Жадная загрузка.
   
   

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

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

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

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

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

{
  "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 можно не указывать, так как оно является значением по-умолчанию. Строки типа "Field_Name_N": true" указывают поля которые следует добавить в выборку.

При этом, поле __id будет загружено в любом случае.

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

Работает только для редакции системы OnPremise, начиная с 2023.9.
Для использования необходимо включить флаг collectorEagerLoadEnabled.

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

1. Приложение;
   
2. Пользователь;
   
3. Роль;
   
4. Таблица.
   
   

Содержимое полей вышеперечисленных типов сортируется по дате создания (поле __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
        }
      ]
    }
  ]
}

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

Как было сказано выше, жадная загрузка полей приложения происходит в соответствии с их правами доступа. Например, если для запроса вида

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

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

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

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