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.cloud.aiplatform.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/cloud/aiplatform/v1/endpoint.proto";
24import "google/cloud/aiplatform/v1/operation.proto";
25import "google/longrunning/operations.proto";
26import "google/protobuf/empty.proto";
27import "google/protobuf/field_mask.proto";
28
29option csharp_namespace = "Google.Cloud.AIPlatform.V1";
30option go_package = "cloud.google.com/go/aiplatform/apiv1/aiplatformpb;aiplatformpb";
31option java_multiple_files = true;
32option java_outer_classname = "EndpointServiceProto";
33option java_package = "com.google.cloud.aiplatform.v1";
34option php_namespace = "Google\\Cloud\\AIPlatform\\V1";
35option ruby_package = "Google::Cloud::AIPlatform::V1";
36
37// A service for managing Vertex AI's Endpoints.
38service EndpointService {
39  option (google.api.default_host) = "aiplatform.googleapis.com";
40  option (google.api.oauth_scopes) =
41      "https://www.googleapis.com/auth/cloud-platform";
42
43  // Creates an Endpoint.
44  rpc CreateEndpoint(CreateEndpointRequest)
45      returns (google.longrunning.Operation) {
46    option (google.api.http) = {
47      post: "/v1/{parent=projects/*/locations/*}/endpoints"
48      body: "endpoint"
49    };
50    option (google.api.method_signature) = "parent,endpoint";
51    option (google.api.method_signature) = "parent,endpoint,endpoint_id";
52    option (google.longrunning.operation_info) = {
53      response_type: "Endpoint"
54      metadata_type: "CreateEndpointOperationMetadata"
55    };
56  }
57
58  // Gets an Endpoint.
59  rpc GetEndpoint(GetEndpointRequest) returns (Endpoint) {
60    option (google.api.http) = {
61      get: "/v1/{name=projects/*/locations/*/endpoints/*}"
62    };
63    option (google.api.method_signature) = "name";
64  }
65
66  // Lists Endpoints in a Location.
67  rpc ListEndpoints(ListEndpointsRequest) returns (ListEndpointsResponse) {
68    option (google.api.http) = {
69      get: "/v1/{parent=projects/*/locations/*}/endpoints"
70    };
71    option (google.api.method_signature) = "parent";
72  }
73
74  // Updates an Endpoint.
75  rpc UpdateEndpoint(UpdateEndpointRequest) returns (Endpoint) {
76    option (google.api.http) = {
77      patch: "/v1/{endpoint.name=projects/*/locations/*/endpoints/*}"
78      body: "endpoint"
79    };
80    option (google.api.method_signature) = "endpoint,update_mask";
81  }
82
83  // Deletes an Endpoint.
84  rpc DeleteEndpoint(DeleteEndpointRequest)
85      returns (google.longrunning.Operation) {
86    option (google.api.http) = {
87      delete: "/v1/{name=projects/*/locations/*/endpoints/*}"
88    };
89    option (google.api.method_signature) = "name";
90    option (google.longrunning.operation_info) = {
91      response_type: "google.protobuf.Empty"
92      metadata_type: "DeleteOperationMetadata"
93    };
94  }
95
96  // Deploys a Model into this Endpoint, creating a DeployedModel within it.
97  rpc DeployModel(DeployModelRequest) returns (google.longrunning.Operation) {
98    option (google.api.http) = {
99      post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:deployModel"
100      body: "*"
101    };
102    option (google.api.method_signature) =
103        "endpoint,deployed_model,traffic_split";
104    option (google.longrunning.operation_info) = {
105      response_type: "DeployModelResponse"
106      metadata_type: "DeployModelOperationMetadata"
107    };
108  }
109
110  // Undeploys a Model from an Endpoint, removing a DeployedModel from it, and
111  // freeing all resources it's using.
112  rpc UndeployModel(UndeployModelRequest)
113      returns (google.longrunning.Operation) {
114    option (google.api.http) = {
115      post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:undeployModel"
116      body: "*"
117    };
118    option (google.api.method_signature) =
119        "endpoint,deployed_model_id,traffic_split";
120    option (google.longrunning.operation_info) = {
121      response_type: "UndeployModelResponse"
122      metadata_type: "UndeployModelOperationMetadata"
123    };
124  }
125
126  // Updates an existing deployed model. Updatable fields include
127  // `min_replica_count`, `max_replica_count`, `autoscaling_metric_specs`,
128  // `disable_container_logging` (v1 only), and `enable_container_logging`
129  // (v1beta1 only).
130  rpc MutateDeployedModel(MutateDeployedModelRequest)
131      returns (google.longrunning.Operation) {
132    option (google.api.http) = {
133      post: "/v1/{endpoint=projects/*/locations/*/endpoints/*}:mutateDeployedModel"
134      body: "*"
135    };
136    option (google.api.method_signature) =
137        "endpoint,deployed_model,update_mask";
138    option (google.longrunning.operation_info) = {
139      response_type: "MutateDeployedModelResponse"
140      metadata_type: "MutateDeployedModelOperationMetadata"
141    };
142  }
143}
144
145// Request message for
146// [EndpointService.CreateEndpoint][google.cloud.aiplatform.v1.EndpointService.CreateEndpoint].
147message CreateEndpointRequest {
148  // Required. The resource name of the Location to create the Endpoint in.
149  // Format: `projects/{project}/locations/{location}`
150  string parent = 1 [
151    (google.api.field_behavior) = REQUIRED,
152    (google.api.resource_reference) = {
153      type: "locations.googleapis.com/Location"
154    }
155  ];
156
157  // Required. The Endpoint to create.
158  Endpoint endpoint = 2 [(google.api.field_behavior) = REQUIRED];
159
160  // Immutable. The ID to use for endpoint, which will become the final
161  // component of the endpoint resource name.
162  // If not provided, Vertex AI will generate a value for this ID.
163  //
164  // If the first character is a letter, this value may be up to 63 characters,
165  // and valid characters are `[a-z0-9-]`. The last character must be a letter
166  // or number.
167  //
168  // If the first character is a number, this value may be up to 9 characters,
169  // and valid characters are `[0-9]` with no leading zeros.
170  //
171  // When using HTTP/JSON, this field is populated
172  // based on a query string argument, such as `?endpoint_id=12345`. This is the
173  // fallback for fields that are not included in either the URI or the body.
174  string endpoint_id = 4 [(google.api.field_behavior) = IMMUTABLE];
175}
176
177// Runtime operation information for
178// [EndpointService.CreateEndpoint][google.cloud.aiplatform.v1.EndpointService.CreateEndpoint].
179message CreateEndpointOperationMetadata {
180  // The operation generic information.
181  GenericOperationMetadata generic_metadata = 1;
182}
183
184// Request message for
185// [EndpointService.GetEndpoint][google.cloud.aiplatform.v1.EndpointService.GetEndpoint]
186message GetEndpointRequest {
187  // Required. The name of the Endpoint resource.
188  // Format:
189  // `projects/{project}/locations/{location}/endpoints/{endpoint}`
190  string name = 1 [
191    (google.api.field_behavior) = REQUIRED,
192    (google.api.resource_reference) = {
193      type: "aiplatform.googleapis.com/Endpoint"
194    }
195  ];
196}
197
198// Request message for
199// [EndpointService.ListEndpoints][google.cloud.aiplatform.v1.EndpointService.ListEndpoints].
200message ListEndpointsRequest {
201  // Required. The resource name of the Location from which to list the
202  // Endpoints. Format: `projects/{project}/locations/{location}`
203  string parent = 1 [
204    (google.api.field_behavior) = REQUIRED,
205    (google.api.resource_reference) = {
206      type: "locations.googleapis.com/Location"
207    }
208  ];
209
210  // Optional. An expression for filtering the results of the request. For field
211  // names both snake_case and camelCase are supported.
212  //
213  //   * `endpoint` supports = and !=. `endpoint` represents the Endpoint ID,
214  //     i.e. the last segment of the Endpoint's [resource
215  //     name][google.cloud.aiplatform.v1.Endpoint.name].
216  //   * `display_name` supports = and, !=
217  //   * `labels` supports general map functions that is:
218  //     * `labels.key=value` - key:value equality
219  //     * `labels.key:* or labels:key - key existence
220  //     * A key including a space must be quoted. `labels."a key"`.
221  //
222  // Some examples:
223  //   * `endpoint=1`
224  //   * `displayName="myDisplayName"`
225  //   * `labels.myKey="myValue"`
226  string filter = 2 [(google.api.field_behavior) = OPTIONAL];
227
228  // Optional. The standard list page size.
229  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];
230
231  // Optional. The standard list page token.
232  // Typically obtained via
233  // [ListEndpointsResponse.next_page_token][google.cloud.aiplatform.v1.ListEndpointsResponse.next_page_token]
234  // of the previous
235  // [EndpointService.ListEndpoints][google.cloud.aiplatform.v1.EndpointService.ListEndpoints]
236  // call.
237  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
238
239  // Optional. Mask specifying which fields to read.
240  google.protobuf.FieldMask read_mask = 5
241      [(google.api.field_behavior) = OPTIONAL];
242
243  // A comma-separated list of fields to order by, sorted in ascending order.
244  // Use "desc" after a field name for descending.
245  // Supported fields:
246  //   * `display_name`
247  //   * `create_time`
248  //   * `update_time`
249  //
250  // Example: `display_name, create_time desc`.
251  string order_by = 6;
252}
253
254// Response message for
255// [EndpointService.ListEndpoints][google.cloud.aiplatform.v1.EndpointService.ListEndpoints].
256message ListEndpointsResponse {
257  // List of Endpoints in the requested page.
258  repeated Endpoint endpoints = 1;
259
260  // A token to retrieve the next page of results.
261  // Pass to
262  // [ListEndpointsRequest.page_token][google.cloud.aiplatform.v1.ListEndpointsRequest.page_token]
263  // to obtain that page.
264  string next_page_token = 2;
265}
266
267// Request message for
268// [EndpointService.UpdateEndpoint][google.cloud.aiplatform.v1.EndpointService.UpdateEndpoint].
269message UpdateEndpointRequest {
270  // Required. The Endpoint which replaces the resource on the server.
271  Endpoint endpoint = 1 [(google.api.field_behavior) = REQUIRED];
272
273  // Required. The update mask applies to the resource. See
274  // [google.protobuf.FieldMask][google.protobuf.FieldMask].
275  google.protobuf.FieldMask update_mask = 2
276      [(google.api.field_behavior) = REQUIRED];
277}
278
279// Request message for
280// [EndpointService.DeleteEndpoint][google.cloud.aiplatform.v1.EndpointService.DeleteEndpoint].
281message DeleteEndpointRequest {
282  // Required. The name of the Endpoint resource to be deleted.
283  // Format:
284  // `projects/{project}/locations/{location}/endpoints/{endpoint}`
285  string name = 1 [
286    (google.api.field_behavior) = REQUIRED,
287    (google.api.resource_reference) = {
288      type: "aiplatform.googleapis.com/Endpoint"
289    }
290  ];
291}
292
293// Request message for
294// [EndpointService.DeployModel][google.cloud.aiplatform.v1.EndpointService.DeployModel].
295message DeployModelRequest {
296  // Required. The name of the Endpoint resource into which to deploy a Model.
297  // Format:
298  // `projects/{project}/locations/{location}/endpoints/{endpoint}`
299  string endpoint = 1 [
300    (google.api.field_behavior) = REQUIRED,
301    (google.api.resource_reference) = {
302      type: "aiplatform.googleapis.com/Endpoint"
303    }
304  ];
305
306  // Required. The DeployedModel to be created within the Endpoint. Note that
307  // [Endpoint.traffic_split][google.cloud.aiplatform.v1.Endpoint.traffic_split]
308  // must be updated for the DeployedModel to start receiving traffic, either as
309  // part of this call, or via
310  // [EndpointService.UpdateEndpoint][google.cloud.aiplatform.v1.EndpointService.UpdateEndpoint].
311  DeployedModel deployed_model = 2 [(google.api.field_behavior) = REQUIRED];
312
313  // A map from a DeployedModel's ID to the percentage of this Endpoint's
314  // traffic that should be forwarded to that DeployedModel.
315  //
316  // If this field is non-empty, then the Endpoint's
317  // [traffic_split][google.cloud.aiplatform.v1.Endpoint.traffic_split] will be
318  // overwritten with it. To refer to the ID of the just being deployed Model, a
319  // "0" should be used, and the actual ID of the new DeployedModel will be
320  // filled in its place by this method. The traffic percentage values must add
321  // up to 100.
322  //
323  // If this field is empty, then the Endpoint's
324  // [traffic_split][google.cloud.aiplatform.v1.Endpoint.traffic_split] is not
325  // updated.
326  map<string, int32> traffic_split = 3;
327}
328
329// Response message for
330// [EndpointService.DeployModel][google.cloud.aiplatform.v1.EndpointService.DeployModel].
331message DeployModelResponse {
332  // The DeployedModel that had been deployed in the Endpoint.
333  DeployedModel deployed_model = 1;
334}
335
336// Runtime operation information for
337// [EndpointService.DeployModel][google.cloud.aiplatform.v1.EndpointService.DeployModel].
338message DeployModelOperationMetadata {
339  // The operation generic information.
340  GenericOperationMetadata generic_metadata = 1;
341}
342
343// Request message for
344// [EndpointService.UndeployModel][google.cloud.aiplatform.v1.EndpointService.UndeployModel].
345message UndeployModelRequest {
346  // Required. The name of the Endpoint resource from which to undeploy a Model.
347  // Format:
348  // `projects/{project}/locations/{location}/endpoints/{endpoint}`
349  string endpoint = 1 [
350    (google.api.field_behavior) = REQUIRED,
351    (google.api.resource_reference) = {
352      type: "aiplatform.googleapis.com/Endpoint"
353    }
354  ];
355
356  // Required. The ID of the DeployedModel to be undeployed from the Endpoint.
357  string deployed_model_id = 2 [(google.api.field_behavior) = REQUIRED];
358
359  // If this field is provided, then the Endpoint's
360  // [traffic_split][google.cloud.aiplatform.v1.Endpoint.traffic_split] will be
361  // overwritten with it. If last DeployedModel is being undeployed from the
362  // Endpoint, the [Endpoint.traffic_split] will always end up empty when this
363  // call returns. A DeployedModel will be successfully undeployed only if it
364  // doesn't have any traffic assigned to it when this method executes, or if
365  // this field unassigns any traffic to it.
366  map<string, int32> traffic_split = 3;
367}
368
369// Response message for
370// [EndpointService.UndeployModel][google.cloud.aiplatform.v1.EndpointService.UndeployModel].
371message UndeployModelResponse {}
372
373// Runtime operation information for
374// [EndpointService.UndeployModel][google.cloud.aiplatform.v1.EndpointService.UndeployModel].
375message UndeployModelOperationMetadata {
376  // The operation generic information.
377  GenericOperationMetadata generic_metadata = 1;
378}
379
380// Request message for
381// [EndpointService.MutateDeployedModel][google.cloud.aiplatform.v1.EndpointService.MutateDeployedModel].
382message MutateDeployedModelRequest {
383  // Required. The name of the Endpoint resource into which to mutate a
384  // DeployedModel. Format:
385  // `projects/{project}/locations/{location}/endpoints/{endpoint}`
386  string endpoint = 1 [
387    (google.api.field_behavior) = REQUIRED,
388    (google.api.resource_reference) = {
389      type: "aiplatform.googleapis.com/Endpoint"
390    }
391  ];
392
393  // Required. The DeployedModel to be mutated within the Endpoint. Only the
394  // following fields can be mutated:
395  //
396  // * `min_replica_count` in either
397  // [DedicatedResources][google.cloud.aiplatform.v1.DedicatedResources] or
398  // [AutomaticResources][google.cloud.aiplatform.v1.AutomaticResources]
399  // * `max_replica_count` in either
400  // [DedicatedResources][google.cloud.aiplatform.v1.DedicatedResources] or
401  // [AutomaticResources][google.cloud.aiplatform.v1.AutomaticResources]
402  // * [autoscaling_metric_specs][google.cloud.aiplatform.v1.DedicatedResources.autoscaling_metric_specs]
403  // * `disable_container_logging` (v1 only)
404  // * `enable_container_logging` (v1beta1 only)
405  DeployedModel deployed_model = 2 [(google.api.field_behavior) = REQUIRED];
406
407  // Required. The update mask applies to the resource. See
408  // [google.protobuf.FieldMask][google.protobuf.FieldMask].
409  google.protobuf.FieldMask update_mask = 4
410      [(google.api.field_behavior) = REQUIRED];
411}
412
413// Response message for
414// [EndpointService.MutateDeployedModel][google.cloud.aiplatform.v1.EndpointService.MutateDeployedModel].
415message MutateDeployedModelResponse {
416  // The DeployedModel that's being mutated.
417  DeployedModel deployed_model = 1;
418}
419
420// Runtime operation information for
421// [EndpointService.MutateDeployedModel][google.cloud.aiplatform.v1.EndpointService.MutateDeployedModel].
422message MutateDeployedModelOperationMetadata {
423  // The operation generic information.
424  GenericOperationMetadata generic_metadata = 1;
425}
426