-
Notifications
You must be signed in to change notification settings - Fork 2.3k
/
notification_service.proto
448 lines (405 loc) · 18.4 KB
/
notification_service.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
package google.monitoring.v3;
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/monitoring/v3/notification.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Google.Cloud.Monitoring.V3";
option go_package = "cloud.google.com/go/monitoring/apiv3/v2/monitoringpb;monitoringpb";
option java_multiple_files = true;
option java_outer_classname = "NotificationServiceProto";
option java_package = "com.google.monitoring.v3";
option php_namespace = "Google\\Cloud\\Monitoring\\V3";
option ruby_package = "Google::Cloud::Monitoring::V3";
// The Notification Channel API provides access to configuration that
// controls how messages related to incidents are sent.
service NotificationChannelService {
option (google.api.default_host) = "monitoring.googleapis.com";
option (google.api.oauth_scopes) =
"https://www.googleapis.com/auth/cloud-platform,"
"https://www.googleapis.com/auth/monitoring,"
"https://www.googleapis.com/auth/monitoring.read";
// Lists the descriptors for supported channel types. The use of descriptors
// makes it possible for new channel types to be dynamically added.
rpc ListNotificationChannelDescriptors(
ListNotificationChannelDescriptorsRequest)
returns (ListNotificationChannelDescriptorsResponse) {
option (google.api.http) = {
get: "/v3/{name=projects/*}/notificationChannelDescriptors"
};
option (google.api.method_signature) = "name";
}
// Gets a single channel descriptor. The descriptor indicates which fields
// are expected / permitted for a notification channel of the given type.
rpc GetNotificationChannelDescriptor(GetNotificationChannelDescriptorRequest)
returns (NotificationChannelDescriptor) {
option (google.api.http) = {
get: "/v3/{name=projects/*/notificationChannelDescriptors/*}"
};
option (google.api.method_signature) = "name";
}
// Lists the notification channels that have been created for the project.
// To list the types of notification channels that are supported, use
// the `ListNotificationChannelDescriptors` method.
rpc ListNotificationChannels(ListNotificationChannelsRequest)
returns (ListNotificationChannelsResponse) {
option (google.api.http) = {
get: "/v3/{name=projects/*}/notificationChannels"
};
option (google.api.method_signature) = "name";
}
// Gets a single notification channel. The channel includes the relevant
// configuration details with which the channel was created. However, the
// response may truncate or omit passwords, API keys, or other private key
// matter and thus the response may not be 100% identical to the information
// that was supplied in the call to the create method.
rpc GetNotificationChannel(GetNotificationChannelRequest)
returns (NotificationChannel) {
option (google.api.http) = {
get: "/v3/{name=projects/*/notificationChannels/*}"
};
option (google.api.method_signature) = "name";
}
// Creates a new notification channel, representing a single notification
// endpoint such as an email address, SMS number, or PagerDuty service.
//
// Design your application to single-thread API calls that modify the state of
// notification channels in a single project. This includes calls to
// CreateNotificationChannel, DeleteNotificationChannel and
// UpdateNotificationChannel.
rpc CreateNotificationChannel(CreateNotificationChannelRequest)
returns (NotificationChannel) {
option (google.api.http) = {
post: "/v3/{name=projects/*}/notificationChannels"
body: "notification_channel"
};
option (google.api.method_signature) = "name,notification_channel";
}
// Updates a notification channel. Fields not specified in the field mask
// remain unchanged.
//
// Design your application to single-thread API calls that modify the state of
// notification channels in a single project. This includes calls to
// CreateNotificationChannel, DeleteNotificationChannel and
// UpdateNotificationChannel.
rpc UpdateNotificationChannel(UpdateNotificationChannelRequest)
returns (NotificationChannel) {
option (google.api.http) = {
patch: "/v3/{notification_channel.name=projects/*/notificationChannels/*}"
body: "notification_channel"
};
option (google.api.method_signature) = "update_mask,notification_channel";
}
// Deletes a notification channel.
//
// Design your application to single-thread API calls that modify the state of
// notification channels in a single project. This includes calls to
// CreateNotificationChannel, DeleteNotificationChannel and
// UpdateNotificationChannel.
rpc DeleteNotificationChannel(DeleteNotificationChannelRequest)
returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v3/{name=projects/*/notificationChannels/*}"
};
option (google.api.method_signature) = "name,force";
}
// Causes a verification code to be delivered to the channel. The code
// can then be supplied in `VerifyNotificationChannel` to verify the channel.
rpc SendNotificationChannelVerificationCode(
SendNotificationChannelVerificationCodeRequest)
returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/v3/{name=projects/*/notificationChannels/*}:sendVerificationCode"
body: "*"
};
option (google.api.method_signature) = "name";
}
// Requests a verification code for an already verified channel that can then
// be used in a call to VerifyNotificationChannel() on a different channel
// with an equivalent identity in the same or in a different project. This
// makes it possible to copy a channel between projects without requiring
// manual reverification of the channel. If the channel is not in the
// verified state, this method will fail (in other words, this may only be
// used if the SendNotificationChannelVerificationCode and
// VerifyNotificationChannel paths have already been used to put the given
// channel into the verified state).
//
// There is no guarantee that the verification codes returned by this method
// will be of a similar structure or form as the ones that are delivered
// to the channel via SendNotificationChannelVerificationCode; while
// VerifyNotificationChannel() will recognize both the codes delivered via
// SendNotificationChannelVerificationCode() and returned from
// GetNotificationChannelVerificationCode(), it is typically the case that
// the verification codes delivered via
// SendNotificationChannelVerificationCode() will be shorter and also
// have a shorter expiration (e.g. codes such as "G-123456") whereas
// GetVerificationCode() will typically return a much longer, websafe base
// 64 encoded string that has a longer expiration time.
rpc GetNotificationChannelVerificationCode(
GetNotificationChannelVerificationCodeRequest)
returns (GetNotificationChannelVerificationCodeResponse) {
option (google.api.http) = {
post: "/v3/{name=projects/*/notificationChannels/*}:getVerificationCode"
body: "*"
};
option (google.api.method_signature) = "name";
}
// Verifies a `NotificationChannel` by proving receipt of the code
// delivered to the channel as a result of calling
// `SendNotificationChannelVerificationCode`.
rpc VerifyNotificationChannel(VerifyNotificationChannelRequest)
returns (NotificationChannel) {
option (google.api.http) = {
post: "/v3/{name=projects/*/notificationChannels/*}:verify"
body: "*"
};
option (google.api.method_signature) = "name,code";
}
}
// The `ListNotificationChannelDescriptors` request.
message ListNotificationChannelDescriptorsRequest {
// Required. The REST resource name of the parent from which to retrieve
// the notification channel descriptors. The expected syntax is:
//
// projects/[PROJECT_ID_OR_NUMBER]
//
// Note that this
// [names](https://cloud.google.com/monitoring/api/v3#project_name) the parent
// container in which to look for the descriptors; to retrieve a single
// descriptor by name, use the
// [GetNotificationChannelDescriptor][google.monitoring.v3.NotificationChannelService.GetNotificationChannelDescriptor]
// operation, instead.
string name = 4 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
child_type: "monitoring.googleapis.com/NotificationChannelDescriptor"
}
];
// The maximum number of results to return in a single response. If
// not set to a positive number, a reasonable value will be chosen by the
// service.
int32 page_size = 2;
// If non-empty, `page_token` must contain a value returned as the
// `next_page_token` in a previous response to request the next set
// of results.
string page_token = 3;
}
// The `ListNotificationChannelDescriptors` response.
message ListNotificationChannelDescriptorsResponse {
// The monitored resource descriptors supported for the specified
// project, optionally filtered.
repeated NotificationChannelDescriptor channel_descriptors = 1;
// If not empty, indicates that there may be more results that match
// the request. Use the value in the `page_token` field in a
// subsequent request to fetch the next set of results. If empty,
// all results have been returned.
string next_page_token = 2;
}
// The `GetNotificationChannelDescriptor` response.
message GetNotificationChannelDescriptorRequest {
// Required. The channel type for which to execute the request. The format is:
//
// projects/[PROJECT_ID_OR_NUMBER]/notificationChannelDescriptors/[CHANNEL_TYPE]
string name = 3 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannelDescriptor"
}
];
}
// The `CreateNotificationChannel` request.
message CreateNotificationChannelRequest {
// Required. The
// [project](https://cloud.google.com/monitoring/api/v3#project_name) on which
// to execute the request. The format is:
//
// projects/[PROJECT_ID_OR_NUMBER]
//
// This names the container into which the channel will be
// written, this does not name the newly created channel. The resulting
// channel's name will have a normalized version of this field as a prefix,
// but will add `/notificationChannels/[CHANNEL_ID]` to identify the channel.
string name = 3 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
child_type: "monitoring.googleapis.com/NotificationChannel"
}
];
// Required. The definition of the `NotificationChannel` to create.
NotificationChannel notification_channel = 2
[(google.api.field_behavior) = REQUIRED];
}
// The `ListNotificationChannels` request.
message ListNotificationChannelsRequest {
// Required. The
// [project](https://cloud.google.com/monitoring/api/v3#project_name) on which
// to execute the request. The format is:
//
// projects/[PROJECT_ID_OR_NUMBER]
//
// This names the container
// in which to look for the notification channels; it does not name a
// specific channel. To query a specific channel by REST resource name, use
// the
// [`GetNotificationChannel`][google.monitoring.v3.NotificationChannelService.GetNotificationChannel]
// operation.
string name = 5 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
child_type: "monitoring.googleapis.com/NotificationChannel"
}
];
// If provided, this field specifies the criteria that must be met by
// notification channels to be included in the response.
//
// For more details, see [sorting and
// filtering](https://cloud.google.com/monitoring/api/v3/sorting-and-filtering).
string filter = 6;
// A comma-separated list of fields by which to sort the result. Supports
// the same set of fields as in `filter`. Entries can be prefixed with
// a minus sign to sort in descending rather than ascending order.
//
// For more details, see [sorting and
// filtering](https://cloud.google.com/monitoring/api/v3/sorting-and-filtering).
string order_by = 7;
// The maximum number of results to return in a single response. If
// not set to a positive number, a reasonable value will be chosen by the
// service.
int32 page_size = 3;
// If non-empty, `page_token` must contain a value returned as the
// `next_page_token` in a previous response to request the next set
// of results.
string page_token = 4;
}
// The `ListNotificationChannels` response.
message ListNotificationChannelsResponse {
// The notification channels defined for the specified project.
repeated NotificationChannel notification_channels = 3;
// If not empty, indicates that there may be more results that match
// the request. Use the value in the `page_token` field in a
// subsequent request to fetch the next set of results. If empty,
// all results have been returned.
string next_page_token = 2;
// The total number of notification channels in all pages. This number is only
// an estimate, and may change in subsequent pages. https://aip.dev/158
int32 total_size = 4;
}
// The `GetNotificationChannel` request.
message GetNotificationChannelRequest {
// Required. The channel for which to execute the request. The format is:
//
// projects/[PROJECT_ID_OR_NUMBER]/notificationChannels/[CHANNEL_ID]
string name = 3 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannel"
}
];
}
// The `UpdateNotificationChannel` request.
message UpdateNotificationChannelRequest {
// The fields to update.
google.protobuf.FieldMask update_mask = 2;
// Required. A description of the changes to be applied to the specified
// notification channel. The description must provide a definition for
// fields to be updated; the names of these fields should also be
// included in the `update_mask`.
NotificationChannel notification_channel = 3
[(google.api.field_behavior) = REQUIRED];
}
// The `DeleteNotificationChannel` request.
message DeleteNotificationChannelRequest {
// Required. The channel for which to execute the request. The format is:
//
// projects/[PROJECT_ID_OR_NUMBER]/notificationChannels/[CHANNEL_ID]
string name = 3 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannel"
}
];
// If true, the notification channel will be deleted regardless of its
// use in alert policies (the policies will be updated to remove the
// channel). If false, channels that are still referenced by an existing
// alerting policy will fail to be deleted in a delete operation.
bool force = 5;
}
// The `SendNotificationChannelVerificationCode` request.
message SendNotificationChannelVerificationCodeRequest {
// Required. The notification channel to which to send a verification code.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannel"
}
];
}
// The `GetNotificationChannelVerificationCode` request.
message GetNotificationChannelVerificationCodeRequest {
// Required. The notification channel for which a verification code is to be
// generated and retrieved. This must name a channel that is already verified;
// if the specified channel is not verified, the request will fail.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannel"
}
];
// The desired expiration time. If specified, the API will guarantee that
// the returned code will not be valid after the specified timestamp;
// however, the API cannot guarantee that the returned code will be
// valid for at least as long as the requested time (the API puts an upper
// bound on the amount of time for which a code may be valid). If omitted,
// a default expiration will be used, which may be less than the max
// permissible expiration (so specifying an expiration may extend the
// code's lifetime over omitting an expiration, even though the API does
// impose an upper limit on the maximum expiration that is permitted).
google.protobuf.Timestamp expire_time = 2;
}
// The `GetNotificationChannelVerificationCode` request.
message GetNotificationChannelVerificationCodeResponse {
// The verification code, which may be used to verify other channels
// that have an equivalent identity (i.e. other channels of the same
// type with the same fingerprint such as other email channels with
// the same email address or other sms channels with the same number).
string code = 1;
// The expiration time associated with the code that was returned. If
// an expiration was provided in the request, this is the minimum of the
// requested expiration in the request and the max permitted expiration.
google.protobuf.Timestamp expire_time = 2;
}
// The `VerifyNotificationChannel` request.
message VerifyNotificationChannelRequest {
// Required. The notification channel to verify.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "monitoring.googleapis.com/NotificationChannel"
}
];
// Required. The verification code that was delivered to the channel as
// a result of invoking the `SendNotificationChannelVerificationCode` API
// method or that was retrieved from a verified channel via
// `GetNotificationChannelVerificationCode`. For example, one might have
// "G-123456" or "TKNZGhhd2EyN3I1MnRnMjRv" (in general, one is only
// guaranteed that the code is valid UTF-8; one should not
// make any assumptions regarding the structure or format of the code).
string code = 2 [(google.api.field_behavior) = REQUIRED];
}