Web 服务 API 调用

所有 WS API 调用都必须包含在具有适当 HTTP 标头的 HTTP 请求内。 所有 Service Desk WS API 调用都需要以下标准参数：
 
本节包含以下主题：       
                                                                                            

对所有调用的响应：

不管请求成功还是失败，对 Service Desk WS API 调用的响应包括默认的服务响应 bean 类。 get 响应 bean 类可包含以下成员：

Get 调用

get 调用用于检索基于记录“标识符”的实体的预定义字段值集。

get 请求

除常规的登录 ID 和密码参数外，get 调用还需要以下参数：

get 响应

所有 API 调用的默认服务响应都包含采用 get 调用所请求的输出格式的记录。

list 调用

list 调用用于基于指定的搜索条件检索记录（实体）。

list 请求：除常规的登录 ID 和密码参数外，list 调用还需要以下参数：

list 响应

所有 API 调用的默认服务响应都包含符合搜索条件且采用 list 调用所请求的输出格式的记录集。

insert 调用

insert 调用用于使用指定的值创建特定类型的新记录（实体）。

insert 请求 - 除常规的登录 ID 和密码参数外，insert 调用还需要以下参数：

在插入期间，您不需要为该实体类型指定所有字段。 除那些在 describe 响应中标记为必需的字段（通过布尔值为“0”的属性“nullable”指示）外，大多数字段都为可选字段。 未指定的字段将设置为空或默认值。 太长的字段将会截断。

当您在 insert 请求中发送无法识别的字段值时，Web 服务 API 拒绝此调用。 因此将传输状态代码 300，如以下消息所示：

Rejecting the value that is supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

API 对无法识别的字段值应用严格的定义，以便调用中的所有字段对该操作的用户都必须有效。

例如：

• API 拒绝为已从用户的访问权限中删除或移除的自定义字段指定值的调用。
• API 拒绝指定只读字段的调用。

对于某些类型的实体，如果您尝试插入已经存在的记录，API 将不会插入新记录。

insert 响应

所有 API 调用的默认服务响应都包含将要以 insert 调用所请求的输出格式插入的记录的记录标识符（行 ID）。

update 调用

update 调用用于使用指定的值修改由记录标识符标识的现有记录（实体）。

update 请求

除常规的登录 ID 和密码参数外，update 调用还需要以下参数：

成员：Bean 类

说明：实体特定的 java bean 类（复杂的数据类型），包含更新由记录标识符标识的现有实体时必须更新的字段的值。

在更新期间，您不需要为该实体类型指定所有字段。 请为希望在此调用期间更新的那些字段传递值。

未指定的字段将保持不变。 太长的字段将会截断。 如果您在 update 请求中发送无法识别的字段值，Service Desk WS API 将拒绝调用并发送状态代码 300 和相关的状态信息，该信息包括以下内容：

Rejecting the value supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

• API 对无法识别的字段值应用严格的定义，以便调用中的所有字段对该操作的用户都必须有效。 例如：API 拒绝为已从用户的访问权限中删除或移除的自定义字段指定值的调用。
• API 拒绝指定只读字段的调用。

update 响应：所有 API 调用的默认服务响应都包含将要以 update 调用所请求的输出格式更新的记录的记录标识符（行 ID）。

用户尝试更新故障单时，将显示一条错误消息，指示以下字段为只读字段：

• 请求人组织
• 请求人位置
• 请求人站点
• 请求委托人组织
• 请求委托人位置
• 请求委托人站点
• 上级情况

delete 调用

delete 调用用于删除由记录标识符标识的现有记录（实体）。

delete 请求：除常规的登录 ID 和密码参数外，delete 调用还需要以下参数：

delete 响应

所有 API 调用的默认服务响应都包含将要以 delete 调用所请求的输出格式删除的记录的记录标识符（行 ID）。

relate 调用

relate 调用用于将相应记录标识符标识的一个实体（记录）与另一个实体进行关联。

relate 请求：除常规的登录 ID 和密码参数外，relate 调用还需要以下参数：

relate 响应：所有 API 调用的默认服务响应都包含将要以 relate 调用所请求的输出格式插入关系表中的记录的记录标识符（行 ID）。

unrelate 调用

unrelate 调用用于取消其各自记录标识符标识的一个实体记录与另一个实体的关联。

unrelate 请求 - 除常规的登录 ID 和密码参数外，unrelate 调用还需要以下参数：

unrelate 响应：所有 API 调用的默认服务响应都包含将要以 relate 调用所请求的输出格式插入关联关系表中的记录的记录标识符（行 ID）。

字段级别的安全

Service Desk WS API 执行在服务台用户界面中设置的字段级别的安全型号。 在用户界面中，某些字段可能在页面布局中被标记为只读或隐藏。

对于特定用户，API 只能访问该用户在其指定的页面布局中可访问的那些字段。 将应用以下限制：

• API 可以查询只读字段，但是无法为该用户插入或更新这些字段。
• API 无法查询、插入或更新标记为对该用户隐藏的字段。

使用 Service Desk WS API，任何用户都看不到隐藏字段，包括具有完全权限的用户。 此行为与应用程序的运行方式一致。

数值字段

数值字段包括整型字段和双精度型字段。 根据在“确定标准字段的类型”部分中介绍的条件，标准的预定义字段是整型或双精度型。 所有数值自定义字段都将处理为双精度型。 

在相应情况下，数值字段必须转为 i4 或双精度类型，只不过您可以通过将数值字段设置为空字符串值来将其设为空。 类型在实体的 describe 响应中指示。 

引用该字段的所有未来调用（包括 insert 和 update 调用）都必须采用该类型。 字段的类型也会通过 query 调用返回。 

当插入或更新记录时，会应用数值字段限制。 这些限制在 describe 响应中由整型字段的“位数”属性或双精度型字段的“小数位数”或“精度”属性指示。

小数点左边的最大位数等于“精度”减“小数位数”。 在服务台用户界面中，精度的定义方式不同；它是小数点左边所允许的最大位数。 

当插入或更新数据时，会实施数值字段的限制。 然而，Service Desk WS API 会返回不满足这些限制的数据。