--- /dev/null
+// Copyright 2018 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/monitoring/v3/notification.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.Monitoring.V3";
+option go_package = "google.golang.org/genproto/googleapis/monitoring/v3;monitoring";
+option java_multiple_files = true;
+option java_outer_classname = "NotificationServiceProto";
+option java_package = "com.google.monitoring.v3";
+option php_namespace = "Google\\Cloud\\Monitoring\\V3";
+
+// The Notification Channel API provides access to configuration that
+// controls how messages related to incidents are sent.
+service NotificationChannelService {
+ // 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"
+ };
+ }
+
+ // 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/*}"
+ };
+ }
+
+ // Lists the notification channels that have been created for the project.
+ rpc ListNotificationChannels(ListNotificationChannelsRequest)
+ returns (ListNotificationChannelsResponse) {
+ option (google.api.http) = {
+ get: "/v3/{name=projects/*}/notificationChannels"
+ };
+ }
+
+ // 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/*}"
+ };
+ }
+
+ // Creates a new notification channel, representing a single notification
+ // endpoint such as an email address, SMS number, or PagerDuty service.
+ rpc CreateNotificationChannel(CreateNotificationChannelRequest)
+ returns (NotificationChannel) {
+ option (google.api.http) = {
+ post: "/v3/{name=projects/*}/notificationChannels"
+ body: "notification_channel"
+ };
+ }
+
+ // Updates a notification channel. Fields not specified in the field mask
+ // remain unchanged.
+ rpc UpdateNotificationChannel(UpdateNotificationChannelRequest)
+ returns (NotificationChannel) {
+ option (google.api.http) = {
+ patch: "/v3/{notification_channel.name=projects/*/notificationChannels/*}"
+ body: "notification_channel"
+ };
+ }
+
+ // Deletes a notification channel.
+ rpc DeleteNotificationChannel(DeleteNotificationChannelRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v3/{name=projects/*/notificationChannels/*}"
+ };
+ }
+
+ // 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: "*"
+ };
+ }
+
+ // 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: "*"
+ };
+ }
+
+ // 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: "*"
+ };
+ }
+}
+
+// The `ListNotificationChannelDescriptors` request.
+message ListNotificationChannelDescriptorsRequest {
+ // The REST resource name of the parent from which to retrieve
+ // the notification channel descriptors. The expected syntax is:
+ //
+ // projects/[PROJECT_ID]
+ //
+ // Note that this names 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;
+
+ // 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 {
+ // The channel type for which to execute the request. The format is
+ // `projects/[PROJECT_ID]/notificationChannelDescriptors/{channel_type}`.
+ string name = 3;
+}
+
+// The `CreateNotificationChannel` request.
+message CreateNotificationChannelRequest {
+ // The project on which to execute the request. The format is:
+ //
+ // projects/[PROJECT_ID]
+ //
+ // Note that 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;
+
+ // The definition of the `NotificationChannel` to create.
+ NotificationChannel notification_channel = 2;
+}
+
+// The `ListNotificationChannels` request.
+message ListNotificationChannelsRequest {
+ // The project on which to execute the request. The format is
+ // `projects/[PROJECT_ID]`. That is, 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;
+
+ // 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](/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](/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 `GetNotificationChannel` request.
+message GetNotificationChannelRequest {
+ // The channel for which to execute the request. The format is
+ // `projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]`.
+ string name = 3;
+}
+
+// The `UpdateNotificationChannel` request.
+message UpdateNotificationChannelRequest {
+ // The fields to update.
+ google.protobuf.FieldMask update_mask = 2;
+
+ // 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;
+}
+
+// The `DeleteNotificationChannel` request.
+message DeleteNotificationChannelRequest {
+ // The channel for which to execute the request. The format is
+ // `projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]`.
+ string name = 3;
+
+ // 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 {
+ // The notification channel to which to send a verification code.
+ string name = 1;
+}
+
+// The `GetNotificationChannelVerificationCode` request.
+message GetNotificationChannelVerificationCodeRequest {
+ // 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;
+
+ // 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 {
+ // The notification channel to verify.
+ string name = 1;
+
+ // 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;
+}