Skip to content

Commit cb08d68

Browse files
thomas-nicolai-frequenzthomas-nicolai-frequenz
authored
v1alpha1 stuctural changes and documentation improvements (#97)
- Reworked documentation and structure - GetGridpoolResponse only returns Gridpool metadata but not assigned microgrids anymore - New ListMicrogrids RPC - Filter improvements for List* requests
2 parents 2d928c8 + f90d2ba commit cb08d68

2 files changed

Lines changed: 147 additions & 81 deletions

File tree

‎RELEASE_NOTES.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,23 @@
22

33
## Summary
44

5-
<!-- Here goes a general summary of what this release is about -->
5+
This release evolves the Assets API into the `PlatformAssetsService`, providing read-only access to platform asset metadata such as Gridpools, microgrids, electrical component inventories, and electrical component connections.
6+
7+
The release introduces Gridpool metadata retrieval and microgrid discovery within the current enterprise scope. It also aligns list request filtering with the structure used in other Frequenz APIs by moving filter fields into dedicated filter messages.
68

79
## Upgrading
810

9-
<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
11+
- The service has been renamed to `PlatformAssetsService`.
12+
- `GetGridpool` now returns only Gridpool metadata. Clients that need microgrids assigned to a Gridpool should use `ListMicrogrids` with the `gridpool_ids` filter.
13+
- The `ListMicrogridElectricalComponentsRequest` and
14+
- `ListMicrogridElectricalComponentConnectionsRequest` messages now use
15+
nested filter messages instead of placing all filter fields directly on the request message.
16+
- Changed ordering of RPCs
1017

1118
## New Features
1219

1320
<!-- Here goes the main new features and examples or instructions on how to use them -->
21+
- New ListMicrogrids RPC has been added
1422

1523
## Bug Fixes
1624

‎proto/frequenz/api/platformassets/v1alpha1/platformassets.proto‎

Lines changed: 137 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ syntax = "proto3";
1212

1313
package frequenz.api.platformassets.v1alpha1;
1414

15-
// protolint:disable:next MAX_LINE_LENGTH
1615
import "frequenz/api/common/v1alpha8/gridpool/gridpool.proto";
1716
// protolint:disable:next MAX_LINE_LENGTH
1817
import "frequenz/api/common/v1alpha8/microgrid/electrical_components/electrical_components.proto";
@@ -31,22 +30,22 @@ import "frequenz/api/common/v1alpha8/microgrid/microgrid.proto";
3130
// identifiers into their associated metadata.
3231
//
3332
// !!! important "Authentication"
34-
// All requests to FlexMarketService must be signed. The key identifier and
35-
// signature must be included in the request metadata (gRPC metadata /
33+
// All requests to PlatformAssetsService must be signed. The key identifier
34+
// and signature must be included in the request metadata (gRPC metadata /
3635
// HTTP headers). The signature must be computed using the HMAC-SHA256
3736
// algorithm and secret key. All requests to this service must be made
3837
// over TLS (HTTPS).
3938
//
4039
service PlatformAssetsService {
41-
// Returns metadata for all microgrids visible to the caller.
42-
rpc ListMicrogrids(ListMicrogridsRequest) returns (ListMicrogridsResponse);
43-
44-
// Returns metadata for a specific gridpool.
45-
rpc GetGridpool(GetGridpoolRequest) returns (GetGridpoolResponse);
40+
// Lists Gridpools within the current enterprise scope.
41+
rpc ListGridpools(ListGridpoolsRequest) returns (ListGridpoolsResponse);
4642

4743
// Returns metadata for a specific microgrid.
4844
rpc GetMicrogrid(GetMicrogridRequest) returns (GetMicrogridResponse);
4945

46+
// Lists microgrids within the current enterprise scope.
47+
rpc ListMicrogrids(ListMicrogridsRequest) returns (ListMicrogridsResponse);
48+
5049
// Lists electrical components for a specific microgrid.
5150
rpc ListMicrogridElectricalComponents(
5251
ListMicrogridElectricalComponentsRequest)
@@ -59,82 +58,38 @@ service PlatformAssetsService {
5958
returns (ListMicrogridElectricalComponentConnectionsResponse);
6059
}
6160

62-
// Request message for listing all visible microgrids.
63-
message ListMicrogridsRequest {
64-
}
65-
66-
// Response message containing all visible microgrids.
67-
message ListMicrogridsResponse {
68-
// Microgrids visible to the caller.
69-
repeated frequenz.api.common.v1alpha8.microgrid.Microgrid microgrids = 1;
70-
}
71-
72-
// Request message for retrieving metadata for a specific gridpool.
73-
message GetGridpoolRequest {
74-
// The unique identifier of the gridpool for which to fetch details.
75-
uint64 gridpool_id = 1;
76-
}
77-
78-
// Response message containing metadata for a specific gridpool.
79-
message GetGridpoolResponse {
80-
// Details of the requested gridpool.
81-
frequenz.api.common.v1alpha8.gridpool.Gridpool gridpool = 1;
82-
// Microgrids belonging to the requested gridpool.
83-
repeated frequenz.api.common.v1alpha8.microgrid.Microgrid microgrids = 2;
84-
}
85-
86-
// Filters for selecting electrical component connections in a microgrid.
87-
//
88-
// A connection must match all specified filter fields to be included in the
89-
// response.
90-
//
91-
// !!! note "Filter Semantics"
92-
// Each repeated field is evaluated using logical OR.
93-
//
94-
// Different filter fields are combined using logical AND.
95-
//
96-
// If no filters are provided, all known electrical connections in the
97-
// microgrid are returned.
98-
//
99-
message MicrogridElectricalComponentConnectionsFilter {
100-
// Optional. Return only connections whose source component ID is included in
101-
// this list.
61+
// Request message for listing Gridpools within the current enterprise scope.
62+
message ListGridpoolsRequest {
63+
// Filters for selecting Gridpools.
10264
//
103-
// If empty, connections from any source component are returned.
104-
repeated uint64 source_component_ids = 1;
105-
106-
// Optional. Return only connections whose destination component ID is
107-
// included in this list.
65+
// A Gridpool must match all specified filter fields to be included in the
66+
// response. The current enterprise scope is always applied in addition to
67+
// these filters.
10868
//
109-
// If empty, connections to any destination component are returned.
110-
repeated uint64 destination_component_ids = 2;
111-
}
112-
113-
// Filters for selecting electrical components in a microgrid.
114-
//
115-
// An electrical component must match all specified filter fields to be
116-
// included in the response.
117-
//
118-
// !!! note "Filter Semantics"
119-
// Each repeated field is evaluated using logical OR.
120-
//
121-
// Different filter fields are combined using logical AND.
122-
//
123-
// If no filters are provided, all electrical components in the microgrid
124-
// are returned.
125-
//
126-
message MicrogridElectricalComponentsFilter {
127-
// Optional. Return only components whose IDs are included in this list.
69+
// !!! note "Filter Semantics"
70+
// Each repeated field is evaluated using logical OR. Different filter
71+
// fields are combined using logical AND. If no filters are provided,
72+
// all Gridpools within the current enterprise scope are returned.
12873
//
129-
// If empty, no component-ID filtering is applied.
130-
repeated uint64 component_ids = 1;
74+
message GridpoolsFilter {
75+
// Optional. Return only Gridpools whose IDs are included in this list and
76+
// are within the current enterprise scope.
77+
//
78+
// If empty, no Gridpool-ID filtering is applied.
79+
repeated uint64 gridpool_ids = 1;
80+
}
13181

132-
// Optional. Return only components whose categories are included in this
133-
// list.
82+
// Optional. Filtering criteria for narrowing the returned Gridpools.
13483
//
135-
// If empty, no category filtering is applied.
136-
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
137-
ElectricalComponentCategory categories = 2;
84+
// If omitted, all Gridpools within the current enterprise scope are returned.
85+
GridpoolsFilter filter = 1;
86+
}
87+
88+
// Response message containing Gridpool metadata.
89+
message ListGridpoolsResponse {
90+
// Gridpools matching the request filters within the current enterprise
91+
// scope.
92+
repeated frequenz.api.common.v1alpha8.gridpool.Gridpool gridpools = 1;
13893
}
13994

14095
// Request message for retrieving metadata for a specific microgrid.
@@ -149,8 +104,83 @@ message GetMicrogridResponse {
149104
frequenz.api.common.v1alpha8.microgrid.Microgrid microgrid = 1;
150105
}
151106

107+
// Request message for listing microgrids accessible through the authenticated
108+
// client's enterprise-scoped authorization context.
109+
message ListMicrogridsRequest {
110+
// Filters for selecting microgrids.
111+
//
112+
// A microgrid must match all specified filter fields to be included in the
113+
// response. The current enterprise scope is always applied in addition to
114+
// these filters.
115+
//
116+
// !!! note "Filter Semantics"
117+
// Each repeated field is evaluated using logical OR. Different filter
118+
// fields are combined using logical AND. If no filters are provided,
119+
// all microgrids within the current enterprise
120+
// scope are returned.
121+
//
122+
message MicrogridsFilter {
123+
// Optional. Return only microgrids whose IDs are included in this list and
124+
// are within the current enterprise scope.
125+
//
126+
// If empty, no microgrid-ID filtering is applied.
127+
repeated uint64 microgrid_ids = 1;
128+
129+
// Optional. Return only microgrids assigned to any of these Gridpools
130+
// within the current enterprise scope.
131+
//
132+
// If empty, no Gridpool-ID filtering is applied.
133+
repeated uint64 gridpool_ids = 2;
134+
}
135+
136+
// Optional. Filtering criteria for narrowing the returned microgrids.
137+
//
138+
// If omitted, all microgrids accessible through the authenticated client's
139+
// enterprise-scoped authorization context are returned.
140+
MicrogridsFilter filter = 1;
141+
}
142+
143+
// Response message containing microgrid metadata.
144+
//
145+
// The response contains microgrids matching the requested filters within the
146+
// current enterprise-scoped context. If no matching microgrids are available
147+
// in that context, `microgrids` is empty.
148+
//
149+
message ListMicrogridsResponse {
150+
// Microgrids matching the request filters within the current
151+
// enterprise-scope.
152+
repeated frequenz.api.common.v1alpha8.microgrid.Microgrid microgrids = 1;
153+
}
154+
152155
// Request parameters for the RPC `ListMicrogridElectricalComponents`.
153156
message ListMicrogridElectricalComponentsRequest {
157+
// Filters for selecting electrical components in a microgrid.
158+
//
159+
// An electrical component must match all specified filter fields to be
160+
// included in the response.
161+
//
162+
// !!! note "Filter Semantics"
163+
// Each repeated field is evaluated using logical OR.
164+
//
165+
// Different filter fields are combined using logical AND.
166+
//
167+
// If no filters are provided, all electrical components in the microgrid
168+
// are returned.
169+
//
170+
message MicrogridElectricalComponentsFilter {
171+
// Optional. Return only components whose IDs are included in this list.
172+
//
173+
// If empty, no component-ID filtering is applied.
174+
repeated uint64 component_ids = 1;
175+
176+
// Optional. Return only components whose categories are included in this
177+
// list.
178+
//
179+
// If empty, no category filtering is applied.
180+
repeated frequenz.api.common.v1alpha8.microgrid.electrical_components.
181+
ElectricalComponentCategory categories = 2;
182+
}
183+
154184
// Mandatory field. The ID of the microgrid for which components
155185
// are to be listed.
156186
uint64 microgrid_id = 1;
@@ -190,6 +220,33 @@ message ListMicrogridElectricalComponentsResponse {
190220
// electrical energy flows within the microgrid.
191221
//
192222
message ListMicrogridElectricalComponentConnectionsRequest {
223+
// Filters for selecting electrical component connections in a microgrid.
224+
//
225+
// A connection must match all specified filter fields to be included in the
226+
// response.
227+
//
228+
// !!! note "Filter Semantics"
229+
// Each repeated field is evaluated using logical OR.
230+
//
231+
// Different filter fields are combined using logical AND.
232+
//
233+
// If no filters are provided, all known electrical connections in the
234+
// microgrid are returned.
235+
//
236+
message MicrogridElectricalComponentConnectionsFilter {
237+
// Optional. Return only connections whose source component ID is
238+
// included in this list.
239+
//
240+
// If empty, connections from any source component are returned.
241+
repeated uint64 source_component_ids = 1;
242+
243+
// Optional. Return only connections whose destination component ID is
244+
// included in this list.
245+
//
246+
// If empty, connections to any destination component are returned.
247+
repeated uint64 destination_component_ids = 2;
248+
}
249+
193250
// The unique identifier of the microgrid whose electrical component
194251
// connections should be listed.
195252
uint64 microgrid_id = 1;
@@ -204,6 +261,7 @@ message ListMicrogridElectricalComponentConnectionsRequest {
204261
//
205262
// The response contains all connections matching the requested filters. If no
206263
// connection matches the filters, `connections` is empty.
264+
//
207265
message ListMicrogridElectricalComponentConnectionsResponse {
208266
// The unique identifier of the microgrid the returned connections belong to.
209267
uint64 microgrid_id = 1;

0 commit comments

Comments
 (0)