Service Desk Web Service API 基础知识

• 查询您组织的数据。
• 添加、更新和删除数据。

本文提供有关 Web 服务 API 基础知识的信息，并包含以下主题：

API 调用的特点

API 调用包含以下特征：

• 请求和响应：您的客户端应用程序通过 API 准备请求并将其提交至 服务台 Web 服务，服务台 Web 服务会处理该请求并返回响应，您的客户端应用程序会对此响应做出处理。
• 同步：调用 API 之后，您的客户端应用程序将一直等待，直到收到服务的响应为止。 不支持进行异步调用。
• 自动执行与出错时回滚：默认情况下，写入 Service Desk 对象的每个操作都是自动执行的。 此行为与 SQL 中的 AUTOCOMMIT 设置类似。
• 对于尝试写入对象的多个记录的 create()、update() 和 delete() 调用，每个记录的写入操作都会被视为一个单独的事务。 例如，如果客户端应用程序尝试创建两个新帐户，则这些帐户将使用互斥的插入操作创建，这些操作会分别成功或失败，而不是整体得到一个结果。  

• 您的组织必须启用 WS API 访问，尝试访问 WS API 的用户必须具有“Web 服务”类型的许可。
• 您的配置权限是否允许您访问此数据。 您的客户端应用程序以用户身份登录到 Service Desk Web Service。 与登录用户关联的配置文件将同意或拒绝对您组织内的特定对象和字段的访问。
• 在应用程序登录 API 时，所有事务都将以登录用户的身份运行。 因此，为了保护您的数据安全，请仅为该用户（登录用户）授予应用程序成功执行所有调用所需的权限。
• 特定变更是否会有损您组织的服务台数据的参照完整性。
• 对象中的给定字段是否能够更新。 例如，只读字段无法在 create() 或 update() 调用中更改。
• API 自动对自定义对象强制使用规则。 例如，此行为将影响在服务台用户界面中配置为唯一或必需的字段。

Web 服务输出数据格式类型

ServiceAide Cloud Service Management 支持以下 HTTP 协议标准数据类型：

• JSON - http://json.org/
• XML - http://en.wikipedia.org/wiki/XML
• JAVA BEAN - http://en.wikipedia.org/wiki/JavaBean

安全

访问您组织的服务台数据的客户端应用程序受到的安全保护与在服务台用户界面中所用的安全保护相同。 客户端应用程序必须使用组织的有效凭据登录。 服务器会验证这些凭据，如果凭据有效，则允许访问 Web 服务操作。

组织的服务台管理员通过配置用户配置文件并将用户分配到功能和视图，来控制各种功能和视图的可用性。 要访问 API（以发起调用并接收调用结果），用户必须获得“Web 服务”许可。 客户端应用程序只能查询或更新其客户切片可以通过登录用户的配置文件访问的那些对象和字段。

要通过 API 或客户端进行访问，用户必须使用他们的安全令牌或提供他们的登录 ID 和密码来登录。 安全令牌是从服务台自动生成的密钥。

错误处理

API 调用会返回错误数据，以便您的客户端应用程序可以使用这些数据来确定和解决运行时错误。 如果在执行多数 API 调用时出错，API 将提供下列类型的错误处理方式：

• 对于由消息格式错误、验证失败或类似问题造成的错误，API 将返回默认的服务响应，其中包括相应的状态代码和描述性的状态消息。
• 对于多数调用，如果查询特定的问题导致出现错误，则 API 将会返回错误。 例如，如果 create() 请求包含要针对只读字段进行更新的值。

支持的实体

可以使用 ServiceAide Cloud Service Management Web 服务 API 访问和更改以下实体类型：

• 附件
• 变更请求
• 配置项
• 通信
• 联系人
• 定义的搜索
• 突发事件
• 知识文章
• 组织
• 问题
• 项目
• 服务请求
• 支持组
• 任务故障单
• 故障单
• 值列表
• 工作日志

支持的实例列表在将来会有变化。 某些实体对特定用户可能不可访问，取决于组织和用户的权限。

支持的操作

API 调用是指您的客户端应用程序在运行时可以调用以执行任务的特定操作。 ServiceAide Cloud Service Management Web 服务支持以下类型的操作：

ServiceAide Cloud Service Management Web 服务 API 的常规表单

来自客户端的请求发起每个 API 调用且具有来自服务器的响应。 API 调用决不会是从服务器向客户端发起。 每个 API 调用都有方法名称，这是“支持的操作”部分中介绍的操作之一。

ServiceAide Cloud Service Management Web 服务 API 允许您使用 SOAP（简单对象访问协议）或者 XML-RPC（一种用 XML 编码的简单 RPC 机制）对调用进行编码。

SOAP 实施

ServiceAide Cloud Service Management Web 服务 API 允许您使用 SOAP 对您的调用进行编码。 SOAP（简单对象访问协议）是一种基于 XML 的信息交换协议。 有关 SOAP 的详细说明，请访问 http://www.w3.org/TR/SOAP/。

所有支持的操作在 SOAP 实施过程中均可使用。 请参阅“支持的操作”部分。

每个 SOAP 调用都必须发送至 servlet 名称为 webservices/xxxx 的 Service Desk 应用程序服务器主机名。 本部分将概述 Service Desk API 的高级 SOAP 规范。

有关更多技术规范，请参阅位于以下网址的 Service Desk WSDL：http://www.w3.org/TR/SOAP/。

SOAP 命名空间

SOAP 针对不同元素和属性使用不同的命名空间。 该命名空间取决于数据在消息格式、处理或编码中充当的角色。 命名空间反映了 SOAP 中的所有数据类型定义如何委派给 XML 架构。

ServiceAide Cloud Service Management Web 服务 API 使用以下命名空间。