Логика указания входных параметров методов API

Варианты указания входного параметра метода


Обязательность

указания

Требуется

значение (NOT NULL)

ЦветЛогика
Необязательный к указанию с возможностью пустого значения
  •  
  •  

При операции изменения (EDIT, UPDATE) означает, что поле необязательно изменять при потребности изменения объекта. Поле объекта допускает пустое значение. Часто применяется программистом для изменения объекта с целью сброса значения поля.

Дело в том, что пустое значение у ряда полей в системе 1С-Коннект напрямую влияет на поведение системы. Например:

  • оценка "0" у обращения по линии означает, что оценка не проводилась (пользователь не может в программе указать это значение).
  • пустая ссылка на аккаунт 1С-Коннект в поле "Клиент-менеджер" карточки организации означает, что клиент-менеджер не назначен данной организации, и алгоритм доставки обращения не будет приоритетно пытаться доставлять обращение клиент-менеджеру.

При операции чтения данных (READ, LIST) означает, что логикой системы предусмотрено одно из двух:

  • хранение пустого значения поля объекта.
  • соотв. поле в Базе данных не может хранить пустое значение, но необходимо осуществить фильтрацию по правилу "ни одно из значений...".
Необязательный к указанию, но с запретом пустого значения
  •  
  •  

При операции добавления/создания (ADD, INSERT)основной вариант для полей объекта, необязательных к заполнению.

При операции изменения (EDIT, UPDATE) - основной вариант для полей объекта, обязательных к заполнению. То есть, решил изменить объект - можешь не менять это поле (в нём тогда будет предыдущее значение); если уж решил изменить значение поля - укажи новое значение.

При операции чтения данных (READ, LIST) - основной вариант для возможных параметров фильтрации результата. Хочешь фильтровать по параметру - укажи его, обязательно указав значение.


Обязательный к указанию, но с возможностью указать пустое значения
  •  
  •  

не применяется.

Обязательный к указанию, с запретом пустого значения
  •  
  •  

При операции чтения данных (READ, LIST) - применяется для запроса обязательных параметров фильтра.

При операции добавления/создания (ADD, INSERT) - основной вариант для полей объекта, обязательных к заполнению.

При операции изменения (EDIT, UPDATE) - применяется редко, только для запроса параметров, напрямую связанных с транзакцией или фиксацией состояния объекта.

Логика восприятия входных параметров системой

При операции изменения (EDIT, UPDATE) система ожидает, что, если параметр указан - то значение соответствующего поля в объекте данных нужно изменить на указанное.

То есть, если в объекте с 5 полями нужно изменить значение только 2-х - то программисту следует указать только 2 из 5 входных параметров, предназначенных для указания значений этих полей.

При этом, если значение указанного параметра не указано (пустое значение) - система и устанавливает в поле объекта пустое значение. То есть, если бизнес-логикой поле объекта не предусматривает пустое значение, то в соответствующем входном параметре метода API будет запрет на пустое значение указываемого параметра.


При операции добавления/создания (ADD, INSERT) система требует указания значений обязательных к заполнению полей, поэтому вариант R_N не допустим. Не указать входным параметром не обязательное поле объекта - равноценно указанию параметра, но с пустым значением, поэтому вариант NR_N не практикуется. Если параметр не обязателен к указанию (вариант NR_NN) - может означать 2 сценария:

  • поле объекта в принципе необязательно к заполнению (аналогично пониманию NULL в реляционных СУБД).
  • поле самого объекта обязательно к заполнению, но если программист не указал соответствующий параметр - система при создании объекта данных, записывает в это поле значение по умолчанию.


При операции чтения данных (READ, LIST) система ожидает, что если входной параметр указан - значит, необходимо производить отбор списка записей/объектов по данному параметру. Как правило, количество параметров (по сути, фильтра), требуемых к указанию для метода, минимально. Указание нескольких параметров отбора равноценно логике предикатов "AND" (∩), т.е. приводит к отбору одновременно по всем этим значениям. Вследствие этого, вариант R_D бессмысленный, и не практикуется.