4.6.2.2.5. Коммит новых и измененных экземпляров, удаление

Функция коммита позволяет выполнять операции над переданными ей объектами и возвращает их новое состояния. Формат результата определяется тем, какой формат (JSON или XML) был использован для запроса (заголовок Content-Type).

Формат JSON

В качестве заголовка Content-Type следует использовать значение application/json.

Создание сущности покупателя с автоматически сгенерированным идентификатором:

{
  "commitInstances": [{
      "id": "NEW-sales$Customer",
      "name": "Saltikov",
      "email": "saltikov@mail.com"
      }
  ]
}

Создание сущности покупателя с указанным идентификатором:

{
  "commitInstances": [{
      "id": "NEW-sales$Customer-b32a6412-d4d9-11e2-a20b-87b22b1460c7",
      "name": "Titov",
      "email": "titov@mail.com"
      }
  ]
}

Создание сущности заказа с указанием ссылки на новую сущность покупателя и заполнение атрибутами сущности данного покупателя:

{
  "commitInstances": [{
      "id": "NEW-sales$Order",
      "amount": 15,
      "customer":
          {"id": "NEW-sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
          }
      },{
          "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
          "name": "Dudkin",
          "email": "dudkin@mail.com"
         }
  ]
}

Изменение одновременно двух сущностей покупателей:

{
  "commitInstances": [{
        "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
        "email": "dudkin@mail.ru"
      },
      {
        "id": "sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
        "email": "saltikov@mail.ru"
      }
  ]
}

Удаление сущности покупателя с поддержкой мягкого удаления:

{
  "removeInstances": [{
      "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
      }
  ],
  "softDeletion": "true"
}
  • Массив commitInstances содержит создаваемые или изменяемые сущности.

    • При создании сущности в качестве значения поля id указывается значение NEW-<entityName> или NEW-<entityName>-<entityId>.

    • При изменении сущности в качестве значения поля id указывается значение <entityName>-<entityId>.

    • Далее в списке элементов через запятую указываются названия атрибутов создаваемой или изменяемой сущности и их значения.

      Если при изменении сущности требуется установить какой-либо атрибут в null, то в идентификаторе необходимо указать также представление, включающее этот атрибут. Например:

      {
        "commitInstances": [{
            "id": "sales$Customer-b32a6412-d4d9-11e2-a20b-87b22b1460c7-customer-edit",
            "name": "John Doe",
            "channel": null
            }
        ]
      }

      Здесь представление customer-edit должно содержать атрибут channel, в противном случае его значение не изменится. Для установки в null локального атрибута можно указать всегда доступное представление _local.

  • Массив removeInstances содержит удаляемые объекты. При удалении объекта обязательно указывать значение поля id. Перед удалением будет выполнен merge() переданных объектов, что позволяет, например, проверить, не изменилась ли версия удаляемого объекта.

  • Поле softDeletion управляет режимом мягкого удаления.

Функция вызывается посредством POST обращения к {host:port}/app-portal/api/commit?s=<sessionId>. JSON передается в теле запроса. Функция возвращает массив объектов JSON. Например, при изменении поля email у сущности покупателя будет возвращен следующий массив объектов JSON:

[
   {"id":"sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
       "createTs":"2013-06-14T14:07:15.040",
       "createdBy":"admin",
       "deleteTs":null,
       "deletedBy":null,
       "email":"saltikovvvv@mail.ru",
       "name":"Saltikov",
       "updateTs":"2013-06-14T15:07:03.463",
       "updatedBy":"admin",
       "version":"3"
   }
]                   
Формат XML

В качестве заголовка Content-Type следует использовать значение text/xml.

Пример формата XML

<CommitRequest>
  <commitInstances>
      <instance id="sales$Order-9873c8a8-d4e7-11e2-85c0-33423bc08c84">
          <field name="date">2015-01-30</field>
          <field name="amount">3500.00</field>
          <reference name="customer" id="sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab"/>
      </instance>
  </commitInstances>
  <removeInstances>
      <instance id="sales$Customer-d67c10f0-4d28-4904-afca-4bc45654985d"/>
  </removeInstances>
  <softDeletion>true</softDeletion>
</CommitRequest>                 

Семантика полей XML-документа определяется в схеме http://schemas.haulmont.com/cuba/5.6/restapi-commit-v2.xsd.

В случае запроса в формате XML установка поля в null осуществляется с помощью атрибута null="true". Кроме того, в идентификаторе должно быть указано представление, содержащее данный атрибут. Например:

<CommitRequest>
    <commitInstances>
        <instance id="Order-9873c8a8-d4e7-11e2-85c0-33423bc08c84">
            <field name="amount" null="true"/>
            <reference name="customer" null="true"/>
        </instance>
    </commitInstances>
</CommitRequest>                        

Функция вызывается посредством POST запроса по адресу {host:port}/app-portal/api/commit?s=<sessionId>. XML передается в теле запроса. Запрос возвращает массив объектов XML вида

<instances>
   <instance ...>
   <instance ...>
</instances>              

Схема, содержащая описание результата вызова функции, находится по адресу http://schemas.haulmont.com/cuba/5.6/restapi-instance-v2.xsd