1// Copyright 2023 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.apps.events.subscriptions.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/apps/events/subscriptions/v1/subscription_resource.proto"; 24import "google/longrunning/operations.proto"; 25import "google/protobuf/empty.proto"; 26import "google/protobuf/field_mask.proto"; 27 28option csharp_namespace = "Google.Apps.Events.Subscriptions.V1"; 29option go_package = "cloud.google.com/go/apps/events/subscriptions/apiv1/subscriptionspb;subscriptionspb"; 30option java_multiple_files = true; 31option java_outer_classname = "SubscriptionsServiceProto"; 32option java_package = "com.google.apps.events.subscriptions.v1"; 33option php_namespace = "Google\\Apps\\Events\\Subscriptions\\V1"; 34option ruby_package = "Google::Apps::Events::Subscriptions::V1"; 35 36// A service that manages subscriptions to Google Workspace events. 37service SubscriptionsService { 38 option (google.api.default_host) = "workspaceevents.googleapis.com"; 39 option (google.api.oauth_scopes) = 40 "https://www.googleapis.com/auth/chat.bot," 41 "https://www.googleapis.com/auth/chat.memberships," 42 "https://www.googleapis.com/auth/chat.memberships.readonly," 43 "https://www.googleapis.com/auth/chat.messages," 44 "https://www.googleapis.com/auth/chat.messages.reactions," 45 "https://www.googleapis.com/auth/chat.messages.reactions.readonly," 46 "https://www.googleapis.com/auth/chat.messages.readonly," 47 "https://www.googleapis.com/auth/chat.spaces," 48 "https://www.googleapis.com/auth/chat.spaces.readonly," 49 "https://www.googleapis.com/auth/meetings.space.created," 50 "https://www.googleapis.com/auth/meetings.space.readonly"; 51 52 // Creates a Google Workspace subscription. To learn how to use this 53 // method, see [Create a Google Workspace 54 // subscription](https://developers.google.com/workspace/events/guides/create-subscription). 55 rpc CreateSubscription(CreateSubscriptionRequest) 56 returns (google.longrunning.Operation) { 57 option (google.api.http) = { 58 post: "/v1/subscriptions" 59 body: "subscription" 60 }; 61 option (google.api.method_signature) = "subscription"; 62 option (google.longrunning.operation_info) = { 63 response_type: "Subscription" 64 metadata_type: "CreateSubscriptionMetadata" 65 }; 66 } 67 68 // Deletes a Google Workspace subscription. 69 // To learn how to use this method, see [Delete a Google Workspace 70 // subscription](https://developers.google.com/workspace/events/guides/delete-subscription). 71 rpc DeleteSubscription(DeleteSubscriptionRequest) 72 returns (google.longrunning.Operation) { 73 option (google.api.http) = { 74 delete: "/v1/{name=subscriptions/*}" 75 }; 76 option (google.api.method_signature) = "name"; 77 option (google.longrunning.operation_info) = { 78 response_type: "google.protobuf.Empty" 79 metadata_type: "DeleteSubscriptionMetadata" 80 }; 81 } 82 83 // Gets details about a Google Workspace subscription. To learn how to use 84 // this method, see [Get details about a Google Workspace 85 // subscription](https://developers.google.com/workspace/events/guides/get-subscription). 86 rpc GetSubscription(GetSubscriptionRequest) returns (Subscription) { 87 option (google.api.http) = { 88 get: "/v1/{name=subscriptions/*}" 89 }; 90 option (google.api.method_signature) = "name"; 91 } 92 93 // Lists Google Workspace subscriptions. To learn how to use this method, see 94 // [List Google Workspace 95 // subscriptions](https://developers.google.com/workspace/events/guides/list-subscriptions). 96 rpc ListSubscriptions(ListSubscriptionsRequest) 97 returns (ListSubscriptionsResponse) { 98 option (google.api.http) = { 99 get: "/v1/subscriptions" 100 }; 101 option (google.api.method_signature) = "filter"; 102 } 103 104 // Updates or renews a Google Workspace subscription. To learn how to use this 105 // method, see [Update or renew a Google Workspace 106 // subscription](https://developers.google.com/workspace/events/guides/update-subscription). 107 rpc UpdateSubscription(UpdateSubscriptionRequest) 108 returns (google.longrunning.Operation) { 109 option (google.api.http) = { 110 patch: "/v1/{subscription.name=subscriptions/*}" 111 body: "subscription" 112 }; 113 option (google.api.method_signature) = "subscription,update_mask"; 114 option (google.longrunning.operation_info) = { 115 response_type: "Subscription" 116 metadata_type: "UpdateSubscriptionMetadata" 117 }; 118 } 119 120 // Reactivates a suspended Google Workspace subscription. 121 // 122 // This method resets your subscription's `State` field to `ACTIVE`. Before 123 // you use this method, you must fix the error that suspended the 124 // subscription. To learn how to use this method, see [Reactivate a Google 125 // Workspace 126 // subscription](https://developers.google.com/workspace/events/guides/reactivate-subscription). 127 rpc ReactivateSubscription(ReactivateSubscriptionRequest) 128 returns (google.longrunning.Operation) { 129 option (google.api.http) = { 130 post: "/v1/{name=subscriptions/*}:reactivate" 131 body: "*" 132 }; 133 option (google.api.method_signature) = "name"; 134 option (google.longrunning.operation_info) = { 135 response_type: "Subscription" 136 metadata_type: "ReactivateSubscriptionMetadata" 137 }; 138 } 139} 140 141// The request message for 142// [SubscriptionsService.CreateSubscription][google.apps.events.subscriptions.v1.SubscriptionsService.CreateSubscription]. 143message CreateSubscriptionRequest { 144 // Required. The subscription resource to create. 145 Subscription subscription = 1 [(google.api.field_behavior) = REQUIRED]; 146 147 // Optional. If set to `true`, validates and previews the request, but doesn't 148 // create the subscription. 149 bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL]; 150} 151 152// The request message for 153// [SubscriptionsService.DeleteSubscription][google.apps.events.subscriptions.v1.SubscriptionsService.DeleteSubscription]. 154message DeleteSubscriptionRequest { 155 // Required. Resource name of the subscription to delete. 156 // 157 // Format: `subscriptions/{subscription}` 158 string name = 1 [ 159 (google.api.field_behavior) = REQUIRED, 160 (google.api.resource_reference) = { 161 type: "workspaceevents.googleapis.com/Subscription" 162 } 163 ]; 164 165 // Optional. If set to `true`, validates and previews the request, but doesn't 166 // delete the subscription. 167 bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL]; 168 169 // Optional. If set to `true` and the subscription isn't found, the request 170 // succeeds but doesn't delete the subscription. 171 bool allow_missing = 3 [(google.api.field_behavior) = OPTIONAL]; 172 173 // Optional. Etag of the subscription. 174 // 175 // If present, it must match with the server's etag. Otherwise, request 176 // fails with the status `ABORTED`. 177 string etag = 4 [(google.api.field_behavior) = OPTIONAL]; 178} 179 180// The request message for 181// [SubscriptionsService.GetSubscription][google.apps.events.subscriptions.v1.SubscriptionsService.GetSubscription]. 182message GetSubscriptionRequest { 183 // Required. Resource name of the subscription. 184 // 185 // Format: `subscriptions/{subscription}` 186 string name = 1 [ 187 (google.api.field_behavior) = REQUIRED, 188 (google.api.resource_reference) = { 189 type: "workspaceevents.googleapis.com/Subscription" 190 } 191 ]; 192} 193 194// The request message for 195// [SubscriptionsService.UpdateSubscription][google.apps.events.subscriptions.v1.SubscriptionsService.UpdateSubscription]. 196message UpdateSubscriptionRequest { 197 // Required. The subscription to update. 198 // 199 // The subscription's `name` field is used to identify the subscription to 200 // update. 201 Subscription subscription = 1 [(google.api.field_behavior) = REQUIRED]; 202 203 // Optional. Required. The field to update. 204 // 205 // You can update one of the following fields in a subscription: 206 // 207 // * [`expire_time`][google.apps.events.subscriptions.v1.Subscription.expire_time]: The timestamp when the 208 // subscription expires. 209 // * [`ttl`][google.apps.events.subscriptions.v1.Subscription.ttl]: The 210 // time-to-live (TTL) or duration of the 211 // subscription. 212 google.protobuf.FieldMask update_mask = 2 213 [(google.api.field_behavior) = OPTIONAL]; 214 215 // Optional. If set to `true`, validates and previews the request, but doesn't 216 // update the subscription. 217 bool validate_only = 3 [(google.api.field_behavior) = OPTIONAL]; 218} 219 220// The request message for 221// [SubscriptionsService.ReactivateSubscription][google.apps.events.subscriptions.v1.SubscriptionsService.ReactivateSubscription]. 222message ReactivateSubscriptionRequest { 223 // Required. Resource name of the subscription. 224 // 225 // Format: `subscriptions/{subscription}` 226 string name = 1 [ 227 (google.api.field_behavior) = REQUIRED, 228 (google.api.resource_reference) = { 229 type: "workspaceevents.googleapis.com/Subscription" 230 } 231 ]; 232} 233 234// The request message for 235// [SubscriptionsService.ListSubscriptions][google.apps.events.subscriptions.v1.SubscriptionsService.ListSubscriptions]. 236message ListSubscriptionsRequest { 237 // Optional. The maximum number of subscriptions to return. The service might 238 // return fewer than this value. 239 // 240 // If unspecified or set to `0`, up to 50 subscriptions are returned. 241 // 242 // The maximum value is 100. If you specify a value more than 100, the system 243 // only returns 100 subscriptions. 244 int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL]; 245 246 // Optional. A page token, received from a previous list subscriptions call. 247 // Provide this parameter to retrieve the subsequent page. 248 // 249 // When paginating, the filter value should match the call that provided the 250 // page token. Passing a different value might lead to unexpected results. 251 string page_token = 2 [(google.api.field_behavior) = OPTIONAL]; 252 253 // Required. A query filter. 254 // 255 // You can filter subscriptions by event type (`event_types`) 256 // and target resource (`target_resource`). 257 // 258 // You must specify at least one event type in your query. To filter for 259 // multiple event types, use the `OR` operator. 260 // 261 // To filter by both event type and target resource, use the `AND` operator 262 // and specify the full resource name, such as 263 // `//chat.googleapis.com/spaces/{space}`. 264 // 265 // For example, the following queries are valid: 266 // 267 // ``` 268 // event_types:"google.workspace.chat.membership.v1.updated" OR 269 // event_types:"google.workspace.chat.message.v1.created" 270 // 271 // event_types:"google.workspace.chat.message.v1.created" AND 272 // target_resource="//chat.googleapis.com/spaces/{space}" 273 // 274 // ( event_types:"google.workspace.chat.membership.v1.updated" OR 275 // event_types:"google.workspace.chat.message.v1.created" ) AND 276 // target_resource="//chat.googleapis.com/spaces/{space}" 277 // ``` 278 // 279 // The server rejects invalid queries with an `INVALID_ARGUMENT` 280 // error. 281 string filter = 3 [(google.api.field_behavior) = REQUIRED]; 282} 283 284// The response message for 285// [SubscriptionsService.ListSubscriptions][google.apps.events.subscriptions.v1.SubscriptionsService.ListSubscriptions]. 286message ListSubscriptionsResponse { 287 // List of subscriptions. 288 repeated Subscription subscriptions = 1; 289 290 // A token, which can be sent as `page_token` to retrieve the next page. 291 // If this field is omitted, there are no subsequent pages. 292 string next_page_token = 2; 293} 294 295// Metadata for UpdateSubscription LRO. 296message UpdateSubscriptionMetadata {} 297 298// Metadata for CreateSubscription LRO. 299message CreateSubscriptionMetadata {} 300 301// Metadata for DeleteSubscription LRO. 302message DeleteSubscriptionMetadata {} 303 304// Metadata for ReactivateSubscription LRO. 305message ReactivateSubscriptionMetadata {} 306