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/operation.proto"; 24import "google/cloud/aiplatform/v1/pipeline_job.proto"; 25import "google/cloud/aiplatform/v1/training_pipeline.proto"; 26import "google/longrunning/operations.proto"; 27import "google/protobuf/empty.proto"; 28import "google/protobuf/field_mask.proto"; 29 30option csharp_namespace = "Google.Cloud.AIPlatform.V1"; 31option go_package = "cloud.google.com/go/aiplatform/apiv1/aiplatformpb;aiplatformpb"; 32option java_multiple_files = true; 33option java_outer_classname = "PipelineServiceProto"; 34option java_package = "com.google.cloud.aiplatform.v1"; 35option php_namespace = "Google\\Cloud\\AIPlatform\\V1"; 36option ruby_package = "Google::Cloud::AIPlatform::V1"; 37 38// A service for creating and managing Vertex AI's pipelines. This includes both 39// `TrainingPipeline` resources (used for AutoML and custom training) and 40// `PipelineJob` resources (used for Vertex AI Pipelines). 41service PipelineService { 42 option (google.api.default_host) = "aiplatform.googleapis.com"; 43 option (google.api.oauth_scopes) = 44 "https://www.googleapis.com/auth/cloud-platform"; 45 46 // Creates a TrainingPipeline. A created TrainingPipeline right away will be 47 // attempted to be run. 48 rpc CreateTrainingPipeline(CreateTrainingPipelineRequest) 49 returns (TrainingPipeline) { 50 option (google.api.http) = { 51 post: "/v1/{parent=projects/*/locations/*}/trainingPipelines" 52 body: "training_pipeline" 53 }; 54 option (google.api.method_signature) = "parent,training_pipeline"; 55 } 56 57 // Gets a TrainingPipeline. 58 rpc GetTrainingPipeline(GetTrainingPipelineRequest) 59 returns (TrainingPipeline) { 60 option (google.api.http) = { 61 get: "/v1/{name=projects/*/locations/*/trainingPipelines/*}" 62 }; 63 option (google.api.method_signature) = "name"; 64 } 65 66 // Lists TrainingPipelines in a Location. 67 rpc ListTrainingPipelines(ListTrainingPipelinesRequest) 68 returns (ListTrainingPipelinesResponse) { 69 option (google.api.http) = { 70 get: "/v1/{parent=projects/*/locations/*}/trainingPipelines" 71 }; 72 option (google.api.method_signature) = "parent"; 73 } 74 75 // Deletes a TrainingPipeline. 76 rpc DeleteTrainingPipeline(DeleteTrainingPipelineRequest) 77 returns (google.longrunning.Operation) { 78 option (google.api.http) = { 79 delete: "/v1/{name=projects/*/locations/*/trainingPipelines/*}" 80 }; 81 option (google.api.method_signature) = "name"; 82 option (google.longrunning.operation_info) = { 83 response_type: "google.protobuf.Empty" 84 metadata_type: "DeleteOperationMetadata" 85 }; 86 } 87 88 // Cancels a TrainingPipeline. 89 // Starts asynchronous cancellation on the TrainingPipeline. The server 90 // makes a best effort to cancel the pipeline, but success is not 91 // guaranteed. Clients can use 92 // [PipelineService.GetTrainingPipeline][google.cloud.aiplatform.v1.PipelineService.GetTrainingPipeline] 93 // or other methods to check whether the cancellation succeeded or whether the 94 // pipeline completed despite cancellation. On successful cancellation, 95 // the TrainingPipeline is not deleted; instead it becomes a pipeline with 96 // a 97 // [TrainingPipeline.error][google.cloud.aiplatform.v1.TrainingPipeline.error] 98 // value with a [google.rpc.Status.code][google.rpc.Status.code] of 1, 99 // corresponding to `Code.CANCELLED`, and 100 // [TrainingPipeline.state][google.cloud.aiplatform.v1.TrainingPipeline.state] 101 // is set to `CANCELLED`. 102 rpc CancelTrainingPipeline(CancelTrainingPipelineRequest) 103 returns (google.protobuf.Empty) { 104 option (google.api.http) = { 105 post: "/v1/{name=projects/*/locations/*/trainingPipelines/*}:cancel" 106 body: "*" 107 }; 108 option (google.api.method_signature) = "name"; 109 } 110 111 // Creates a PipelineJob. A PipelineJob will run immediately when created. 112 rpc CreatePipelineJob(CreatePipelineJobRequest) returns (PipelineJob) { 113 option (google.api.http) = { 114 post: "/v1/{parent=projects/*/locations/*}/pipelineJobs" 115 body: "pipeline_job" 116 }; 117 option (google.api.method_signature) = 118 "parent,pipeline_job,pipeline_job_id"; 119 } 120 121 // Gets a PipelineJob. 122 rpc GetPipelineJob(GetPipelineJobRequest) returns (PipelineJob) { 123 option (google.api.http) = { 124 get: "/v1/{name=projects/*/locations/*/pipelineJobs/*}" 125 }; 126 option (google.api.method_signature) = "name"; 127 } 128 129 // Lists PipelineJobs in a Location. 130 rpc ListPipelineJobs(ListPipelineJobsRequest) 131 returns (ListPipelineJobsResponse) { 132 option (google.api.http) = { 133 get: "/v1/{parent=projects/*/locations/*}/pipelineJobs" 134 }; 135 option (google.api.method_signature) = "parent"; 136 } 137 138 // Deletes a PipelineJob. 139 rpc DeletePipelineJob(DeletePipelineJobRequest) 140 returns (google.longrunning.Operation) { 141 option (google.api.http) = { 142 delete: "/v1/{name=projects/*/locations/*/pipelineJobs/*}" 143 }; 144 option (google.api.method_signature) = "name"; 145 option (google.longrunning.operation_info) = { 146 response_type: "google.protobuf.Empty" 147 metadata_type: "DeleteOperationMetadata" 148 }; 149 } 150 151 // Cancels a PipelineJob. 152 // Starts asynchronous cancellation on the PipelineJob. The server 153 // makes a best effort to cancel the pipeline, but success is not 154 // guaranteed. Clients can use 155 // [PipelineService.GetPipelineJob][google.cloud.aiplatform.v1.PipelineService.GetPipelineJob] 156 // or other methods to check whether the cancellation succeeded or whether the 157 // pipeline completed despite cancellation. On successful cancellation, 158 // the PipelineJob is not deleted; instead it becomes a pipeline with 159 // a [PipelineJob.error][google.cloud.aiplatform.v1.PipelineJob.error] value 160 // with a [google.rpc.Status.code][google.rpc.Status.code] of 1, corresponding 161 // to `Code.CANCELLED`, and 162 // [PipelineJob.state][google.cloud.aiplatform.v1.PipelineJob.state] is set to 163 // `CANCELLED`. 164 rpc CancelPipelineJob(CancelPipelineJobRequest) 165 returns (google.protobuf.Empty) { 166 option (google.api.http) = { 167 post: "/v1/{name=projects/*/locations/*/pipelineJobs/*}:cancel" 168 body: "*" 169 }; 170 option (google.api.method_signature) = "name"; 171 } 172} 173 174// Request message for 175// [PipelineService.CreateTrainingPipeline][google.cloud.aiplatform.v1.PipelineService.CreateTrainingPipeline]. 176message CreateTrainingPipelineRequest { 177 // Required. The resource name of the Location to create the TrainingPipeline 178 // in. Format: `projects/{project}/locations/{location}` 179 string parent = 1 [ 180 (google.api.field_behavior) = REQUIRED, 181 (google.api.resource_reference) = { 182 type: "locations.googleapis.com/Location" 183 } 184 ]; 185 186 // Required. The TrainingPipeline to create. 187 TrainingPipeline training_pipeline = 2 188 [(google.api.field_behavior) = REQUIRED]; 189} 190 191// Request message for 192// [PipelineService.GetTrainingPipeline][google.cloud.aiplatform.v1.PipelineService.GetTrainingPipeline]. 193message GetTrainingPipelineRequest { 194 // Required. The name of the TrainingPipeline resource. 195 // Format: 196 // `projects/{project}/locations/{location}/trainingPipelines/{training_pipeline}` 197 string name = 1 [ 198 (google.api.field_behavior) = REQUIRED, 199 (google.api.resource_reference) = { 200 type: "aiplatform.googleapis.com/TrainingPipeline" 201 } 202 ]; 203} 204 205// Request message for 206// [PipelineService.ListTrainingPipelines][google.cloud.aiplatform.v1.PipelineService.ListTrainingPipelines]. 207message ListTrainingPipelinesRequest { 208 // Required. The resource name of the Location to list the TrainingPipelines 209 // from. Format: `projects/{project}/locations/{location}` 210 string parent = 1 [ 211 (google.api.field_behavior) = REQUIRED, 212 (google.api.resource_reference) = { 213 type: "locations.googleapis.com/Location" 214 } 215 ]; 216 217 // The standard list filter. 218 // 219 // Supported fields: 220 // 221 // * `display_name` supports `=`, `!=` comparisons, and `:` wildcard. 222 // * `state` supports `=`, `!=` comparisons. 223 // * `training_task_definition` `=`, `!=` comparisons, and `:` wildcard. 224 // * `create_time` supports `=`, `!=`,`<`, `<=`,`>`, `>=` comparisons. 225 // `create_time` must be in RFC 3339 format. 226 // * `labels` supports general map functions that is: 227 // `labels.key=value` - key:value equality 228 // `labels.key:* - key existence 229 // 230 // Some examples of using the filter are: 231 // 232 // * `state="PIPELINE_STATE_SUCCEEDED" AND display_name:"my_pipeline_*"` 233 // * `state!="PIPELINE_STATE_FAILED" OR display_name="my_pipeline"` 234 // * `NOT display_name="my_pipeline"` 235 // * `create_time>"2021-05-18T00:00:00Z"` 236 // * `training_task_definition:"*automl_text_classification*"` 237 string filter = 2; 238 239 // The standard list page size. 240 int32 page_size = 3; 241 242 // The standard list page token. 243 // Typically obtained via 244 // [ListTrainingPipelinesResponse.next_page_token][google.cloud.aiplatform.v1.ListTrainingPipelinesResponse.next_page_token] 245 // of the previous 246 // [PipelineService.ListTrainingPipelines][google.cloud.aiplatform.v1.PipelineService.ListTrainingPipelines] 247 // call. 248 string page_token = 4; 249 250 // Mask specifying which fields to read. 251 google.protobuf.FieldMask read_mask = 5; 252} 253 254// Response message for 255// [PipelineService.ListTrainingPipelines][google.cloud.aiplatform.v1.PipelineService.ListTrainingPipelines] 256message ListTrainingPipelinesResponse { 257 // List of TrainingPipelines in the requested page. 258 repeated TrainingPipeline training_pipelines = 1; 259 260 // A token to retrieve the next page of results. 261 // Pass to 262 // [ListTrainingPipelinesRequest.page_token][google.cloud.aiplatform.v1.ListTrainingPipelinesRequest.page_token] 263 // to obtain that page. 264 string next_page_token = 2; 265} 266 267// Request message for 268// [PipelineService.DeleteTrainingPipeline][google.cloud.aiplatform.v1.PipelineService.DeleteTrainingPipeline]. 269message DeleteTrainingPipelineRequest { 270 // Required. The name of the TrainingPipeline resource to be deleted. 271 // Format: 272 // `projects/{project}/locations/{location}/trainingPipelines/{training_pipeline}` 273 string name = 1 [ 274 (google.api.field_behavior) = REQUIRED, 275 (google.api.resource_reference) = { 276 type: "aiplatform.googleapis.com/TrainingPipeline" 277 } 278 ]; 279} 280 281// Request message for 282// [PipelineService.CancelTrainingPipeline][google.cloud.aiplatform.v1.PipelineService.CancelTrainingPipeline]. 283message CancelTrainingPipelineRequest { 284 // Required. The name of the TrainingPipeline to cancel. 285 // Format: 286 // `projects/{project}/locations/{location}/trainingPipelines/{training_pipeline}` 287 string name = 1 [ 288 (google.api.field_behavior) = REQUIRED, 289 (google.api.resource_reference) = { 290 type: "aiplatform.googleapis.com/TrainingPipeline" 291 } 292 ]; 293} 294 295// Request message for 296// [PipelineService.CreatePipelineJob][google.cloud.aiplatform.v1.PipelineService.CreatePipelineJob]. 297message CreatePipelineJobRequest { 298 // Required. The resource name of the Location to create the PipelineJob in. 299 // Format: `projects/{project}/locations/{location}` 300 string parent = 1 [ 301 (google.api.field_behavior) = REQUIRED, 302 (google.api.resource_reference) = { 303 type: "locations.googleapis.com/Location" 304 } 305 ]; 306 307 // Required. The PipelineJob to create. 308 PipelineJob pipeline_job = 2 [(google.api.field_behavior) = REQUIRED]; 309 310 // The ID to use for the PipelineJob, which will become the final component of 311 // the PipelineJob name. If not provided, an ID will be automatically 312 // generated. 313 // 314 // This value should be less than 128 characters, and valid characters 315 // are /[a-z][0-9]-/. 316 string pipeline_job_id = 3; 317} 318 319// Request message for 320// [PipelineService.GetPipelineJob][google.cloud.aiplatform.v1.PipelineService.GetPipelineJob]. 321message GetPipelineJobRequest { 322 // Required. The name of the PipelineJob resource. 323 // Format: 324 // `projects/{project}/locations/{location}/pipelineJobs/{pipeline_job}` 325 string name = 1 [ 326 (google.api.field_behavior) = REQUIRED, 327 (google.api.resource_reference) = { 328 type: "aiplatform.googleapis.com/PipelineJob" 329 } 330 ]; 331} 332 333// Request message for 334// [PipelineService.ListPipelineJobs][google.cloud.aiplatform.v1.PipelineService.ListPipelineJobs]. 335message ListPipelineJobsRequest { 336 // Required. The resource name of the Location to list the PipelineJobs from. 337 // Format: `projects/{project}/locations/{location}` 338 string parent = 1 [ 339 (google.api.field_behavior) = REQUIRED, 340 (google.api.resource_reference) = { 341 type: "locations.googleapis.com/Location" 342 } 343 ]; 344 345 // Lists the PipelineJobs that match the filter expression. The following 346 // fields are supported: 347 // 348 // * `pipeline_name`: Supports `=` and `!=` comparisons. 349 // * `display_name`: Supports `=`, `!=` comparisons, and `:` wildcard. 350 // * `pipeline_job_user_id`: Supports `=`, `!=` comparisons, and `:` wildcard. 351 // for example, can check if pipeline's display_name contains *step* by 352 // doing display_name:\"*step*\" 353 // * `state`: Supports `=` and `!=` comparisons. 354 // * `create_time`: Supports `=`, `!=`, `<`, `>`, `<=`, and `>=` comparisons. 355 // Values must be in RFC 3339 format. 356 // * `update_time`: Supports `=`, `!=`, `<`, `>`, `<=`, and `>=` comparisons. 357 // Values must be in RFC 3339 format. 358 // * `end_time`: Supports `=`, `!=`, `<`, `>`, `<=`, and `>=` comparisons. 359 // Values must be in RFC 3339 format. 360 // * `labels`: Supports key-value equality and key presence. 361 // * `template_uri`: Supports `=`, `!=` comparisons, and `:` wildcard. 362 // * `template_metadata.version`: Supports `=`, `!=` comparisons, and `:` 363 // wildcard. 364 // 365 // Filter expressions can be combined together using logical operators 366 // (`AND` & `OR`). 367 // For example: `pipeline_name="test" AND create_time>"2020-05-18T13:30:00Z"`. 368 // 369 // The syntax to define filter expression is based on 370 // https://google.aip.dev/160. 371 // 372 // Examples: 373 // 374 // * `create_time>"2021-05-18T00:00:00Z" OR 375 // update_time>"2020-05-18T00:00:00Z"` PipelineJobs created or updated 376 // after 2020-05-18 00:00:00 UTC. 377 // * `labels.env = "prod"` 378 // PipelineJobs with label "env" set to "prod". 379 string filter = 2; 380 381 // The standard list page size. 382 int32 page_size = 3; 383 384 // The standard list page token. 385 // Typically obtained via 386 // [ListPipelineJobsResponse.next_page_token][google.cloud.aiplatform.v1.ListPipelineJobsResponse.next_page_token] 387 // of the previous 388 // [PipelineService.ListPipelineJobs][google.cloud.aiplatform.v1.PipelineService.ListPipelineJobs] 389 // call. 390 string page_token = 4; 391 392 // A comma-separated list of fields to order by. The default sort order is in 393 // ascending order. Use "desc" after a field name for descending. You can have 394 // multiple order_by fields provided e.g. "create_time desc, end_time", 395 // "end_time, start_time, update_time" For example, using "create_time desc, 396 // end_time" will order results by create time in descending order, and if 397 // there are multiple jobs having the same create time, order them by the end 398 // time in ascending order. if order_by is not specified, it will order by 399 // default order is create time in descending order. Supported fields: 400 // 401 // * `create_time` 402 // * `update_time` 403 // * `end_time` 404 // * `start_time` 405 string order_by = 6; 406 407 // Mask specifying which fields to read. 408 google.protobuf.FieldMask read_mask = 7; 409} 410 411// Response message for 412// [PipelineService.ListPipelineJobs][google.cloud.aiplatform.v1.PipelineService.ListPipelineJobs] 413message ListPipelineJobsResponse { 414 // List of PipelineJobs in the requested page. 415 repeated PipelineJob pipeline_jobs = 1; 416 417 // A token to retrieve the next page of results. 418 // Pass to 419 // [ListPipelineJobsRequest.page_token][google.cloud.aiplatform.v1.ListPipelineJobsRequest.page_token] 420 // to obtain that page. 421 string next_page_token = 2; 422} 423 424// Request message for 425// [PipelineService.DeletePipelineJob][google.cloud.aiplatform.v1.PipelineService.DeletePipelineJob]. 426message DeletePipelineJobRequest { 427 // Required. The name of the PipelineJob resource to be deleted. 428 // Format: 429 // `projects/{project}/locations/{location}/pipelineJobs/{pipeline_job}` 430 string name = 1 [ 431 (google.api.field_behavior) = REQUIRED, 432 (google.api.resource_reference) = { 433 type: "aiplatform.googleapis.com/PipelineJob" 434 } 435 ]; 436} 437 438// Request message for 439// [PipelineService.CancelPipelineJob][google.cloud.aiplatform.v1.PipelineService.CancelPipelineJob]. 440message CancelPipelineJobRequest { 441 // Required. The name of the PipelineJob to cancel. 442 // Format: 443 // `projects/{project}/locations/{location}/pipelineJobs/{pipeline_job}` 444 string name = 1 [ 445 (google.api.field_behavior) = REQUIRED, 446 (google.api.resource_reference) = { 447 type: "aiplatform.googleapis.com/PipelineJob" 448 } 449 ]; 450} 451