切换深色模式
LoRaWAN API：设备、订阅、下行与组播
本文件集中说明 LoRaWAN 业务，和 平台管理 API 分开。MQTT / UDP 的业务能力分别见 MQTT 和 UDP。
如何调用
使用 Postman 的 gRPC 请求或生成的 SDK 连接服务器 API 端口，原生包默认 服务器:8080。选择下表方法，填写 Message，Metadata 设置 authorization: Bearer <token>。登录 JWT 与接口密钥的获取见 鉴权说明。不要向 /api/devices 直接发送 JSON，除非部署了额外 REST Gateway。
请求字段以下方参数表为准，bytes 使用 Base64；EUI、地址和密钥按 HEX 字符串处理。参数表中的“按业务校验”表示 proto3 不提供 required 标记，业务仍可能要求对象、字段组合、合法值和权限。普通创建接口不会自动写入现场终端配置。
常用业务顺序
| 任务 | 方法 | 结果核对 |
|---|---|---|
| 查询应用与模版 | ApplicationService/List、DeviceProfileService/List | 保存实际 ID 与区域/版本 |
| 登记 OTAA | DeviceService/Create → CreateKeys | Get / GetKeys，再核对终端 join 和 up |
| 登记 ABP | DeviceService/Create → Activate | GetActivation，再核对真实 up |
| 查询设备 | DeviceService/Get / List，AlinkwiseService/ListTenantDevices | List 使用 limit/offset 分页，跨应用查询注意租户范围 |
| 修改/删除 | DeviceService/Update / Delete | 重新查询目标；删除不擦除终端本地配置 |
| 订阅数据 | InternalService/StreamDeviceEvents / StreamDeviceFrames | 流式读取，多次返回；断线后重连 |
| 查询历史 | AlinkwiseService/ListDeviceUplinkHistory | 按事件、关键字和分页检查；与实时流分开 |
| 单播下行 | DeviceService/Enqueue → GetQueue | txack、confirmed ack（适用时）、业务回复 |
| 取消待发 | DeviceService/FlushQueue | 只能撤销尚未发送的队列 |
| 网关登记与查询 | GatewayService/Create / Get / List | 还需真实 stats 才能证明接入 |
| 建组与成员 | MulticastGroupService/Create、AddDevice、AddGateway | 终端本地还需相同组播会话 |
| 组播下行 | MulticastGroupService/Enqueue → ListQueue | 网关发送及各成员业务接收分别核对 |
OTAA 与 ABP 字段
Create 中的 device 对象包含 dev_eui、name、application_id、device_profile_id 等基础信息。OTAA 之后创建根密钥；LoRaWAN 1.0 / 1.1 对根密钥与网络会话字段要求不同，以终端模版和消息结构为准。ABP 使用 Activate 提交 dev_addr、会话密钥和计数器；不要用 CreateKeys 代替 ABP 激活。
读取密钥只在有权限的受控环境进行，不写入共享日志。重激活会话会影响帧计数与下行，业务运行中不要为排错随意重置。
订阅与重连
StreamDeviceEvents 提供应用事件；StreamDeviceFrames / StreamGatewayFrames 用于帧诊断；StreamRuntimeStatus 用于状态变化。服务端流不是固定周期轮询，一次调用可以持续返回多条。浏览器应使用支持流式 gRPC-Web 的生成客户端，不能按普通单次 JSON 响应解析。
断线后使用退避重连，重新核对认证和设备 ID。实时缓存不是完整历史日志；需要补缺时另查持久化历史，并按事件标识/设备、时间和计数去重。
单播与组播的确认
Enqueue 响应只证明接受进队列。Class A 等下一次上行接收窗口；Class C 仍需可用会话与网关。confirmed 是协议确认要求，不能证明继电器动作或参数已改变。组播的队列和成员由 MulticastGroupService 管理，不通过普通 Application MQTT 单播主题替代。
网关本地终端与组播的 API 转发
G4 Edge 本地终端和组播可以通过 AlinkwiseService/ExecuteGatewayRemoteCommand 操作。它不修改服务器 DeviceService 的档案；命令、参数和编码详见 LoRaWAN MQTT 的私有管理协议。服务器转发当前不支持 group:send；服务器组播下行使用 MulticastGroupService/Enqueue。
常用接口参数与返回
以下集中列出设备、网关、订阅、历史和组播接口。应用集成完整字段见 应用参考，模版见 模版参考，高级 Relay / FUOTA 分别见 Relay 和 FUOTA。
终端登记与队列
device · Create
接口名称： api.DeviceService/Create
功能： 创建 对应资源。Create the given device.
请求： api.CreateDeviceRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device | api.Device | 按业务校验 | 终端对象。 Device object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Get
接口名称： api.DeviceService/Get
功能： 查询 对应资源。Get returns the device for the given DevEUI.
请求： api.GetDeviceRequest；返回： api.GetDeviceResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device | api.Device | 按业务校验 | 终端对象。 Device object. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 Last seen at timestamp. |
device_status | api.DeviceStatus | 按业务校验 | 终端状态。 Device status. |
class_enabled | common.DeviceClass {CLASS_A=0, CLASS_B=1, CLASS_C=2} | 按业务校验 | 已启用的 Class。 Enabled device class. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Update
接口名称： api.DeviceService/Update
功能： 更新 对应资源。Update the given device.
请求： api.UpdateDeviceRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device | api.Device | 按业务校验 | 终端对象。 Device object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Delete
接口名称： api.DeviceService/Delete
功能： 删除 对应资源。Delete the device with the given DevEUI.
请求： api.DeleteDeviceRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · List
接口名称： api.DeviceService/List
功能： 列出 对应资源。Get the list of devices.
请求： api.ListDevicesRequest；返回： api.ListDevicesResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of devices to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
search | string | 按业务校验 | 搜索关键字。 If set, the given string will be used to search on name (optional). |
application_id | string | 按业务校验 | 应用 UUID。 Application ID (UUID) to filter devices on. |
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicst-group ID (UUID) to filter devices on. |
order_by | api.ListDevicesRequest.OrderBy {NAME=0, DEV_EUI=1, LAST_SEEN_AT=2, DEVICE_PROFILE_NAME=3} | 按业务校验 | If set, the given value will be used to sort by (optional). |
order_by_desc | bool | 按业务校验 | If set, the sorting direction will be decending (default = ascending) (optional). |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 Tags to filter devices on. |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 Device-profile ID (UUID) to filter devices on. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of devices. |
result | repeated api.DeviceListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · CreateKeys
接口名称： api.DeviceService/CreateKeys
功能： 创建终端根密钥。Create the given device-keys.
请求： api.CreateDeviceKeysRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_keys | api.DeviceKeys | 按业务校验 | Device-keys object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetKeys
接口名称： api.DeviceService/GetKeys
功能： 查询终端根密钥。Get the device-keys for the given DevEUI.
请求： api.GetDeviceKeysRequest；返回： api.GetDeviceKeysResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_keys | api.DeviceKeys | 按业务校验 | Device-keys object. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · UpdateKeys
接口名称： api.DeviceService/UpdateKeys
功能： 更新终端根密钥。Update the given device-keys.
请求： api.UpdateDeviceKeysRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_keys | api.DeviceKeys | 按业务校验 | Device-keys object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · DeleteKeys
接口名称： api.DeviceService/DeleteKeys
功能： 删除终端根密钥。Delete the device-keys for the given DevEUI.
请求： api.DeleteDeviceKeysRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · FlushDevNonces
接口名称： api.DeviceService/FlushDevNonces
功能： 清空 DevNonces。FlushDevNonces flushes the OTAA device nonces.
请求： api.FlushDevNoncesRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Activate
接口名称： api.DeviceService/Activate
功能： 激活 ABP 会话。Activate (re)activates the device with the given parameters (for ABP or for importing OTAA activations).
请求： api.ActivateDeviceRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_activation | api.DeviceActivation | 按业务校验 | 终端会话激活参数。 Device activation object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Deactivate
接口名称： api.DeviceService/Deactivate
功能： 停用当前会话。Deactivate de-activates the device.
请求： api.DeactivateDeviceRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetActivation
接口名称： api.DeviceService/GetActivation
功能： 查询当前会话。GetActivation returns the current activation details of the device (OTAA or ABP).
请求： api.GetDeviceActivationRequest；返回： api.GetDeviceActivationResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_activation | api.DeviceActivation | 按业务校验 | 终端会话激活参数。 Device activation object. |
join_server_context | common.JoinServerContext | 按业务校验 | Join-Server context. A non-empty value indicatest that ChirpStack does not have access to the AppSKey and that the encryption / decryption of the payloads is the responsibility of the end-application. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetRandomDevAddr
接口名称： api.DeviceService/GetRandomDevAddr
功能： 查询 RandomDevAddr。GetRandomDevAddr returns a random DevAddr taking the NwkID prefix into account.
请求： api.GetRandomDevAddrRequest；返回： api.GetRandomDevAddrResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_addr | string | 按业务校验 | 会话短地址。 DevAddr. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetMetrics
接口名称： api.DeviceService/GetMetrics
功能： 查询 Metrics。GetMetrics returns the device metrics. Note that this requires a device-profile with codec and measurements configured.
请求： api.GetDeviceMetricsRequest；返回： api.GetDeviceMetricsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
aggregation | common.Aggregation {HOUR=0, DAY=1, MONTH=2, MINUTE=3} | 按业务校验 | 聚合粒度。 Aggregation. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
metrics | map<string, common.Metric> | 按业务校验 | 指标集合。 |
states | map<string, api.DeviceState> | 按业务校验 | 消息定义未补充字段说明。 |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetLinkMetrics
接口名称： api.DeviceService/GetLinkMetrics
功能： 查询 LinkMetrics。GetLinkMetrics returns the device link metrics. This includes uplinks, downlinks, RSSI, SNR, etc...
请求： api.GetDeviceLinkMetricsRequest；返回： api.GetDeviceLinkMetricsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
aggregation | common.Aggregation {HOUR=0, DAY=1, MONTH=2, MINUTE=3} | 按业务校验 | 聚合粒度。 Aggregation. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
rx_packets | common.Metric | 按业务校验 | Packets received from the device. |
gw_rssi | common.Metric | 按业务校验 | RSSI (as reported by the gateway(s)). |
gw_snr | common.Metric | 按业务校验 | SNR (as reported by the gateway(s)). |
rx_packets_per_freq | common.Metric | 按业务校验 | Packets received by frequency. |
rx_packets_per_dr | common.Metric | 按业务校验 | Packets received by DR. |
errors | common.Metric | 按业务校验 | Errors. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · Enqueue
接口名称： api.DeviceService/Enqueue
功能： 将下行加入队列。Enqueue adds the given item to the downlink queue.
请求： api.EnqueueDeviceQueueItemRequest；返回： api.EnqueueDeviceQueueItemResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
queue_item | api.DeviceQueueItem | 按业务校验 | 待加入的下行条目。 Item to enqueue. |
flush_queue | bool | 按业务校验 | 是否清空队列。 Flush queue before enqueue. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID (UUID). |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · FlushQueue
接口名称： api.DeviceService/FlushQueue
功能： 清空待发队列。FlushQueue flushes the downlink device-queue.
请求： api.FlushDeviceQueueRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetQueue
接口名称： api.DeviceService/GetQueue
功能： 查询下行队列。GetQueue returns the downlink device-queue.
请求： api.GetDeviceQueueItemsRequest；返回： api.GetDeviceQueueItemsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
count_only | bool | 按业务校验 | Return only the count, not the result-set. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of queue items. |
result | repeated api.DeviceQueueItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
device · GetNextFCntDown
接口名称： api.DeviceService/GetNextFCntDown
功能： 查询 NextFCntDown。GetNextFCntDown returns the next FCntDown to use for enqueing encrypted downlinks. The difference with the DeviceActivation f_cont_down is that this method takes potential existing queue-items into account.
请求： api.GetDeviceNextFCntDownRequest；返回： api.GetDeviceNextFCntDownResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
f_cnt_down | uint32 | 按业务校验 | FCntDown. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套字段的完整结构见 device 消息结构。
网关资源
gateway · Create
接口名称： api.GatewayService/Create
功能： 创建 对应资源。Create creates the given gateway.
请求： api.CreateGatewayRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway | api.Gateway | 按业务校验 | 网关对象。 Gateway object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · Get
接口名称： api.GatewayService/Get
功能： 查询 对应资源。Get returns the gateway for the given Gateway ID.
请求： api.GetGatewayRequest；返回： api.GetGatewayResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway | api.Gateway | 按业务校验 | 网关对象。 Gateway object. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 Last seen at timestamp. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · Update
接口名称： api.GatewayService/Update
功能： 更新 对应资源。Update updates the given gateway.
请求： api.UpdateGatewayRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway | api.Gateway | 按业务校验 | 网关对象。 Gateway object. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · Delete
接口名称： api.GatewayService/Delete
功能： 删除 对应资源。Delete deletes the gateway matching the given Gateway ID.
请求： api.DeleteGatewayRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · List
接口名称： api.GatewayService/List
功能： 列出 对应资源。Get the list of gateways.
请求： api.ListGatewaysRequest；返回： api.ListGatewaysResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of gateways to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
search | string | 按业务校验 | 搜索关键字。 If set, the given string will be used to search on name (optional). |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID (UUID) to filter gateways on. To list all gateways as a global admin user, this field can be left blank. |
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast-group ID (UUID) to filter gateways on. |
order_by | api.ListGatewaysRequest.OrderBy {NAME=0, GATEWAY_ID=1, LAST_SEEN_AT=2} | 按业务校验 | If set, the given value will be used to sort by (optional). |
order_by_desc | bool | 按业务校验 | If set, the sorting direction will be decending (default = ascending) (optional). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of gateways. |
result | repeated api.GatewayListItem | 按业务校验 | 结果列表或结果内容。 Result-set. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · GetMetrics
接口名称： api.GatewayService/GetMetrics
功能： 查询 Metrics。GetMetrics returns the gateway metrics.
请求： api.GetGatewayMetricsRequest；返回： api.GetGatewayMetricsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
aggregation | common.Aggregation {HOUR=0, DAY=1, MONTH=2, MINUTE=3} | 按业务校验 | 聚合粒度。 Aggregation. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
rx_packets | common.Metric | 按业务校验 | RX packets. |
tx_packets | common.Metric | 按业务校验 | TX packets. |
tx_packets_per_freq | common.Metric | 按业务校验 | TX packets / frequency. |
rx_packets_per_freq | common.Metric | 按业务校验 | RX packets / frequency. |
tx_packets_per_dr | common.Metric | 按业务校验 | TX packets / DR. |
rx_packets_per_dr | common.Metric | 按业务校验 | RX packets / DR. |
tx_packets_per_status | common.Metric | 按业务校验 | TX packets per status. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
gateway · GetDutyCycleMetrics
接口名称： api.GatewayService/GetDutyCycleMetrics
功能： 查询 DutyCycleMetrics。GetDutyCycleMetrics returns the duty-cycle metrics. Note that only the last 2 hours of data are stored. Currently only per minute aggregation is available.
请求： api.GetGatewayDutyCycleMetricsRequest；返回： api.GetGatewayDutyCycleMetricsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
max_load_percentage | common.Metric | 按业务校验 | Percentage relative to max load. |
window_percentage | common.Metric | 按业务校验 | Percentage relative to tracking window. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套字段的完整结构见 gateway 消息结构。
组播与成员
multicast_group · Create
接口名称： api.MulticastGroupService/Create
功能： 创建 对应资源。Create the given multicast group.
请求： api.CreateMulticastGroupRequest；返回： api.CreateMulticastGroupResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group | api.MulticastGroup | 按业务校验 | 组播组对象。 Multicast group to create. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID of created multicast group (UUID). |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · Get
接口名称： api.MulticastGroupService/Get
功能： 查询 对应资源。Get returns the multicast group for the given ID.
请求： api.GetMulticastGroupRequest；返回： api.GetMulticastGroupResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 Multicast group ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group | api.MulticastGroup | 按业务校验 | 组播组对象。 Multicast group object. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · Update
接口名称： api.MulticastGroupService/Update
功能： 更新 对应资源。Update the given multicast group.
请求： api.UpdateMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group | api.MulticastGroup | 按业务校验 | 组播组对象。 Multicast group object to update. |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · Delete
接口名称： api.MulticastGroupService/Delete
功能： 删除 对应资源。Delete the multicast-group with the given ID.
请求： api.DeleteMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 Multicast group iD. |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · List
接口名称： api.MulticastGroupService/List
功能： 列出 对应资源。List the available multicast groups.
请求： api.ListMulticastGroupsRequest；返回： api.ListMulticastGroupsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of multicast groups to return in the result-set. If not set, it will be treated as 0, and the response will only return the total_count. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set (for pagination). |
search | string | 按业务校验 | 搜索关键字。 If set, the given string will be used to search on name. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID to list the multicast groups for. This is mandatory unless tenant_id is set. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (optional, HEX encoded EUI64). |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID to list the multicast groups for. This is mandatory unless application_id is set. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 Total number of multicast groups. |
result | repeated api.MulticastGroupListItem | 按业务校验 | 结果列表或结果内容。 Result-test. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · AddDevice
接口名称： api.MulticastGroupService/AddDevice
功能： 添加组播终端成员。Add a device to the multicast group.
请求： api.AddDeviceToMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (HEX encoded). |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · RemoveDevice
接口名称： api.MulticastGroupService/RemoveDevice
功能： 移除组播终端成员。Remove a device from the multicast group.
请求： api.RemoveDeviceFromMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (HEX encoded). |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · AddGateway
接口名称： api.MulticastGroupService/AddGateway
功能： 添加组播发射网关。Add a gateway to the multicast group.
请求： api.AddGatewayToMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (HEX encoded). |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · RemoveGateway
接口名称： api.MulticastGroupService/RemoveGateway
功能： 移除组播发射网关。Remove a gateway from the multicast group.
请求： api.RemoveGatewayFromMulticastGroupRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (HEX encoded). |
返回值
无字段。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · Enqueue
接口名称： api.MulticastGroupService/Enqueue
功能： 将下行加入队列。Add the given item to the multicast group queue.
请求： api.EnqueueMulticastGroupQueueItemRequest；返回： api.EnqueueMulticastGroupQueueItemResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
queue_item | api.MulticastGroupQueueItem | 按业务校验 | 待加入的下行条目。 Multicast queue-item to enqueue. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
f_cnt | uint32 | 按业务校验 | 帧计数。 Frame-counter of the enqueued payload. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · FlushQueue
接口名称： api.MulticastGroupService/FlushQueue
功能： 清空待发队列。Flush the queue for the given multicast group.
请求： api.FlushMulticastGroupQueueRequest；返回： google.protobuf.Empty（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
返回值
无字段。
操作影响
此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
multicast_group · ListQueue
接口名称： api.MulticastGroupService/ListQueue
功能： 列出组播下行队列。List the items in the multicast group queue.
请求： api.ListMulticastGroupQueueRequest；返回： api.ListMulticastGroupQueueResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
items | repeated api.MulticastGroupQueueItem | 按业务校验 | 消息定义未补充字段说明。 |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套字段的完整结构见 multicast_group 消息结构。
订阅与区域
internal · StreamGatewayFrames
接口名称： api.InternalService/StreamGatewayFrames
功能： 持续订阅网关无线帧。Stream frame for the given Gateway ID.
请求： api.StreamGatewayFramesRequest；返回： api.LogItem（服务端流：持续返回多条消息）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
time | google.protobuf.Timestamp | 按业务校验 | 时间。 Timestamp. |
description | string | 按业务校验 | 描述。 Message. |
body | string | 按业务校验 | Body. |
properties | map<string, string> | 按业务校验 | Properties. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
internal · StreamDeviceFrames
接口名称： api.InternalService/StreamDeviceFrames
功能： 持续订阅终端无线帧。Stream frames for the given Device EUI.
请求： api.StreamDeviceFramesRequest；返回： api.LogItem（服务端流：持续返回多条消息）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
time | google.protobuf.Timestamp | 按业务校验 | 时间。 Timestamp. |
description | string | 按业务校验 | 描述。 Message. |
body | string | 按业务校验 | Body. |
properties | map<string, string> | 按业务校验 | Properties. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
internal · StreamDeviceEvents
接口名称： api.InternalService/StreamDeviceEvents
功能： 持续订阅终端应用事件。Stream events for the given Device EUI.
请求： api.StreamDeviceEventsRequest；返回： api.LogItem（服务端流：持续返回多条消息）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
time | google.protobuf.Timestamp | 按业务校验 | 时间。 Timestamp. |
description | string | 按业务校验 | 描述。 Message. |
body | string | 按业务校验 | Body. |
properties | map<string, string> | 按业务校验 | Properties. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
internal · StreamRuntimeStatus
接口名称： api.InternalService/StreamRuntimeStatus
功能： 持续订阅运行状态变化。Stream runtime status changes for devices and gateways in a tenant.
请求： api.StreamRuntimeStatusRequest；返回： api.RuntimeStatusEvent（服务端流：持续返回多条消息）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID. |
application_id | string | 按业务校验 | 应用 UUID。 Optional application ID filter for devices. |
include_devices | bool | 按业务校验 | Include device status events. |
include_gateways | bool | 按业务校验 | Include gateway status events. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
resource_type | string | 按业务校验 | Resource type: device or gateway. |
id | string | 按业务校验 | 资源 ID。 Device EUI or Gateway ID. |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID, only set for devices. |
state | string | 按业务校验 | State: online, offline, never-seen, or disabled. |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 Last seen timestamp. |
next_offline_at | google.protobuf.Timestamp | 按业务校验 | Timestamp at which the resource should be considered offline. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
internal · ListRegions
接口名称： api.InternalService/ListRegions
功能： 列出 Regions。ListRegions lists the available (configured) regions.
请求： google.protobuf.Empty；返回： api.ListRegionsResponse（单次响应）。
请求参数
无字段。
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
regions | repeated api.RegionListItem | 按业务校验 | Configured regions. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
internal · GetRegion
接口名称： api.InternalService/GetRegion
功能： 查询 Region。GetRegion returns the region details for the given region.
请求： api.GetRegionRequest；返回： api.GetRegionResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 Region ID. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
region | common.Region {EU868=0, US915=2, CN779=3, EU433=4, AU915=5, CN470=6, AS923=7, AS923_2=12, AS923_3=13, AS923_4=14, KR920=8, IN865=9, RU864=10, ISM2400=11} | 按业务校验 | 区域枚举。 Region. |
user_info | string | 按业务校验 | User information. |
uplink_channels | repeated api.RegionChannel | 按业务校验 | Uplink channels. |
rx1_delay | uint32 | 按业务校验 | RX1 delay. |
rx1_dr_offset | uint32 | 按业务校验 | RX1 data-rate offset. |
rx2_dr | uint32 | 按业务校验 | RX2 DR. |
rx2_frequency | uint32 | 按业务校验 | RX2 frequency. |
class_b_ping_slot_dr | uint32 | 按业务校验 | Class-B ping-slot DR. |
class_b_ping_slot_frequency | uint32 | 按业务校验 | Class-B ping-slot frequency. |
description | string | 按业务校验 | 描述。 Region description. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套字段的完整结构见 internal 消息结构。
跨应用与历史
alinkwise · ListTenantDevices
接口名称： api.AlinkwiseService/ListTenantDevices
功能： 列出 TenantDevices。ListTenantDevices returns a tenant-level device list with server-side filtering, sorting, and pagination.
请求： api.ListTenantDevicesRequest；返回： api.ListTenantDevicesResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of devices to return in the result-set. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set. |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID (UUID) to filter devices on. |
application_id | string | 按业务校验 | 应用 UUID。 Optional application ID (UUID). |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 Optional device-profile ID (UUID). |
search | string | 按业务校验 | 搜索关键字。 Optional search over device, application, and device-profile name. |
online_state | api.ListTenantDevicesRequest.OnlineState {ALL=0, ONLINE=1, OFFLINE=2, NEVER_SEEN=3, DISABLED=4} | 按业务校验 | Optional online-state filter. |
order_by | api.ListTenantDevicesRequest.OrderBy {NAME=0, DEV_EUI=1, LAST_SEEN_AT=2, DEVICE_PROFILE_NAME=3, APPLICATION_NAME=4, CREATED_AT=5, UPDATED_AT=6} | 按业务校验 | Sorting field. |
order_by_desc | bool | 按业务校验 | Sorting direction. |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 Tags to filter devices on. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 |
result | repeated api.TenantDeviceListItem | 按业务校验 | 结果列表或结果内容。 |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
alinkwise · ListDeviceUplinkHistory
接口名称： api.AlinkwiseService/ListDeviceUplinkHistory
功能： 列出 DeviceUplinkHistory。ListDeviceUplinkHistory returns persisted uplink events for one device.
请求： api.ListDeviceUplinkHistoryRequest；返回： api.ListDeviceUplinkHistoryResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | uint32 | 按业务校验 | 本次最多返回条数。 Max number of uplink events to return. |
offset | uint32 | 按业务校验 | 分页起始偏移。 Offset in the result-set. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
search | string | 按业务校验 | 搜索关键字。 Optional search over DevAddr, FCnt, FPort, payload hex, object JSON, and rx_info JSON. |
f_port | uint32 | 按业务校验 | 应用端口。 Optional FPort filter. Only used when has_f_port is true. |
has_f_port | bool | 按业务校验 | Whether f_port should be applied. |
event_type | string | 按业务校验 | Optional event type filter: up, join, ack, txack, log, status, location, integration. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
total_count | uint32 | 按业务校验 | 符合条件的总条数。 |
result | repeated api.DeviceUplinkHistoryItem | 按业务校验 | 结果列表或结果内容。 |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
alinkwise · GetDevicePacketLoss
接口名称： api.AlinkwiseService/GetDevicePacketLoss
功能： 查询 DevicePacketLoss。GetDevicePacketLoss returns packet-loss statistics calculated from uplink frame-counter gaps in persisted integration history.
请求： api.GetDevicePacketLossRequest；返回： api.GetDevicePacketLossResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
received_uplinks | uint32 | 按业务校验 | Uplinks received by the server in the selected interval. |
missing_uplinks | uint32 | 按业务校验 | Missing uplinks inferred from positive FCnt gaps. |
expected_uplinks | uint32 | 按业务校验 | received_uplinks + missing_uplinks. |
loss_rate_basis_points | uint32 | 按业务校验 | Loss rate in basis points. 1234 means 12.34%. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
alinkwise · GetDeviceHistoryLinkMetrics
接口名称： api.AlinkwiseService/GetDeviceHistoryLinkMetrics
功能： 查询 DeviceHistoryLinkMetrics。GetDeviceHistoryLinkMetrics returns link metrics aggregated from persisted PostgreSQL integration history.
请求： api.GetDeviceHistoryLinkMetricsRequest；返回： api.GetDeviceHistoryLinkMetricsResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
start | google.protobuf.Timestamp | 按业务校验 | 起始时间。 Interval start timestamp. |
end | google.protobuf.Timestamp | 按业务校验 | 结束时间。 Interval end timestamp. |
aggregation | common.Aggregation {HOUR=0, DAY=1, MONTH=2, MINUTE=3} | 按业务校验 | 聚合粒度。 Aggregation. |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
metrics_json | string | 按业务校验 | JSON encoded DeviceLinkMetricsSummary-compatible payload. |
device_status_json | string | 按业务校验 | JSON encoded latest DeviceStatus-compatible payload from history. |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
alinkwise · ExecuteGatewayRemoteCommand
接口名称： api.AlinkwiseService/ExecuteGatewayRemoteCommand
功能： 执行 GatewayRemoteCommand。ExecuteGatewayRemoteCommand sends a limited gateway-manager remote command.
请求： api.ExecuteGatewayRemoteCommandRequest；返回： api.ExecuteGatewayRemoteCommandResponse（单次响应）。
请求参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 |
command | string | 按业务校验 | 命令名称。 |
environment_json | string | 按业务校验 | 环境参数 JSON 字符串。 |
body_json | string | 按业务校验 | 命令体 JSON 字符串。 |
返回值
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
result_json | string | 按业务校验 | 消息定义未补充字段说明。 |
错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。
嵌套字段的完整结构见 alinkwise 消息结构。
嵌套消息结构
以下对象可直接与上方请求表配合填写，无需切换到平台管理文档。
api.Device
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
name | string | 按业务校验 | 名称。 Name. |
description | string | 按业务校验 | 描述。 Description. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID (UUID). |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 Device-profile ID (UUID). |
skip_fcnt_check | bool | 按业务校验 | 是否跳过帧计数检查。 Skip frame-counter checks (this is insecure, but could be helpful for debugging). |
is_disabled | bool | 按业务校验 | 是否禁用。 Device is disabled. |
variables | map<string, string> | 按业务校验 | 变量映射。 Variables (user defined). These variables can be used together with integrations to store tokens / secrets that must be configured per device. These variables are not exposed in the event payloads. |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 Tags (user defined). These tags can be used to add additional information to the device. These tags are exposed in all the integration events. |
join_eui | string | 按业务校验 | JoinEUI。 JoinEUI (optional, EUI64). This field will be automatically set / updated on OTAA. However, in some cases it must be pre-configured. For example to allow OTAA using a Relay. In this case the Relay needs to know the JoinEUI + DevEUI combinations of the devices for which it needs to forward uplinks. |
api.Device.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.Device.VariablesEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.DeviceActivation
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
dev_addr | string | 按业务校验 | 会话短地址。 Device address (HEX encoded). |
app_s_key | string | 按业务校验 | 应用会话密钥。 Application session key (HEX encoded). |
nwk_s_enc_key | string | 按业务校验 | 网络会话加密密钥。 Network session encryption key (HEX encoded). Note: For LoRaWAN 1.0.x devices, set this to the NwkSKey. |
s_nwk_s_int_key | string | 按业务校验 | 服务网络会话完整性密钥。 Serving network session integrity key (HEX encoded). Note: For LoRaWAN 1.0.x devices, set this to the NwkSKey. |
f_nwk_s_int_key | string | 按业务校验 | 转发网络会话完整性密钥。 Forwarding network session integrity key (HEX encoded). Note: For LoRaWAN 1.0.x devices, set this to the NwkSKey. |
f_cnt_up | uint32 | 按业务校验 | 上行帧计数。 Uplink frame-counter. |
n_f_cnt_down | uint32 | 按业务校验 | 网络下行帧计数。 Downlink network frame-counter. |
a_f_cnt_down | uint32 | 按业务校验 | 应用下行帧计数。 Downlink application frame-counter. |
api.DeviceKeys
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
nwk_key | string | 按业务校验 | 网络根密钥。 Network root key (128 bit). Note: For LoRaWAN 1.0.x, use this field for the LoRaWAN 1.0.x 'AppKey`! |
app_key | string | 按业务校验 | 应用根密钥。 Application root key (128 bit). Note: This field only needs to be set for LoRaWAN 1.1.x devices! |
gen_app_key | string | 按业务校验 | Gen App Key (128 bit). Note: This field only needs to be set for LoRaWAN 1.0.x devices that implement TS005 (remote multicast setup). |
api.DeviceListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 DevEUI (EUI64). |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 Last seen at timestamp. |
name | string | 按业务校验 | 名称。 Name. |
description | string | 按业务校验 | 描述。 Description. |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 Device-profile ID (UUID). |
device_profile_name | string | 按业务校验 | Device-profile name. |
device_status | api.DeviceStatus | 按业务校验 | 终端状态。 Device status. |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 Device tags. |
api.DeviceListItem.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.DeviceQueueItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID (UUID). This is automatically generated on enqueue. |
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 Device EUI (EUI64). |
confirmed | bool | 按业务校验 | 是否使用确认下行。 Confirmed. |
f_port | uint32 | 按业务校验 | 应用端口。 FPort (must be > 0). On enqueue and if using a JavaScript codec, this value might be automatically set by the codec function. |
data | bytes | 按业务校验 | 原始负载字节，JSON 中为 Base64。 Data. Or use the json_object field when a codec has been configured. |
object | google.protobuf.Struct | 按业务校验 | 业务对象，需 codec 处理。 Only use this when a codec has been configured that can encode this object to bytes. |
is_pending | bool | 按业务校验 | 是否处于等待确认状态。 Is pending. This is set by ChirpStack to true when the downlink is pending (e.g. it has been sent, but a confirmation is still pending). |
f_cnt_down | uint32 | 按业务校验 | Downlink frame-counter. Do not set this for plain-text data payloads. It will be automatically set by ChirpStack when the payload has been sent as downlink. |
is_encrypted | bool | 按业务校验 | 负载是否已经加密。 Is encrypted. This must be set to true if the end-application has already encrypted the data payload. In this case, the f_cnt_down field must be set to the corresponding frame-counter which has been used during the encryption. |
expires_at | google.protobuf.Timestamp | 按业务校验 | 过期时间。 Expires at (optional). Expired queue-items will be automatically removed from the queue. |
api.DeviceState
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 按业务校验 | 名称。 Name. |
value | string | 按业务校验 | Value. |
api.DeviceStatus
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
margin | int32 | 按业务校验 | The device margin status -32..32: The demodulation SNR ration in dB |
external_power_source | bool | 按业务校验 | 是否外接电源。 Device is connected to an external power source. |
battery_level | float | 按业务校验 | 电池状态。 Device battery level as a percentage. -1 when the battery level is not available. |
api.GetDeviceMetricsResponse.MetricsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | common.Metric | 按业务校验 | 消息定义未补充字段说明。 |
api.GetDeviceMetricsResponse.StatesEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | api.DeviceState | 按业务校验 | 消息定义未补充字段说明。 |
api.ListDevicesRequest.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
common.JoinServerContext
Join-Server context.
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_key_id | string | 按业务校验 | Session-key ID. |
app_s_key | common.KeyEnvelope | 按业务校验 | 应用会话密钥。 AppSKey envelope. |
common.KeyEnvelope
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
kek_label | string | 按业务校验 | KEK label. |
aes_key | bytes | 按业务校验 | AES key (when the kek_label is set, this value must first be decrypted). |
common.Metric
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 按业务校验 | 名称。 Name. |
timestamps | repeated google.protobuf.Timestamp | 按业务校验 | Timestamps. |
datasets | repeated common.MetricDataset | 按业务校验 | Datasets. |
kind | common.MetricKind {COUNTER=0, ABSOLUTE=1, GAUGE=2} | 按业务校验 | Kind. |
common.MetricDataset
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
label | string | 按业务校验 | Label. |
data | repeated float | 按业务校验 | 数据序列。 Data. Each value index corresponds with the same timestamp index of the Metric. |
api.Gateway
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
name | string | 按业务校验 | 名称。 Name. |
description | string | 按业务校验 | 描述。 Description. |
location | common.Location | 按业务校验 | 位置。 Gateway location. |
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID (UUID). |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 Tags. |
metadata | map<string, string> | 按业务校验 | Metadata (provided by the gateway). |
stats_interval | uint32 | 按业务校验 | 状态上报周期。 Stats interval (seconds). This defines the expected interval in which the gateway sends its statistics. |
api.Gateway.MetadataEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.Gateway.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.GatewayListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
tenant_id | string | 按业务校验 | 租户 UUID。 Tenant ID. |
gateway_id | string | 按业务校验 | 网关 EUI。 Gateway ID (EUI64). |
name | string | 按业务校验 | 名称。 Name. |
description | string | 按业务校验 | 描述。 Description. |
location | common.Location | 按业务校验 | 位置。 Location. |
properties | map<string, string> | 按业务校验 | Gateway properties. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 Last seen at timestamp. |
state | api.GatewayState {NEVER_SEEN=0, ONLINE=1, OFFLINE=2} | 按业务校验 | Gateway state. Please note that the state of the gateway is driven by the stats packages that are sent by the gateway. |
api.GatewayListItem.PropertiesEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
common.Location
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
latitude | double | 按业务校验 | 纬度。 Latitude. |
longitude | double | 按业务校验 | 经度。 Longitude. |
altitude | double | 按业务校验 | 海拔。 Altitude. |
source | common.LocationSource {UNKNOWN=0, GPS=1, CONFIG=2, GEO_RESOLVER_TDOA=3, GEO_RESOLVER_RSSI=4, GEO_RESOLVER_GNSS=5, GEO_RESOLVER_WIFI=6} | 按业务校验 | Location source. |
accuracy | float | 按业务校验 | Accuracy. |
api.MulticastGroup
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID (UUID). This will be generated automatically on create. |
name | string | 按业务校验 | 名称。 Name. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID. After creation, this can not be updated. |
region | common.Region {EU868=0, US915=2, CN779=3, EU433=4, AU915=5, CN470=6, AS923=7, AS923_2=12, AS923_3=13, AS923_4=14, KR920=8, IN865=9, RU864=10, ISM2400=11} | 按业务校验 | 区域枚举。 Region. |
mc_addr | string | 按业务校验 | 组播地址。 Multicast address (HEX encoded DevAddr). |
mc_nwk_s_key | string | 按业务校验 | 组播网络会话密钥。 Multicast network session key (HEX encoded AES128 key). |
mc_app_s_key | string | 按业务校验 | 组播应用会话密钥。 Multicast application session key (HEX encoded AES128 key). |
f_cnt | uint32 | 按业务校验 | 帧计数。 Frame-counter. |
group_type | api.MulticastGroupType {CLASS_C=0, CLASS_B=1} | 按业务校验 | 组播类型。 Multicast group type. |
dr | uint32 | 按业务校验 | 数据率索引。 Data-rate. |
frequency | uint32 | 按业务校验 | 频率。 Frequency (Hz). |
class_b_ping_slot_periodicity | uint32 | 按业务校验 | Class-B ping-slot periodicity (only for Class-B). Valid options are: 0 - 7. Number of ping-slots per beacon-period: pingNb = 2^(7-periodicity) Periodicity: 0 = 128 ping-slots per beacon period = ~ every 1 sec Periodicity: 7 = 1 ping-slot per beacon period = ~ every 128 sec |
class_c_scheduling_type | api.MulticastGroupSchedulingType {DELAY=0, GPS_TIME=1} | 按业务校验 | Class C 调度类型。 Scheduling type (only for Class-C). |
api.MulticastGroupListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 Created at timestamp. |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 Last update timestamp. |
name | string | 按业务校验 | 名称。 Name. |
region | common.Region {EU868=0, US915=2, CN779=3, EU433=4, AU915=5, CN470=6, AS923=7, AS923_2=12, AS923_3=13, AS923_4=14, KR920=8, IN865=9, RU864=10, ISM2400=11} | 按业务校验 | 区域枚举。 Region. |
group_type | api.MulticastGroupType {CLASS_C=0, CLASS_B=1} | 按业务校验 | 组播类型。 Multicast group type. |
application_id | string | 按业务校验 | 应用 UUID。 Application ID. |
application_name | string | 按业务校验 | Application name. |
api.MulticastGroupQueueItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
multicast_group_id | string | 按业务校验 | 组播组 UUID。 Multicast group ID. |
f_cnt | uint32 | 按业务校验 | 帧计数。 Downlink frame-counter. This will be automatically set on enqueue. |
f_port | uint32 | 按业务校验 | 应用端口。 FPort (must be > 0). |
data | bytes | 按业务校验 | 原始负载字节，JSON 中为 Base64。 Payload. |
expires_at | google.protobuf.Timestamp | 按业务校验 | 过期时间。 Expires at (optional). Expired queue-items will be automatically removed from the queue. |
api.LogItem.PropertiesEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.RegionChannel
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
frequency | uint32 | 按业务校验 | 频率。 Frequency (Hz). |
data_rates | repeated uint32 | 按业务校验 | Data-rates. |
api.RegionListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 按业务校验 | 资源 ID。 ID. |
region | common.Region {EU868=0, US915=2, CN779=3, EU433=4, AU915=5, CN470=6, AS923=7, AS923_2=12, AS923_3=13, AS923_4=14, KR920=8, IN865=9, RU864=10, ISM2400=11} | 按业务校验 | 区域枚举。 Region. |
description | string | 按业务校验 | 描述。 Description. |
api.DeviceUplinkHistoryItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
deduplication_id | string | 按业务校验 | 消息定义未补充字段说明。 |
event_type | string | 按业务校验 | 消息定义未补充字段说明。 |
time | string | 按业务校验 | 时间。 |
dev_addr | string | 按业务校验 | 会话短地址。 |
dr | uint32 | 按业务校验 | 数据率索引。 |
f_cnt | string | 按业务校验 | 帧计数。 |
f_port | uint32 | 按业务校验 | 应用端口。 |
confirmed | bool | 按业务校验 | 是否使用确认下行。 |
data_hex | string | 按业务校验 | 消息定义未补充字段说明。 |
object_json | string | 按业务校验 | 消息定义未补充字段说明。 |
rx_info_json | string | 按业务校验 | 消息定义未补充字段说明。 |
tx_info_json | string | 按业务校验 | 消息定义未补充字段说明。 |
tags_json | string | 按业务校验 | 消息定义未补充字段说明。 |
summary_json | string | 按业务校验 | 消息定义未补充字段说明。 |
api.ListTenantDevicesRequest.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |
api.TenantDeviceListItem
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
dev_eui | string | 按业务校验 | 终端完整 DevEUI。 |
name | string | 按业务校验 | 名称。 |
description | string | 按业务校验 | 描述。 |
application_id | string | 按业务校验 | 应用 UUID。 |
application_name | string | 按业务校验 | 消息定义未补充字段说明。 |
device_profile_id | string | 按业务校验 | 终端模版 UUID。 |
device_profile_name | string | 按业务校验 | 消息定义未补充字段说明。 |
created_at | google.protobuf.Timestamp | 按业务校验 | 创建时间。 |
updated_at | google.protobuf.Timestamp | 按业务校验 | 最后更新时间。 |
last_seen_at | google.protobuf.Timestamp | 按业务校验 | 最后上报时间。 |
device_status | api.DeviceStatus | 按业务校验 | 终端状态。 |
tags | map<string, string> | 按业务校验 | 自定义字符串标签。 |
join_eui | string | 按业务校验 | JoinEUI。 |
is_disabled | bool | 按业务校验 | 是否禁用。 |
is_active | bool | 按业务校验 | 是否启用。 |
class_enabled | common.DeviceClass {CLASS_A=0, CLASS_B=1, CLASS_C=2} | 按业务校验 | 已启用的 Class。 |
api.TenantDeviceListItem.TagsEntry
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 按业务校验 | 消息定义未补充字段说明。 |
value | string | 按业务校验 | 消息定义未补充字段说明。 |