|
API：应用程序接口（API：Application Program Interface）
应用程序接口是一组定义、程序及协议的集合，通过 API 接口实现计算机之间的相互通信。API 的一个主要功能是提供通用功能集。程序员通过调用 API 函数对应用程序进行开发，可以减轻编程任务。 API 同时也是一种中间件，为各种不同平台提供数据共享。巨控的GRM远程模块可以提供API接口，让第三方程序员调用巨控云平台的数据进行二次开发。
巨控GRM 云服务器提供多种不同的API接口以访问 GRM 设备中的数据。各种接口的优缺点见下表： 
本文档描述的是 Web 数据接口。其他接口（内置网页系统/手机 APP 和 OPC Server）在本文档中不涉及。
Web 数据接口对于每个 GRM 设备默认是不开通的，需要开通该功能的请与我们联系。巨控王工：15307483969
WEB 数据接口的使用基本流程：
1：由模块使用者先配置好巨控模块，使之正常运行。确认找我们开通了 WEB 数据接口权限（默认开通）
2：开发者可以先用模块的设备序号密码登录 www.yunplc.com。可以看到模块里面的变量。在这个网页上能看到的变量，能修改的变量，WEB 接口用同样的密码都能读写。
3：开发者根据 WEB 接口文档，来读写变量即可自行开发网页或者 APP,实现对设备的监试，报警，控制。
1.客户端的操作原理
客户端需要 2 步骤动作：第一步是在主服务器上登录，得到一个代表该设备的 Session ID（以后简称 SID），以及该设备对应的数据服务器的地址。第二步是在数据服务器上用 SID 来做读写操作。SID 是一个 64 位的随机数，它是客户端能够访问这个 GRM 设备的唯一凭据。客户端的 IP 地址可能随时变化，只要拥有正确的 SID 就可以跟设备通讯。在不同的设备之间传递 SID 也是可以的。例如，客户自己的服务器到 GRM 服务器来登录，得到 SID，然后把 SID 传给手机 APP 程序，这样手机 APP 程序就可以在不知道 GRM设备密码的情况下读写数据了。
网络上所有的变量都来自于 GRM 模块，在网络上只能使用 GRM 模块中已配置的变量，网络读写权限也是在 GRM 模块里面配置。如果配置 GRM 模块和编写客户端程序的不是同一个人，请自行协调有关变量名的问题。变量名里面的英文是不区分大小写的。如果您从内置网页系统里面查看变量名，要注意系统变量名的替换（参见第三章第 1 节）。当然，客户端也可以用 E 命令来枚举 GRM 设备中的变量名和变量的各种属性。因为所有变量都完全按名字访问，建议在编写客户端程序之前预先确定所有需要在网络上操作的变量的名字。如果客户端程序已经写好，而 GRM 模块又被重新配置，改变了变量名，客户端程序就可能无法正确读写了！除了变量名之外，变量的其它属性可以在 GRM 模块里面随便修改，对网络上的读写操作完全没有影响，包括改变这个变量在 PLC 中的地址，改变数据类型，改变 PLC 通讯参数等等。每个 Session 只要每隔 10 分钟有至少 1 次数据读或写操作，这个 SID 就会一直有效。而如果在连续 10 分钟内没有发生任何数据读写操作，这个 SID 就自动被服务器删除。如果读写操作返回了错误 8，表示服务器认为这个 SID 是无效的，请重新登录一次，不需要管是什么原因。服务器为了防止客户端程序忘了处理错误 8，可能在 1-2 天之内随机的踢掉客户端（曾经有客户端程序忘了处理 SID 失效，结果上线后一个多月才碰上服务器维护重启，导致 SID 无效，结果他的程序就出错了。后来我们增加了这个功能）。因为服务器上的每个 Session 需要占用一定的系统资源，系统给每个 GRM 设备分配的 Session 数目限制为100 个。如果您在 10 分钟之内登录超过 100 次，将得到错误 15，您只能等到某个旧的 SID 在 10 分钟后被删掉，然后才能登录上。客户对于不想使用的 SID 没有办法明确的删除，只能等 10 分钟超时自动删掉。
如果您读取 GRM 设备数据的间隔比较长（1 分钟或者更长），建议可以在每次读取数据之前登录一次，这样您的程序内部不需要记录任何状态。但如果数据读取间隔小于 1 分钟，推荐您只登录一次然后保存着登录得到的 SID，下次就不用再登录了。
我们的主服务器是固定的地址 http://www.yunplc.com:7080（如果客户自行搭建云服务器，请向服务器提供商索取地址），数据服务器有多个，具体某个 GRM 设备属于哪个数据服务器由登录命令返回。如果有多个客户端连接到同一个 GRM 设备，这些客户端会得到同样的数据服务器。如果没有任何客户端访问，GRM 设备端不会有数据流量，只有心跳数据包以维持 GPRS 连接。此时一个月只消耗几兆的流量。只要有任何客户端连接到云服务器，不论是服务器支持的三种接口（内置网页系统，Web 数据接口，OPC Server）中的哪一种，数据服务器都会自动启动到 GRM 设备的读操作。所有客户端的读都被数据服务器缓冲。不论有多少个客户端，到 GRM 设备的读流量只有 1 份。但是写操作是不缓冲的，如果多个客户端从不同的入口都来写同一个 GRM 设备变量，后发出的写会覆盖之前的写的结果，导致只有最后一个写有效。客户需要自行避免其中的冲突问题。
2.客户端登录的推荐作法
我们云服务器已支持标准的 CORS 跨域功能。客户端如果是网页，推荐使用网页上的 JS 代码通过 CORS功能直接连到我们云服务器来获取数据，无需客户端自己的网页服务器从我们云服务器读数据再转发。如果客户自己做网站来从我们服务器获取数据，请特别注意：不要在每次 Web 客户请求页面的时候登录！这样不仅影响系统性能，而且是错误的！因为每个 GRM 设备同时只能登录 100 个 SID。如果 10 分钟内有若干个 Web 客户累计刷新了 100 次页面，那么这个设备的 SID 就用光了，之后您的网站就无法再登录了！如果负载量不大，简单的做法是：在 Web 客户登录您的网站的时候来登录，然后保存 SID 供以后的数据访问来使用。也就是您的每个 Web 客户占用一个我们服务器的 SID。因为每个设备只能同时登录 100 个 SID，
这样就限制了您的网站对每个设备只能同时连接 100 个 Web 客户。对于手机程序（安卓或 IOS），通常也使用这种方法。这样就不需要额外的服务器了，每个手机程序都是直接连接到我们数据服务器的。一般来说每个设备同时上线 100 个手机已经足够用了。如果您要让每个设备
同时上线更多的手机，仍然得用下面的做法，通过自己的一个服务器来缓存数据。对于负载量很大的网站，因为一个 GRM 设备上只有一份数据，在每个 Web 客户请求页面的时候都从我
们数据服务器重复读取是没有意义的，我们推荐的最佳做法是：用客户网站的 Web 服务器内部做一个数据缓存。在有 Web 用户登录到客户网站的时候，客户的 Web 服务器到我们服务器登录一次（对每个设备只需要登录这一次！），然后用单独的一个线程或者定时器，定时读取该设备的全部变量，缓存起来（读全部数据只有第一次需要带所有变量名，以后都可以用[重复上次读]命令）。Web 客户的所有网页请求都从 Web 服务器的缓存里面直接获取数据，无需任何等待。网页如果要写入变量，也是由网页首先提交到 Web 服务器的缓存里面（以保证其他的用户的页面能立刻看到），然后再排队，用 Web 服务器自己的 SID 写到我们数据服务器。（后面 3.4 和 3.6 节有相应的简单做法和最佳做法的流程）
注意，每个 SID 只有一个读命令缓存。如果客户 A 用一个 SID 发出某种方式的读，然后就开始使用 [重复上次读]命令以节约流量，而客户 B 也用这个 SID 发出了另一个不同的读命令，那么客户 A 的“重复上次读”就会读到错误的结果（变成了重复 B 的读命令结果）。因此不要在不同的地方复用同一个 SID。特殊情况下如果确实需要在持续重复读的时候偶尔发出某些额外的
|
