📚 课程目录第3章 EcoStruxure Web Services（EWS）核心机制

3. EcoStruxure Web Services（EWS）核心机制

EWS 是施耐德电气为 EcoStruxure 平台提供的基于 SOAP 的 Web 服务接口，它把楼宇、配电、工业等场景中的监控数据以标准化的 XML 消息暴露出来。与 REST/JSON 接口不同，EWS 的调用契约由 WSDL 文件严格定义，客户端必须先获取 WSDL，再据此生成代理类或构造 SOAP 报文。理解 EWS 的关键，不在于记住某个方法名，而在于掌握“契约—认证—会话—读写—错误”这条完整链路。

一、SOAP/WSDL 契约：接口的“法律文本”

EWS 的 WSDL 通常通过 https://<服务器>/ews/services/<服务名>?wsdl 获取，例如 https://10.20.30.40/ews/services/Login?wsdl。WSDL 中定义了 types（XSD 数据结构）、message（输入输出消息）、portType（操作集合）、binding（SOAP 绑定与传输协议）和 service（端点地址）。EWS 常用服务包括 Login、Logout、Read、Write、Subscribe、GetItems 等，每个操作都对应一个 soap:operation。

以 Read 为例，其请求体大致如下（示例参数为合理假设）：

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionId>8f3a-...-c21</SessionId>
  </soap:Header>
  <soap:Body>
    <Read xmlns="http://ws.ecostruxure.com/">
      <ItemNames>Building1.Floor2.Room201.Temperature</ItemNames>
      <ItemNames>Building1.Floor2.Room201.Humidity</ItemNames>
    </Read>
  </soap:Body>
</soap:Envelope>

响应中每个 Item 会返回 Value、Quality、Timestamp 三个核心字段。Quality 常见取值有 Good、Bad、Uncertain，它比数值本身更能反映数据是否可信。WSDL 是强类型契约，客户端若字段名拼写错误或命名空间不匹配，服务端会直接返回 SOAP Fault，而不是静默忽略。

二、认证方式与会话管理

EWS 采用“先登录、后调用”的会话模型。客户端调用 Login 操作，提交用户名、密码（通常为明文或经 TLS 保护），服务端验证通过后返回一个 SessionId。后续所有 Read/Write/Subscribe 请求都必须在 SOAP Header 中携带该 SessionId。会话具有空闲超时，典型值为 60 秒到 30 分钟不等，超时后 SessionId 失效，需重新 Login。

认证方式上，EWS 支持基于用户名口令的认证，也可结合 Windows 集成认证或证书。实际部署中，建议始终通过 HTTPS 传输，避免 SessionId 和口令被截获。会话管理有三个易错点：一是 SessionId 必须放在 Header 而非 Body；二是并发调用时不要复用同一个 SessionId 做长事务；三是 Logout 应显式调用，否则会话会占用服务端资源直到超时。

三、数据读写操作

Read 操作按 ItemName 批量读取，一次请求可包含多个 ItemNames，减少往返次数。ItemName 是 EWS 中的路径式标识，形如 Site.Area.Equipment.Point，具体命名由工程组态决定。Write 操作则需提供 ItemName 与 Value，部分实现还要求写入前先读取以确认当前 Quality 为 Good，避免向失效点写入。

批量写入时要注意原子性：EWS 的 Write 通常不是事务性的，若 10 个点中第 7 个失败，前 6 个可能已生效。因此工程上建议对关键写入做“写后读回”校验，即 Write 后立即 Read 同一 ItemName，比对 Value 与 Timestamp 是否更新。Subscribe 用于变化上报，客户端提供回调地址或轮询拉取，适合趋势与报警场景。

四、错误处理模型

EWS 的错误分两层：传输层错误（HTTP 500、连接超时）和业务层错误（SOAP Fault）。SOAP Fault 包含 faultcode、faultstring 和可选的 detail。常见 faultcode 有 Client（请求格式错误）、Server（服务端内部错误）、Session（会话无效或过期）。

处理策略应区分可重试与不可重试：Session 类错误应重新 Login 后重放；Client 类错误应检查 ItemName 拼写、命名空间和参数类型，重试无意义；Server 类错误可做有限次退避重试。下面给出一个可参考的判定表（示例）：

Fault 类型	典型 faultstring	处理动作	是否重试
Session	Invalid or expired session	重新 Login，更新 Header 后重放	是
Client	Unknown item name	核对 ItemName 与 WSDL 定义	否
Client	Type mismatch	检查 Value 的 XSD 类型	否
Server	Internal service error	指数退避，最多 3 次	有限

实践建议：在客户端封装统一的 EWS 调用层，集中处理 SessionId 注入、Fault 解析和重登录逻辑，业务代码只关心 ItemName 与 Value，可显著降低集成复杂度。

综合来看，EWS 的核心机制可以概括为：WSDL 定义“能调什么”，认证与会话定义“谁在调、调多久”，Read/Write 定义“怎么读写”，SOAP Fault 定义“出错怎么办”。把这四者串起来，才能写出稳定、可维护的 EWS 集成代码。