mirror of
https://gitee.com/pnoker/iot-dc3.git
synced 2026-08-30 17:19:58 +08:00
docs(api): correct gRPC RPC names, import paths, and missing services
Align the four api READMEs with the actual protos: Select*->Get*/List* per the CRUD verb convention, fix api/common->api/center import paths for auth/data, drop the fabricated manager SelectByServiceName RPC, and document the previously omitted auth/data/manager services.
This commit is contained in:
pnoker
@@ -21,7 +21,7 @@ Defines tenant-related RPC calls and data structures.
|
||||
|
||||
**Service**: `TenantApi`
|
||||
|
||||
- `SelectByCode` - Query tenant information by tenant code
|
||||
- `GetByCode` - Query tenant information by tenant code
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -48,8 +48,8 @@ Defines user-related RPC calls and data structures.
|
||||
|
||||
**Service**: `UserApi`
|
||||
|
||||
- `SelectById` - Query user information by user ID
|
||||
- `SelectByPrincipalId` - Query user information by principal ID
|
||||
- `GetById` - Query user information by user ID
|
||||
- `GetByPrincipalId` - Query user information by principal ID
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -71,6 +71,34 @@ Defines local credential lookup RPC calls and data structures.
|
||||
- `GrpcRLocalCredentialDTO` - Response wrapper containing local credential information
|
||||
- `GrpcLocalCredentialDTO` - Local credential data structure (login name, principal ID)
|
||||
|
||||
### permission.proto
|
||||
|
||||
Defines permission lookup RPC calls for RBAC.
|
||||
|
||||
**Service**: `PermissionApi`
|
||||
|
||||
- `ListPermissionCodes` - List the permission codes granted to a principal
|
||||
|
||||
### resource_registry.proto
|
||||
|
||||
Defines resource registry synchronization RPC calls.
|
||||
|
||||
**Service**: `ResourceRegistryApi`
|
||||
|
||||
- `Sync` - Synchronize API/menu resource definitions into the registry
|
||||
|
||||
### mcp_runtime.proto
|
||||
|
||||
Defines MCP (Model Context Protocol) runtime RPC calls for AI tool integration.
|
||||
|
||||
**Service**: `McpRuntimeApi`
|
||||
|
||||
- `Introspect` - Introspect an MCP connection
|
||||
- `ListTools` - List the tools exposed by an MCP connection
|
||||
- `ResolveTool` - Resolve a tool definition by name
|
||||
- `AuthorizeToolCall` - Authorize an MCP tool invocation
|
||||
- `Audit` - Record an MCP tool-call audit entry
|
||||
|
||||
## Dependencies
|
||||
|
||||
This module depends on common proto definitions:
|
||||
@@ -94,10 +122,10 @@ This module depends on common proto definitions:
|
||||
### 2. Import Proto Files
|
||||
|
||||
```protobuf
|
||||
import "api/common/auth/tenant.proto";
|
||||
import "api/common/auth/token.proto";
|
||||
import "api/common/auth/user.proto";
|
||||
import "api/common/auth/local_credential.proto";
|
||||
import "api/center/auth/tenant.proto";
|
||||
import "api/center/auth/token.proto";
|
||||
import "api/center/auth/user.proto";
|
||||
import "api/center/auth/local_credential.proto";
|
||||
```
|
||||
|
||||
### 3. Implement Service
|
||||
@@ -105,8 +133,8 @@ import "api/common/auth/local_credential.proto";
|
||||
```java
|
||||
public class TenantServiceImpl extends TenantApiGrpc.TenantApiImplBase {
|
||||
@Override
|
||||
public void selectByCode(GrpcCodeQuery request,
|
||||
StreamObserver<GrpcRTenantDTO> responseObserver) {
|
||||
public void getByCode(GrpcCodeQuery request,
|
||||
StreamObserver<GrpcRTenantDTO> responseObserver) {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
|
||||
@@ -21,7 +21,10 @@ Defines point value query RPC calls and data structures for device data collecti
|
||||
|
||||
**Service**: `PointValueApi`
|
||||
|
||||
- `LastValue` - Query the latest collected value of a device point
|
||||
- `GetLastValue` - Query the latest collected value of a device point
|
||||
- `ListHistoryValues` - Query historical values of a device point
|
||||
- `ReadCommand` - Trigger a read command for a device point
|
||||
- `WriteCommand` - Trigger a write command for a device point
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -29,6 +32,38 @@ Defines point value query RPC calls and data structures for device data collecti
|
||||
- `GrpcRPointValueDTO` - Response wrapper containing point value information
|
||||
- `GrpcPointValueDTO` - Point value data structure
|
||||
|
||||
### event_history.proto
|
||||
|
||||
Defines device event history RPC calls.
|
||||
|
||||
**Service**: `EventHistoryApi`
|
||||
|
||||
- `ReportEvent` - Report a device event
|
||||
- `GetByRecordId` - Query an event history record by record ID
|
||||
- `ListByPage` - Query event history with pagination support
|
||||
|
||||
### command_history.proto
|
||||
|
||||
Defines device command history RPC calls.
|
||||
|
||||
**Service**: `CommandHistoryApi`
|
||||
|
||||
- `CallCommand` - Issue a command to a device
|
||||
- `GetByRecordId` - Query a command history record by record ID
|
||||
- `ListByPage` - Query command history with pagination support
|
||||
|
||||
### status_health.proto
|
||||
|
||||
Defines device/driver status and system health RPC calls.
|
||||
|
||||
**Service**: `StatusHealthApi`
|
||||
|
||||
- `DeviceStatusesByIds` - Query device statuses by device IDs
|
||||
- `DeviceStatusesByProfileId` - Query device statuses by profile ID
|
||||
- `DriverStatusesByIds` - Query driver statuses by driver IDs
|
||||
- `DriverDeviceStatusSummary` - Summarize device statuses under a driver
|
||||
- `SystemHealth` - Query overall system health
|
||||
|
||||
## Data Models
|
||||
|
||||
### Point Value Model
|
||||
@@ -79,7 +114,7 @@ This module depends on common proto definitions:
|
||||
### 2. Import Proto Files
|
||||
|
||||
```protobuf
|
||||
import "api/common/data/point_value.proto";
|
||||
import "api/center/data/point_value.proto";
|
||||
```
|
||||
|
||||
### 3. Implement Service
|
||||
@@ -87,8 +122,8 @@ import "api/common/data/point_value.proto";
|
||||
```java
|
||||
public class PointValueServiceImpl extends PointValueApiGrpc.PointValueApiImplBase {
|
||||
@Override
|
||||
public void lastValue(GrpcPointValueQuery request,
|
||||
StreamObserver<GrpcRPointValueDTO> responseObserver) {
|
||||
public void getLastValue(GrpcPointValueQuery request,
|
||||
StreamObserver<GrpcRPointValueDTO> responseObserver) {
|
||||
// Query latest point value from database
|
||||
// Return GrpcRPointValueDTO with point value data
|
||||
}
|
||||
@@ -106,7 +141,7 @@ GrpcPointValueQuery query = GrpcPointValueQuery.newBuilder()
|
||||
.build();
|
||||
|
||||
// Call service
|
||||
GrpcRPointValueDTO response = pointValueApi.lastValue(query);
|
||||
GrpcRPointValueDTO response = pointValueApi.getLastValue(query);
|
||||
|
||||
// Extract data
|
||||
if(response.
|
||||
@@ -177,7 +212,7 @@ Date collectionTime = new Date(timestamp);
|
||||
|
||||
- **Query Optimization**: Always include tenant_id for proper data isolation
|
||||
- **Caching**: Consider caching recent point values for high-frequency queries
|
||||
- **Time Series Database**: This API typically queries time-series databases (e.g., InfluxDB, TDengine)
|
||||
- **Time Series Store**: This API queries the time-series store through `dc3-common-repository` (PostgreSQL with the TimescaleDB extension)
|
||||
- **Data Volume**: Point value queries can generate high traffic in large-scale deployments
|
||||
|
||||
## Integration Points
|
||||
|
||||
@@ -22,6 +22,7 @@ Defines driver registration RPC calls and data structures.
|
||||
**Service**: `DriverApi`
|
||||
|
||||
- `DriverRegister` - Register a driver instance with the platform (used by drivers on startup)
|
||||
- `GetById` - Query driver registration information by driver ID
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -34,8 +35,8 @@ Defines device-related RPC calls for driver services.
|
||||
|
||||
**Service**: `DeviceApi`
|
||||
|
||||
- `SelectByPage` - Query devices with pagination support
|
||||
- `SelectById` - Query device by device ID
|
||||
- `ListByPage` - Query devices with pagination support
|
||||
- `GetById` - Query device by device ID
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -51,8 +52,8 @@ Defines point-related RPC calls for driver services.
|
||||
|
||||
**Service**: `PointApi`
|
||||
|
||||
- `SelectByPage` - Query points with pagination support
|
||||
- `SelectById` - Query point by point ID
|
||||
- `ListByPage` - Query points with pagination support
|
||||
- `GetById` - Query point by point ID
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
@@ -141,7 +142,7 @@ GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder()
|
||||
.setDriverId(driver.getId())
|
||||
.setDeviceId(deviceId)
|
||||
.build();
|
||||
GrpcRDeviceDTO deviceResponse = deviceApi.selectById(query);
|
||||
GrpcRDeviceDTO deviceResponse = deviceApi.getById(query);
|
||||
// Process device configuration
|
||||
}
|
||||
```
|
||||
@@ -150,7 +151,7 @@ GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder()
|
||||
|
||||
```java
|
||||
// Query device with full configuration
|
||||
GrpcRDeviceAttachDTO deviceAttach = deviceApi.selectById(deviceQuery);
|
||||
GrpcRDeviceAttachDTO deviceAttach = deviceApi.getById(deviceQuery);
|
||||
|
||||
// Extract device information
|
||||
GrpcDeviceDTO device = deviceAttach.getDevice();
|
||||
@@ -171,7 +172,7 @@ GrpcPointQuery pointQuery = GrpcPointQuery.newBuilder()
|
||||
.setPointId(pointId)
|
||||
.build();
|
||||
|
||||
GrpcRPointDTO pointResponse = pointApi.selectById(pointQuery);
|
||||
GrpcRPointDTO pointResponse = pointApi.getById(pointQuery);
|
||||
GrpcPointDTO point = pointResponse.getData();
|
||||
|
||||
// Configure point reading
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
`dc3-api-manager` provides gRPC service definitions for the Manager Center in the IoT DC3 platform. It defines the
|
||||
interfaces used by the Data service and other consumers to query
|
||||
driver, device, and point metadata from the Manager Center.
|
||||
driver, device, point, profile, command, and event metadata from the Manager Center.
|
||||
|
||||
## Module Information
|
||||
|
||||
@@ -21,14 +21,18 @@ Defines driver-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `DriverApi`
|
||||
|
||||
- `SelectByDeviceId` - Query driver information by device ID
|
||||
- `SelectByServiceName` - Query driver information by service name
|
||||
- `ListByPage` - Query drivers with pagination support
|
||||
- `GetByDriverId` - Query driver information by driver ID
|
||||
- `ListByDriverIds` - Query drivers by a list of driver IDs
|
||||
- `GetByDeviceId` - Query driver information by device ID
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
- `GrpcDriverQuery` - Driver query by device ID
|
||||
- `GrpcServiceNameQuery` - Driver query by service name
|
||||
- `GrpcPageDriverQuery` - Paginated driver query request
|
||||
- `GrpcDriverQuery` - Driver query by driver ID / device ID
|
||||
- `GrpcDriverIdsQuery` - Driver query by a list of driver IDs
|
||||
- `GrpcRDriverDTO` - Response wrapper containing driver information
|
||||
- `GrpcRPageDriverDTO` / `GrpcRDriverListDTO` - Paginated / list responses
|
||||
- `GrpcDriverDTO` - Driver data structure (service name, driver type, host, etc.)
|
||||
|
||||
### manager_device.proto
|
||||
@@ -37,12 +41,18 @@ Defines device-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `DeviceApi`
|
||||
|
||||
- `SelectById` - Query device information by device ID
|
||||
- `ListByPage` - Query devices with pagination support
|
||||
- `ListByProfileId` - Query devices by profile ID
|
||||
- `ListByDriverId` - Query devices by driver ID
|
||||
- `GetByDeviceId` - Query device information by device ID
|
||||
- `ListByDeviceIds` - Query devices by a list of device IDs
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
- `GrpcDeviceQuery` - Device query by device ID
|
||||
- `GrpcRDeviceDTO` - Response wrapper containing device information
|
||||
- `GrpcPageDeviceQuery` - Paginated device query request
|
||||
- `GrpcDeviceQuery` - Single device query
|
||||
- `GrpcDeviceIdsQuery` - Device query by a list of device IDs
|
||||
- `GrpcRDeviceDTO` / `GrpcRPageDeviceDTO` / `GrpcRDeviceListDTO` - Single / paginated / list responses
|
||||
|
||||
### manager_point.proto
|
||||
|
||||
@@ -50,12 +60,47 @@ Defines point-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `PointApi`
|
||||
|
||||
- `SelectById` - Query point information by point ID
|
||||
- `ListByPage` - Query points with pagination support
|
||||
- `GetById` - Query point information by point ID
|
||||
- `ListByIds` - Query points by a list of point IDs
|
||||
|
||||
**Key Messages**:
|
||||
|
||||
- `GrpcPointQuery` - Point query by point ID
|
||||
- `GrpcRPointDTO` - Response wrapper containing point information
|
||||
- `GrpcPagePointQuery` - Paginated point query request
|
||||
- `GrpcPointQuery` - Single point query
|
||||
- `GrpcPointIdsQuery` - Point query by a list of point IDs
|
||||
- `GrpcRPointDTO` / `GrpcRPagePointDTO` / `GrpcRPointListDTO` - Single / paginated / list responses
|
||||
|
||||
### manager_command.proto
|
||||
|
||||
Defines command-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `CommandApi`
|
||||
|
||||
- `ListByPage` - Query commands with pagination support
|
||||
- `GetById` - Query command information by command ID
|
||||
- `ListByIds` - Query commands by a list of command IDs
|
||||
|
||||
### manager_event.proto
|
||||
|
||||
Defines event-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `EventApi`
|
||||
|
||||
- `ListByPage` - Query events with pagination support
|
||||
- `GetById` - Query event information by event ID
|
||||
- `ListByIds` - Query events by a list of event IDs
|
||||
|
||||
### manager_profile.proto
|
||||
|
||||
Defines profile-related RPC calls from the manager perspective.
|
||||
|
||||
**Service**: `ProfileApi`
|
||||
|
||||
- `ListByPage` - Query profiles with pagination support
|
||||
- `GetByProfileId` - Query profile information by profile ID
|
||||
- `ListByProfileIds` - Query profiles by a list of profile IDs
|
||||
- `ListByDeviceId` - Query profiles bound to a device
|
||||
|
||||
### manager_query.proto / manager_query_page.proto
|
||||
|
||||
@@ -99,7 +144,7 @@ private PointApiGrpc.PointApiBlockingStub pointApiBlockingStub;
|
||||
GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder()
|
||||
.setDeviceId(deviceId)
|
||||
.build();
|
||||
GrpcRDriverDTO response = driverApiBlockingStub.selectByDeviceId(query);
|
||||
GrpcRDriverDTO response = driverApiBlockingStub.getByDeviceId(query);
|
||||
if(response.
|
||||
|
||||
getResult().
|
||||
|
||||
Reference in New Issue
Block a user