|
| 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 | + |
| 15 | +syntax = "proto3"; |
| 16 | + |
| 17 | +package google.api.apikeys.v2; |
| 18 | + |
| 19 | +import "google/api/annotations.proto"; |
| 20 | +import "google/api/apikeys/v2/resources.proto"; |
| 21 | +import "google/api/client.proto"; |
| 22 | +import "google/api/field_behavior.proto"; |
| 23 | +import "google/api/resource.proto"; |
| 24 | +import "google/longrunning/operations.proto"; |
| 25 | +import "google/protobuf/empty.proto"; |
| 26 | +import "google/protobuf/field_mask.proto"; |
| 27 | + |
| 28 | +option csharp_namespace = "Google.Cloud.ApiKeys.V2"; |
| 29 | +option go_package = "cloud.google.com/go/apikeys/apiv2/apikeyspb;apikeyspb"; |
| 30 | +option java_multiple_files = true; |
| 31 | +option java_outer_classname = "ApiKeysProto"; |
| 32 | +option java_package = "com.google.api.apikeys.v2"; |
| 33 | +option php_namespace = "Google\\Cloud\\ApiKeys\\V2"; |
| 34 | +option ruby_package = "Google::Cloud::ApiKeys::V2"; |
| 35 | + |
| 36 | +// Manages the API keys associated with projects. |
| 37 | +service ApiKeys { |
| 38 | + option (google.api.default_host) = "apikeys.googleapis.com"; |
| 39 | + option (google.api.oauth_scopes) = |
| 40 | + "https://www.googleapis.com/auth/cloud-platform," |
| 41 | + "https://www.googleapis.com/auth/cloud-platform.read-only"; |
| 42 | + |
| 43 | + // Creates a new API key. |
| 44 | + // |
| 45 | + // NOTE: Key is a global resource; hence the only supported value for |
| 46 | + // location is `global`. |
| 47 | + rpc CreateKey(CreateKeyRequest) returns (google.longrunning.Operation) { |
| 48 | + option (google.api.http) = { |
| 49 | + post: "/v2/{parent=projects/*/locations/*}/keys" |
| 50 | + body: "key" |
| 51 | + }; |
| 52 | + option (google.api.method_signature) = "parent,key,key_id"; |
| 53 | + option (google.longrunning.operation_info) = { |
| 54 | + response_type: "Key" |
| 55 | + metadata_type: "google.protobuf.Empty" |
| 56 | + }; |
| 57 | + } |
| 58 | + |
| 59 | + // Lists the API keys owned by a project. The key string of the API key |
| 60 | + // isn't included in the response. |
| 61 | + // |
| 62 | + // NOTE: Key is a global resource; hence the only supported value for |
| 63 | + // location is `global`. |
| 64 | + rpc ListKeys(ListKeysRequest) returns (ListKeysResponse) { |
| 65 | + option (google.api.http) = { |
| 66 | + get: "/v2/{parent=projects/*/locations/*}/keys" |
| 67 | + }; |
| 68 | + option (google.api.method_signature) = "parent"; |
| 69 | + } |
| 70 | + |
| 71 | + // Gets the metadata for an API key. The key string of the API key |
| 72 | + // isn't included in the response. |
| 73 | + // |
| 74 | + // NOTE: Key is a global resource; hence the only supported value for |
| 75 | + // location is `global`. |
| 76 | + rpc GetKey(GetKeyRequest) returns (Key) { |
| 77 | + option (google.api.http) = { |
| 78 | + get: "/v2/{name=projects/*/locations/*/keys/*}" |
| 79 | + }; |
| 80 | + option (google.api.method_signature) = "name"; |
| 81 | + } |
| 82 | + |
| 83 | + // Get the key string for an API key. |
| 84 | + // |
| 85 | + // NOTE: Key is a global resource; hence the only supported value for |
| 86 | + // location is `global`. |
| 87 | + rpc GetKeyString(GetKeyStringRequest) returns (GetKeyStringResponse) { |
| 88 | + option (google.api.http) = { |
| 89 | + get: "/v2/{name=projects/*/locations/*/keys/*}/keyString" |
| 90 | + }; |
| 91 | + option (google.api.method_signature) = "name"; |
| 92 | + } |
| 93 | + |
| 94 | + // Patches the modifiable fields of an API key. |
| 95 | + // The key string of the API key isn't included in the response. |
| 96 | + // |
| 97 | + // NOTE: Key is a global resource; hence the only supported value for |
| 98 | + // location is `global`. |
| 99 | + rpc UpdateKey(UpdateKeyRequest) returns (google.longrunning.Operation) { |
| 100 | + option (google.api.http) = { |
| 101 | + patch: "/v2/{key.name=projects/*/locations/*/keys/*}" |
| 102 | + body: "key" |
| 103 | + }; |
| 104 | + option (google.api.method_signature) = "key,update_mask"; |
| 105 | + option (google.longrunning.operation_info) = { |
| 106 | + response_type: "Key" |
| 107 | + metadata_type: "google.protobuf.Empty" |
| 108 | + }; |
| 109 | + } |
| 110 | + |
| 111 | + // Deletes an API key. Deleted key can be retrieved within 30 days of |
| 112 | + // deletion. Afterward, key will be purged from the project. |
| 113 | + // |
| 114 | + // NOTE: Key is a global resource; hence the only supported value for |
| 115 | + // location is `global`. |
| 116 | + rpc DeleteKey(DeleteKeyRequest) returns (google.longrunning.Operation) { |
| 117 | + option (google.api.http) = { |
| 118 | + delete: "/v2/{name=projects/*/locations/*/keys/*}" |
| 119 | + }; |
| 120 | + option (google.api.method_signature) = "name"; |
| 121 | + option (google.longrunning.operation_info) = { |
| 122 | + response_type: "Key" |
| 123 | + metadata_type: "google.protobuf.Empty" |
| 124 | + }; |
| 125 | + } |
| 126 | + |
| 127 | + // Undeletes an API key which was deleted within 30 days. |
| 128 | + // |
| 129 | + // NOTE: Key is a global resource; hence the only supported value for |
| 130 | + // location is `global`. |
| 131 | + rpc UndeleteKey(UndeleteKeyRequest) returns (google.longrunning.Operation) { |
| 132 | + option (google.api.http) = { |
| 133 | + post: "/v2/{name=projects/*/locations/*/keys/*}:undelete" |
| 134 | + body: "*" |
| 135 | + }; |
| 136 | + option (google.longrunning.operation_info) = { |
| 137 | + response_type: "Key" |
| 138 | + metadata_type: "google.protobuf.Empty" |
| 139 | + }; |
| 140 | + } |
| 141 | + |
| 142 | + // Find the parent project and resource name of the API |
| 143 | + // key that matches the key string in the request. If the API key has been |
| 144 | + // purged, resource name will not be set. |
| 145 | + // The service account must have the `apikeys.keys.lookup` permission |
| 146 | + // on the parent project. |
| 147 | + rpc LookupKey(LookupKeyRequest) returns (LookupKeyResponse) { |
| 148 | + option (google.api.http) = { |
| 149 | + get: "/v2/keys:lookupKey" |
| 150 | + }; |
| 151 | + } |
| 152 | +} |
| 153 | + |
| 154 | +// Request message for `CreateKey` method. |
| 155 | +message CreateKeyRequest { |
| 156 | + // Required. The project in which the API key is created. |
| 157 | + string parent = 1 [ |
| 158 | + (google.api.field_behavior) = REQUIRED, |
| 159 | + (google.api.resource_reference) = { |
| 160 | + child_type: "apikeys.googleapis.com/Key" |
| 161 | + } |
| 162 | + ]; |
| 163 | + |
| 164 | + // Required. The API key fields to set at creation time. |
| 165 | + // You can configure only the `display_name`, `restrictions`, and |
| 166 | + // `annotations` fields. |
| 167 | + Key key = 2 [(google.api.field_behavior) = REQUIRED]; |
| 168 | + |
| 169 | + // User specified key id (optional). If specified, it will become the final |
| 170 | + // component of the key resource name. |
| 171 | + // |
| 172 | + // The id must be unique within the project, must conform with RFC-1034, |
| 173 | + // is restricted to lower-cased letters, and has a maximum length of 63 |
| 174 | + // characters. In another word, the id must match the regular |
| 175 | + // expression: `[a-z]([a-z0-9-]{0,61}[a-z0-9])?`. |
| 176 | + // |
| 177 | + // The id must NOT be a UUID-like string. |
| 178 | + string key_id = 3; |
| 179 | +} |
| 180 | + |
| 181 | +// Request message for `ListKeys` method. |
| 182 | +message ListKeysRequest { |
| 183 | + // Required. Lists all API keys associated with this project. |
| 184 | + string parent = 1 [ |
| 185 | + (google.api.field_behavior) = REQUIRED, |
| 186 | + (google.api.resource_reference) = { |
| 187 | + child_type: "apikeys.googleapis.com/Key" |
| 188 | + } |
| 189 | + ]; |
| 190 | + |
| 191 | + // Optional. Specifies the maximum number of results to be returned at a time. |
| 192 | + int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; |
| 193 | + |
| 194 | + // Optional. Requests a specific page of results. |
| 195 | + string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; |
| 196 | + |
| 197 | + // Optional. Indicate that keys deleted in the past 30 days should also be |
| 198 | + // returned. |
| 199 | + bool show_deleted = 6 [(google.api.field_behavior) = OPTIONAL]; |
| 200 | +} |
| 201 | + |
| 202 | +// Response message for `ListKeys` method. |
| 203 | +message ListKeysResponse { |
| 204 | + // A list of API keys. |
| 205 | + repeated Key keys = 1; |
| 206 | + |
| 207 | + // The pagination token for the next page of results. |
| 208 | + string next_page_token = 2; |
| 209 | +} |
| 210 | + |
| 211 | +// Request message for `GetKey` method. |
| 212 | +message GetKeyRequest { |
| 213 | + // Required. The resource name of the API key to get. |
| 214 | + string name = 1 [ |
| 215 | + (google.api.field_behavior) = REQUIRED, |
| 216 | + (google.api.resource_reference) = { type: "apikeys.googleapis.com/Key" } |
| 217 | + ]; |
| 218 | +} |
| 219 | + |
| 220 | +// Request message for `GetKeyString` method. |
| 221 | +message GetKeyStringRequest { |
| 222 | + // Required. The resource name of the API key to be retrieved. |
| 223 | + string name = 1 [ |
| 224 | + (google.api.field_behavior) = REQUIRED, |
| 225 | + (google.api.resource_reference) = { type: "apikeys.googleapis.com/Key" } |
| 226 | + ]; |
| 227 | +} |
| 228 | + |
| 229 | +// Response message for `GetKeyString` method. |
| 230 | +message GetKeyStringResponse { |
| 231 | + // An encrypted and signed value of the key. |
| 232 | + string key_string = 1; |
| 233 | +} |
| 234 | + |
| 235 | +// Request message for `UpdateKey` method. |
| 236 | +message UpdateKeyRequest { |
| 237 | + // Required. Set the `name` field to the resource name of the API key to be |
| 238 | + // updated. You can update only the `display_name`, `restrictions`, and |
| 239 | + // `annotations` fields. |
| 240 | + Key key = 1 [(google.api.field_behavior) = REQUIRED]; |
| 241 | + |
| 242 | + // The field mask specifies which fields to be updated as part of this |
| 243 | + // request. All other fields are ignored. |
| 244 | + // Mutable fields are: `display_name`, `restrictions`, and `annotations`. |
| 245 | + // If an update mask is not provided, the service treats it as an implied mask |
| 246 | + // equivalent to all allowed fields that are set on the wire. If the field |
| 247 | + // mask has a special value "*", the service treats it equivalent to replace |
| 248 | + // all allowed mutable fields. |
| 249 | + google.protobuf.FieldMask update_mask = 2; |
| 250 | +} |
| 251 | + |
| 252 | +// Request message for `DeleteKey` method. |
| 253 | +message DeleteKeyRequest { |
| 254 | + // Required. The resource name of the API key to be deleted. |
| 255 | + string name = 1 [ |
| 256 | + (google.api.field_behavior) = REQUIRED, |
| 257 | + (google.api.resource_reference) = { type: "apikeys.googleapis.com/Key" } |
| 258 | + ]; |
| 259 | + |
| 260 | + // Optional. The etag known to the client for the expected state of the key. |
| 261 | + // This is to be used for optimistic concurrency. |
| 262 | + string etag = 2 [(google.api.field_behavior) = OPTIONAL]; |
| 263 | +} |
| 264 | + |
| 265 | +// Request message for `UndeleteKey` method. |
| 266 | +message UndeleteKeyRequest { |
| 267 | + // Required. The resource name of the API key to be undeleted. |
| 268 | + string name = 1 [ |
| 269 | + (google.api.field_behavior) = REQUIRED, |
| 270 | + (google.api.resource_reference) = { type: "apikeys.googleapis.com/Key" } |
| 271 | + ]; |
| 272 | +} |
| 273 | + |
| 274 | +// Request message for `LookupKey` method. |
| 275 | +message LookupKeyRequest { |
| 276 | + // Required. Finds the project that owns the key string value. |
| 277 | + string key_string = 1 [(google.api.field_behavior) = REQUIRED]; |
| 278 | +} |
| 279 | + |
| 280 | +// Response message for `LookupKey` method. |
| 281 | +message LookupKeyResponse { |
| 282 | + // The project that owns the key with the value specified in the request. |
| 283 | + string parent = 1; |
| 284 | + |
| 285 | + // The resource name of the API key. If the API key has been purged, |
| 286 | + // resource name is empty. |
| 287 | + string name = 2; |
| 288 | +} |
0 commit comments