Web API 仅可用于以下系统中固件版本为V2.8 及以上版本的 CPU：• S7-1500 自动化系统的 CPU（不支持 S7-1500R/H 冗余系统的 CPU）•SIMATIC 驱动控制器的 CPU 1504D TF 和 1507D TF• ET 200pro 分布式 I/O 系统的 CPU•ET 200SP 分布式 I/O 系统的 CPU
使用 Web API 之前，必须满足以下要求。• 已在STEP 7 的硬件目录中分配正确的固件版本 (≥ V2.8)。• 已创建并组态项目并将其下载到 CPU。• 已在 STEP 7中选中以下复选框– 激活该模块中的 Web 服务器 (Activate web server on this module)JSON对象中的属性顺序不会影响 API 客户端。Web 服务器通过 API 对请求的响应可能会在未来的固件版本中使用新的 JSON属性进行扩展，例如，用更多细节丰富结果。基于 JSON-RPC 的可能 API错误消息的错误代码可能会在未来固件版本中更改（如果适用），并且现有的错误消息可能会更加jingque。说明要检查您的 API请求是否成功，首先检查请求一般而言是否成功。可评估 JSON-RPC错误代码以获取详细信息。文本错误信息仅提供信息。如果想以特定于应用程序的方式实现错误评估，请使用错误消息的相应数字错误代码。浮点值的精度可能与其它客户端（例如TIA Portal）中显示的不同。批量请求始终按照降序处理，各个请求是按降序包含在 HTTP 请求正文中的。如果 API方法包含时间戳，则始终根据 UTC 时间返回这些时间戳。例如，Files.Browse 和Api.BrowseTickets方法的时间戳。通过 API 方法 Plc.ReadSystemTime 和Plc.ReadTimeSettings，可读出系统时间并确定 PLC 本地时间。139API（应用程序编程接口）Web服务器功能手册, 11/2022, A5E03484629-AJ受支持的客户端下表中列出的产品和版本已针对 Web API进行测试。“Zui低版本”列出了经测试可支持相应客户端的Zui低版本Web API 基本功能以下部分概括介绍了所有 Web API基本功能并显示相应 HTML 代码节选。说明包含 Web API 方法的文件必须经过编码并以 UTF-8 字符编码形式存储。有关将Web API 集成到 Web 应用程序中的详细示例，请参见“Web API 集成 (页145)”部分。Api.LoginApi.Login 方法会检查用户的登录数据，成功进行身份验证后，会打开新的 Web API会话。该方法请求以普通文本形式提供用户名和密码作为授权依据。用户名和密码在传送到服务器之前会进行加密。令牌令牌由 28字节的字符串组成。令牌以加密形式传输。对于其它每一个需要进行身份验证的请求，均需要在 HTTP请求标头中指定分配的令牌。如果在此期间不再进行进一步通信，令牌Zui多会在 2.5分钟后失效。会话中每次出现新请求，令牌有效期都会额外延长 2 到 2.5分钟（从服务器完成处理请求之时计起）。对于不需要验证的方法，无需使用令牌。但是，仍可以输入令牌。如果调用方法时传送令牌，将重置相应会话的超时。例如，当调用无令牌的Api.Ping 方法时，会话不会延长，因为 CPU 无法为用户分配令牌。以下方法可使用和不使用令牌：• Api.Browse•Api.Ping•Api.GetPermissions“Everybody”用户“Everybody”用户在没有指定密码的情况下设置。如果要获取“Everybody”用户的令牌，请发送“Everybody”作为用户，并将密码留空("")。说明“Everybody”用户请注意，与 TIA Portal 不同，API 仅接受英语文本“Everybody”。
可能出现的错误消息下表列出了 Api.Login方法可能出现的错误消息。错误代码 错误消息 含义100 Login failed用户名和/或密码无效。分配可靠的用户名和密码。登录失败的另一个原因可能是主动暴力破解。101 Alreadyauthenticated 当前 X-Auth-Token 已进行身份验证。再次对自身进行身份验证之前使用Api.Logout。4No resources 系统不具备执行该请求所需的资源。足够的资源可用后，立即重新执行请求。示例有关对cookie“web_application_cookie”进行进一步处理的示例，请参见示例：用于监控风力发电机的 Web页面部分。 Api.GetPermissions成功登录后，Api.GetPermissions返回已授权用户执行的操作列表.Web API 会根据在 STEP 7 的“Web 服务器 > 用户管理”(Web server> User administration) 区域中分配的权限和密码检查授权。有关用户管理的说明，请参见“组态 Web 服务器(页 21)”部分。 Api.BrowseApi.Browse 方法提供了可使用当前固件通过 Web API调用的所有方法的列表。此列表可提供CPU 支持的所有方法的总览。调用 Api.Browse 方法不需要任何权限。
Api.Version使用 Api.Version 方法请求 WebAPI 的当前版本号。可以从版本号得出：• CPU 版本支持的功能• CPU 的硬件功能状态144Web 服务器功能手册,11/2022, A5E03484629-AJAPI（应用程序编程接口）5.1 Web API 基本功能借助该信息，在实现应用时可根据CPU 提供的功能范围做出相应调整。一个应用程序可支持多个 CPU 版本。调用 Api.Version方法不需要任何权限。示例下例显示了可能的 Api.Version 方法调用结果。3.28版本号以浮点数形式显示，每次发布以及每次更改Web API 时会加 1。5.1.5 Api.PingApi.Ping 方法会输出所用 CPU 的唯一 ID。可使用该值确定 CPU是否可到达。CPU ID 由 28 字节的字符串组成。每次 CPU 重启 (POWER ON - POWER OFF)或暖启动后，系统都会分配一个新的、唯一的 CPU ID。通过将该值与之前输出的 ID 进行比较，还可以确定 CPU在此期间是会否重启。调用 Api.Ping方法不需要任何权限。Api.GetCertificateUrlApi.GetCertificateUrl 方法会返回相对 URL(https://