网关 API

本页列出当前版本的完整方法及字段。方法通过 gRPC / gRPC-Web 调用；REST 注解不表示已部署 REST Gateway。

“必填：按业务校验”表示 proto3 未声明 required，不代表留空一定可用。UUID、EUI、权限、资源存在性与字段组合由服务端校验。嵌套结构详见页末消息结构。

调用方式、鉴权与错误处理

GatewayService

Create

接口名称： api.GatewayService/Create

功能： 创建 对应资源。Create creates the given gateway.

请求： api.CreateGatewayRequest；返回： google.protobuf.Empty（单次响应）。

请求参数

名称	类型	必填	说明
gateway	api.Gateway	按业务校验	网关对象。 Gateway object.

返回值

无字段。

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

Update

接口名称： api.GatewayService/Update

功能： 更新 对应资源。Update updates the given gateway.

请求： api.UpdateGatewayRequest；返回： google.protobuf.Empty（单次响应）。

请求参数

名称	类型	必填	说明
gateway	api.Gateway	按业务校验	网关对象。 Gateway object.

返回值

无字段。

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

GenerateClientCertificate

接口名称： api.GatewayService/GenerateClientCertificate

功能： 生成 ClientCertificate。Generate client-certificate for the gateway.

请求： api.GenerateGatewayClientCertificateRequest；返回： api.GenerateGatewayClientCertificateResponse（单次响应）。

请求参数

名称	类型	必填	说明
gateway_id	string	按业务校验	网关 EUI。 Gateway ID (EUI64).

返回值

名称	类型	必填	说明
tls_cert	string	按业务校验	TLS 证书。 TLS certificate.
tls_key	string	按业务校验	TLS 私钥。 TLS key.
ca_cert	string	按业务校验	CA 证书。 CA certificate.
expires_at	google.protobuf.Timestamp	按业务校验	过期时间。 Expires at defines the expiration date of the certificate.

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

GetRelayGateway

接口名称： api.GatewayService/GetRelayGateway

功能： 查询 RelayGateway。Get the given Relay Gateway.

请求： api.GetRelayGatewayRequest；返回： api.GetRelayGatewayResponse（单次响应）。

请求参数

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID (UUID).
relay_id	string	按业务校验	Relay ID (4 byte HEX).

返回值

名称	类型	必填	说明
relay_gateway	api.RelayGateway	按业务校验	Relay 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 状态；本页不将通用状态码冒充每个方法的固定错误集合。

ListRelayGateways

接口名称： api.GatewayService/ListRelayGateways

功能： 列出 RelayGateways。List the detected Relay Gateways.

请求： api.ListRelayGatewaysRequest；返回： api.ListRelayGatewaysResponse（单次响应）。

请求参数

名称	类型	必填	说明
limit	uint32	按业务校验	本次最多返回条数。 Max number of relay-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).
tenant_id	string	按业务校验	租户 UUID。 Tenant ID (UUID) to filter relay-gateways on. To list all relay-gateways as a global admin user, this field can be left blank.

返回值

名称	类型	必填	说明
total_count	uint32	按业务校验	符合条件的总条数。 Total number of relay-gateways.
result	repeated api.RelayGatewayListItem	按业务校验	结果列表或结果内容。 Result-set.

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

UpdateRelayGateway

接口名称： api.GatewayService/UpdateRelayGateway

功能： 更新 RelayGateway。Update the given Relay Gateway.

请求： api.UpdateRelayGatewayRequest；返回： google.protobuf.Empty（单次响应）。

请求参数

名称	类型	必填	说明
relay_gateway	api.RelayGateway	按业务校验	Relay Gateway object.

返回值

无字段。

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

DeleteRelayGateway

接口名称： api.GatewayService/DeleteRelayGateway

功能： 删除 RelayGateway。Delete the given Relay Gateway.

请求： api.DeleteRelayGatewayRequest；返回： google.protobuf.Empty（单次响应）。

请求参数

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID.
relay_id	string	按业务校验	Relay ID (4 byte HEX).

返回值

无字段。

操作影响

此方法会删除、清空或重置对应资源/状态。调用前核对目标 ID；请勿通过重试重复执行有副作用的操作。

错误处理：按 统一错误说明 检查 gRPC 状态；本页不将通用状态码冒充每个方法的固定错误集合。

嵌套消息结构

api.CreateGatewayRequest

名称	类型	必填	说明
gateway	api.Gateway	按业务校验	网关对象。 Gateway object.

api.DeleteGatewayRequest

名称	类型	必填	说明
gateway_id	string	按业务校验	网关 EUI。 Gateway ID (EUI64).

api.DeleteRelayGatewayRequest

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID.
relay_id	string	按业务校验	Relay ID (4 byte HEX).

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	按业务校验	消息定义未补充字段说明。

api.GenerateGatewayClientCertificateRequest

名称	类型	必填	说明
gateway_id	string	按业务校验	网关 EUI。 Gateway ID (EUI64).

api.GenerateGatewayClientCertificateResponse

名称	类型	必填	说明
tls_cert	string	按业务校验	TLS 证书。 TLS certificate.
tls_key	string	按业务校验	TLS 私钥。 TLS key.
ca_cert	string	按业务校验	CA 证书。 CA certificate.
expires_at	google.protobuf.Timestamp	按业务校验	过期时间。 Expires at defines the expiration date of the certificate.

api.GetGatewayDutyCycleMetricsRequest

名称	类型	必填	说明
gateway_id	string	按业务校验	网关 EUI。 Gateway ID (EUI64).
start	google.protobuf.Timestamp	按业务校验	起始时间。 Interval start timestamp.
end	google.protobuf.Timestamp	按业务校验	结束时间。 Interval end timestamp.

api.GetGatewayDutyCycleMetricsResponse

名称	类型	必填	说明
max_load_percentage	common.Metric	按业务校验	Percentage relative to max load.
window_percentage	common.Metric	按业务校验	Percentage relative to tracking window.

api.GetGatewayMetricsRequest

名称	类型	必填	说明
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.

api.GetGatewayMetricsResponse

名称	类型	必填	说明
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.

api.GetGatewayRequest

名称	类型	必填	说明
gateway_id	string	按业务校验	网关 EUI。 Gateway ID (EUI64).

api.GetGatewayResponse

名称	类型	必填	说明
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.

api.GetRelayGatewayRequest

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID (UUID).
relay_id	string	按业务校验	Relay ID (4 byte HEX).

api.GetRelayGatewayResponse

名称	类型	必填	说明
relay_gateway	api.RelayGateway	按业务校验	Relay 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.

api.ListGatewaysRequest

名称	类型	必填	说明
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).

api.ListGatewaysResponse

名称	类型	必填	说明
total_count	uint32	按业务校验	符合条件的总条数。 Total number of gateways.
result	repeated api.GatewayListItem	按业务校验	结果列表或结果内容。 Result-set.

api.ListRelayGatewaysRequest

名称	类型	必填	说明
limit	uint32	按业务校验	本次最多返回条数。 Max number of relay-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).
tenant_id	string	按业务校验	租户 UUID。 Tenant ID (UUID) to filter relay-gateways on. To list all relay-gateways as a global admin user, this field can be left blank.

api.ListRelayGatewaysResponse

名称	类型	必填	说明
total_count	uint32	按业务校验	符合条件的总条数。 Total number of relay-gateways.
result	repeated api.RelayGatewayListItem	按业务校验	结果列表或结果内容。 Result-set.

api.RelayGateway

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID.
relay_id	string	按业务校验	Relay ID (4 byte HEX).
name	string	按业务校验	名称。 Name.
description	string	按业务校验	描述。 Description.
stats_interval	uint32	按业务校验	状态上报周期。 Stats interval (seconds). This defines the expected interval in which the gateway sends its statistics.
region_config_id	string	按业务校验	区域配置 ID。 Region configuration ID.

api.RelayGatewayListItem

名称	类型	必填	说明
tenant_id	string	按业务校验	租户 UUID。 Tenant ID.
relay_id	string	按业务校验	Relay ID (4 byte HEX).
name	string	按业务校验	名称。 Name.
description	string	按业务校验	描述。 Description.
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 relay is driven by the last received stats packet sent by the relay-gateway.
region_config_id	string	按业务校验	区域配置 ID。 Region configuration ID.

api.UpdateGatewayRequest

名称	类型	必填	说明
gateway	api.Gateway	按业务校验	网关对象。 Gateway object.

api.UpdateRelayGatewayRequest

名称	类型	必填	说明
relay_gateway	api.RelayGateway	按业务校验	Relay Gateway object.

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.

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.