1// Copyright 2021 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.monitoring.v3;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/monitored_resource.proto";
23import "google/api/resource.proto";
24import "google/monitoring/v3/common.proto";
25import "google/monitoring/v3/group.proto";
26import "google/protobuf/empty.proto";
27
28option csharp_namespace = "Google.Cloud.Monitoring.V3";
29option go_package = "cloud.google.com/go/monitoring/apiv3/v2/monitoringpb;monitoringpb";
30option java_multiple_files = true;
31option java_outer_classname = "GroupServiceProto";
32option java_package = "com.google.monitoring.v3";
33option php_namespace = "Google\\Cloud\\Monitoring\\V3";
34option ruby_package = "Google::Cloud::Monitoring::V3";
35
36// The Group API lets you inspect and manage your
37// [groups](#google.monitoring.v3.Group).
38//
39// A group is a named filter that is used to identify
40// a collection of monitored resources. Groups are typically used to
41// mirror the physical and/or logical topology of the environment.
42// Because group membership is computed dynamically, monitored
43// resources that are started in the future are automatically placed
44// in matching groups. By using a group to name monitored resources in,
45// for example, an alert policy, the target of that alert policy is
46// updated automatically as monitored resources are added and removed
47// from the infrastructure.
48service GroupService {
49  option (google.api.default_host) = "monitoring.googleapis.com";
50  option (google.api.oauth_scopes) =
51      "https://www.googleapis.com/auth/cloud-platform,"
52      "https://www.googleapis.com/auth/monitoring,"
53      "https://www.googleapis.com/auth/monitoring.read";
54
55  // Lists the existing groups.
56  rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse) {
57    option (google.api.http) = {
58      get: "/v3/{name=projects/*}/groups"
59    };
60    option (google.api.method_signature) = "name";
61  }
62
63  // Gets a single group.
64  rpc GetGroup(GetGroupRequest) returns (Group) {
65    option (google.api.http) = {
66      get: "/v3/{name=projects/*/groups/*}"
67    };
68    option (google.api.method_signature) = "name";
69  }
70
71  // Creates a new group.
72  rpc CreateGroup(CreateGroupRequest) returns (Group) {
73    option (google.api.http) = {
74      post: "/v3/{name=projects/*}/groups"
75      body: "group"
76    };
77    option (google.api.method_signature) = "name,group";
78  }
79
80  // Updates an existing group.
81  // You can change any group attributes except `name`.
82  rpc UpdateGroup(UpdateGroupRequest) returns (Group) {
83    option (google.api.http) = {
84      put: "/v3/{group.name=projects/*/groups/*}"
85      body: "group"
86    };
87    option (google.api.method_signature) = "group";
88  }
89
90  // Deletes an existing group.
91  rpc DeleteGroup(DeleteGroupRequest) returns (google.protobuf.Empty) {
92    option (google.api.http) = {
93      delete: "/v3/{name=projects/*/groups/*}"
94    };
95    option (google.api.method_signature) = "name";
96  }
97
98  // Lists the monitored resources that are members of a group.
99  rpc ListGroupMembers(ListGroupMembersRequest) returns (ListGroupMembersResponse) {
100    option (google.api.http) = {
101      get: "/v3/{name=projects/*/groups/*}/members"
102    };
103    option (google.api.method_signature) = "name";
104  }
105}
106
107// The `ListGroup` request.
108message ListGroupsRequest {
109  // Required. The [project](https://cloud.google.com/monitoring/api/v3#project_name)
110  // whose groups are to be listed. The format is:
111  //
112  //     projects/[PROJECT_ID_OR_NUMBER]
113  string name = 7 [
114    (google.api.field_behavior) = REQUIRED,
115    (google.api.resource_reference) = {
116      child_type: "monitoring.googleapis.com/Group"
117    }
118  ];
119
120  // An optional filter consisting of a single group name.  The filters limit
121  // the groups returned based on their parent-child relationship with the
122  // specified group. If no filter is specified, all groups are returned.
123  oneof filter {
124    // A group name. The format is:
125    //
126    //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
127    //
128    // Returns groups whose `parent_name` field contains the group
129    // name.  If no groups have this parent, the results are empty.
130    string children_of_group = 2 [(google.api.resource_reference) = {
131                                    type: "monitoring.googleapis.com/Group"
132                                  }];
133
134    // A group name. The format is:
135    //
136    //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
137    //
138    // Returns groups that are ancestors of the specified group.
139    // The groups are returned in order, starting with the immediate parent and
140    // ending with the most distant ancestor.  If the specified group has no
141    // immediate parent, the results are empty.
142    string ancestors_of_group = 3 [(google.api.resource_reference) = {
143                                     type: "monitoring.googleapis.com/Group"
144                                   }];
145
146    // A group name. The format is:
147    //
148    //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
149    //
150    // Returns the descendants of the specified group.  This is a superset of
151    // the results returned by the `children_of_group` filter, and includes
152    // children-of-children, and so forth.
153    string descendants_of_group = 4 [(google.api.resource_reference) = {
154                                       type: "monitoring.googleapis.com/Group"
155                                     }];
156  }
157
158  // A positive number that is the maximum number of results to return.
159  int32 page_size = 5;
160
161  // If this field is not empty then it must contain the `next_page_token` value
162  // returned by a previous call to this method.  Using this field causes the
163  // method to return additional results from the previous method call.
164  string page_token = 6;
165}
166
167// The `ListGroups` response.
168message ListGroupsResponse {
169  // The groups that match the specified filters.
170  repeated Group group = 1;
171
172  // If there are more results than have been returned, then this field is set
173  // to a non-empty value.  To see the additional results,
174  // use that value as `page_token` in the next call to this method.
175  string next_page_token = 2;
176}
177
178// The `GetGroup` request.
179message GetGroupRequest {
180  // Required. The group to retrieve. The format is:
181  //
182  //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
183  string name = 3 [
184    (google.api.field_behavior) = REQUIRED,
185    (google.api.resource_reference) = {
186      type: "monitoring.googleapis.com/Group"
187    }
188  ];
189}
190
191// The `CreateGroup` request.
192message CreateGroupRequest {
193  // Required. The [project](https://cloud.google.com/monitoring/api/v3#project_name) in
194  // which to create the group. The format is:
195  //
196  //     projects/[PROJECT_ID_OR_NUMBER]
197  string name = 4 [
198    (google.api.field_behavior) = REQUIRED,
199    (google.api.resource_reference) = {
200      child_type: "monitoring.googleapis.com/Group"
201    }
202  ];
203
204  // Required. A group definition. It is an error to define the `name` field because
205  // the system assigns the name.
206  Group group = 2 [(google.api.field_behavior) = REQUIRED];
207
208  // If true, validate this request but do not create the group.
209  bool validate_only = 3;
210}
211
212// The `UpdateGroup` request.
213message UpdateGroupRequest {
214  // Required. The new definition of the group.  All fields of the existing group,
215  // excepting `name`, are replaced with the corresponding fields of this group.
216  Group group = 2 [(google.api.field_behavior) = REQUIRED];
217
218  // If true, validate this request but do not update the existing group.
219  bool validate_only = 3;
220}
221
222// The `DeleteGroup` request. The default behavior is to be able to delete a
223// single group without any descendants.
224message DeleteGroupRequest {
225  // Required. The group to delete. The format is:
226  //
227  //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
228  string name = 3 [
229    (google.api.field_behavior) = REQUIRED,
230    (google.api.resource_reference) = {
231      type: "monitoring.googleapis.com/Group"
232    }
233  ];
234
235  // If this field is true, then the request means to delete a group with all
236  // its descendants. Otherwise, the request means to delete a group only when
237  // it has no descendants. The default value is false.
238  bool recursive = 4;
239}
240
241// The `ListGroupMembers` request.
242message ListGroupMembersRequest {
243  // Required. The group whose members are listed. The format is:
244  //
245  //     projects/[PROJECT_ID_OR_NUMBER]/groups/[GROUP_ID]
246  string name = 7 [
247    (google.api.field_behavior) = REQUIRED,
248    (google.api.resource_reference) = {
249      type: "monitoring.googleapis.com/Group"
250    }
251  ];
252
253  // A positive number that is the maximum number of results to return.
254  int32 page_size = 3;
255
256  // If this field is not empty then it must contain the `next_page_token` value
257  // returned by a previous call to this method.  Using this field causes the
258  // method to return additional results from the previous method call.
259  string page_token = 4;
260
261  // An optional [list
262  // filter](https://cloud.google.com/monitoring/api/learn_more#filtering)
263  // describing the members to be returned.  The filter may reference the type,
264  // labels, and metadata of monitored resources that comprise the group. For
265  // example, to return only resources representing Compute Engine VM instances,
266  // use this filter:
267  //
268  //     `resource.type = "gce_instance"`
269  string filter = 5;
270
271  // An optional time interval for which results should be returned. Only
272  // members that were part of the group during the specified interval are
273  // included in the response.  If no interval is provided then the group
274  // membership over the last minute is returned.
275  TimeInterval interval = 6;
276}
277
278// The `ListGroupMembers` response.
279message ListGroupMembersResponse {
280  // A set of monitored resources in the group.
281  repeated google.api.MonitoredResource members = 1;
282
283  // If there are more results than have been returned, then this field is
284  // set to a non-empty value.  To see the additional results, use that value as
285  // `page_token` in the next call to this method.
286  string next_page_token = 2;
287
288  // The total number of elements matching this request.
289  int32 total_size = 3;
290}
291