Коллекционные адреса и пачки

Адрес, который заканчивается маркером без имени, — коллекционный. Чтение по нему возвращает список, а запись принимает массив definition и создаёт до 100 узлов одним атомарным вызовом — либо все, либо ни одного.

Правила

Коллекционный адрес — маркер без имени в конце: Catalog.Номенклатура.Attribute, <форма>.Item, …DataSet.<Набор>.Field, <макет>.Cell, Role.<Роль>.Rights.
Массив в definition вместо объекта включает пакетный режим. Каждый элемент несёт своё имя: name у метаданных, форм и СКД, cell у ячеек макета, object у прав ролей.
До 100 элементов за вызов. У ячеек макета ещё ограничение 1000 ячеек: диапазон R2C1:R2C9 — это 9 ячеек.
Атомарно. Если хоть один элемент не проходит, откатывается вся пачка, и ответ называет виновника: definition[i] «Имя»: причина.
Порядок сохраняется. Поздние элементы видят ранние: в одной пачке можно создать группу формы и поля внутри неё.
Контракт пачки — грань #help на коллекционном адресе read-инструмента, например metadata_read с адресом Catalog.Номенклатура.Attribute#help.

Инструмент	Коллекционный адрес	Операция	Ключ элемента
`metadata_write`	`Catalog.X.Attribute`, `Document.X.TabularSection.Y.Attribute`	`create`	`name`
`form_write`	`<форма>.Item`, `.Attribute`, `.Command`, `.Parameter`, `.Attribute.X.Column`	`create`	`name`
`dcs_write`	`…DataSet.X.Field`, `…TotalField` и другие коллекции схемы	`create`	`name`
`spreadsheet_write`	`<макет>.Cell`	`update`	`cell`
`rights_write`	`Role.X.Rights`, `Role.X.RestrictionTemplate`	`update`, `create`	`object`, `name`
`code_write`	модуль	`create_method`	массив текстов в `content`

Пример: три реквизита одним вызовом

аргументы metadata_write

{
  "project": "УТ2020",
  "operation": "create",
  "fqn": "Catalog.Тест.Attribute",
  "definition": [
    { "name": "ИНН", "type": "Строка(12)" },
    { "name": "Скидка", "type": "Число(5,2)" },
    { "name": "Партнёр", "type": "СправочникСсылка.Партнеры" }
  ]
}

Ответ — один заголовок с отметкой ×3 и по строке на каждый созданный узел:

ответ инструмента

### 🟢 create — Catalog.Тест.Attribute ×3

- **status:** 🟢 committed
- **fqn:** `Catalog.Тест.Attribute`
- **operation:** `create`
- **count:** 3

#### Changes

- создан Attribute Catalog.Тест.Attribute.ИНН [Строка(12)]
- создан Attribute Catalog.Тест.Attribute.Скидка [Число(5,2)]
- создан Attribute Catalog.Тест.Attribute.Партнёр [СправочникСсылка.Партнеры]

Та же пачка с опечаткой в типе второго элемента не создаёт ничего и называет виновника:

ответ инструмента

### 🟠 create — Catalog.Тест.Attribute ×3

- **status:** 🟠 rolled_back
- **fqn:** `Catalog.Тест.Attribute`
- **operation:** `create`
- **count:** 3
- **rollback_reason:** definition[1] «Скидка»: тип не разрешён: «Чизло(5,2)»; контракт: metadata_read Catalog.Тест.Attribute#help

Когда пачка, а когда отдельные вызовы

Пачка выгодна, когда узлов три и больше: один вызов, одна проверка, одна запись и одна точка отката. Отдельные вызовы нужны, когда следующий шаг зависит от результата предыдущего — например, сначала узнать имя группы в дереве формы, потом создавать поля.

Типичные ошибки

Массив на именованном адресе (Catalog.X.Attribute.ИНН + массив) или объект на коллекционном — отказ с подсказкой, какой режим ожидался.
Элемент без name — отказ всей пачки с номером элемента.
Больше 100 элементов — разбейте на несколько вызовов.