Skip to content

Commit

Permalink
feat: [scheduler] Location API methods (#4048)
Browse files Browse the repository at this point in the history 
* feat: Location API methods
docs: updated comments
chore: proto formatting

PiperOrigin-RevId: 513582719

Source-Link: googleapis/googleapis@822476c

Source-Link: googleapis/googleapis-gen@39ca527
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXNjaGVkdWxlci8uT3dsQm90LnlhbWwiLCJoIjoiMzljYTUyNzYwMTk5ZDExM2I1MWFkOGJkY2E3NWNlYTllMTFhOWU5OCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: Denis DelGrosso <[email protected]>
  • Loading branch information
@gcf-owl-bot @ddelgrosso1
3 people authored Mar 6, 2023
1 parent 3807117 commit 304eac5
Show file tree
Hide file tree
Showing 11 changed files with 506 additions and 145 deletions.
89 changes: 54 additions & 35 deletions packages/google-cloud-scheduler/protos/google/cloud/scheduler/v1/cloudscheduler.proto
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2019 Google LLC.
// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand All @@ -11,7 +11,6 @@
// 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";

Expand All @@ -35,7 +34,8 @@ option objc_class_prefix = "SCHEDULER";
// schedule asynchronous jobs.
service CloudScheduler {
option (google.api.default_host) = "cloudscheduler.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
option (google.api.oauth_scopes) =
"https://www.googleapis.com/auth/cloud-platform";

// Lists jobs.
rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) {
Expand Down Expand Up @@ -64,13 +64,14 @@ service CloudScheduler {

// Updates a job.
//
// If successful, the updated [Job][google.cloud.scheduler.v1.Job] is returned. If the job does
// not exist, `NOT_FOUND` is returned.
// If successful, the updated [Job][google.cloud.scheduler.v1.Job] is
// returned. If the job does not exist, `NOT_FOUND` is returned.
//
// If UpdateJob does not successfully return, it is possible for the
// job to be in an [Job.State.UPDATE_FAILED][google.cloud.scheduler.v1.Job.State.UPDATE_FAILED] state. A job in this state may
// not be executed. If this happens, retry the UpdateJob request
// until a successful response is received.
// job to be in an
// [Job.State.UPDATE_FAILED][google.cloud.scheduler.v1.Job.State.UPDATE_FAILED]
// state. A job in this state may not be executed. If this happens, retry the
// UpdateJob request until a successful response is received.
rpc UpdateJob(UpdateJobRequest) returns (Job) {
option (google.api.http) = {
patch: "/v1/{job.name=projects/*/locations/*/jobs/*}"
Expand All @@ -90,10 +91,13 @@ service CloudScheduler {
// Pauses a job.
//
// If a job is paused then the system will stop executing the job
// until it is re-enabled via [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob]. The
// state of the job is stored in [state][google.cloud.scheduler.v1.Job.state]; if paused it
// will be set to [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. A job must be in [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED]
// to be paused.
// until it is re-enabled via
// [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob]. The state
// of the job is stored in [state][google.cloud.scheduler.v1.Job.state]; if
// paused it will be set to
// [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. A job must
// be in [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED] to
// be paused.
rpc PauseJob(PauseJobRequest) returns (Job) {
option (google.api.http) = {
post: "/v1/{name=projects/*/locations/*/jobs/*}:pause"
Expand All @@ -104,10 +108,13 @@ service CloudScheduler {

// Resume a job.
//
// This method reenables a job after it has been [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. The
// state of a job is stored in [Job.state][google.cloud.scheduler.v1.Job.state]; after calling this method it
// will be set to [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED]. A job must be in
// [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED] to be resumed.
// This method reenables a job after it has been
// [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. The state
// of a job is stored in [Job.state][google.cloud.scheduler.v1.Job.state];
// after calling this method it will be set to
// [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED]. A job
// must be in [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]
// to be resumed.
rpc ResumeJob(ResumeJobRequest) returns (Job) {
option (google.api.http) = {
post: "/v1/{name=projects/*/locations/*/jobs/*}:resume"
Expand All @@ -129,7 +136,8 @@ service CloudScheduler {
}
}

// Request message for listing jobs using [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
// Request message for listing jobs using
// [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
message ListJobsRequest {
// Required. The location name. For example:
// `projects/PROJECT_ID/locations/LOCATION_ID`.
Expand All @@ -151,29 +159,35 @@ message ListJobsRequest {
// A token identifying a page of results the server will return. To
// request the first page results, page_token must be empty. To
// request the next page of results, page_token must be the value of
// [next_page_token][google.cloud.scheduler.v1.ListJobsResponse.next_page_token] returned from
// the previous call to [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. It is an error to
// switch the value of [filter][google.cloud.scheduler.v1.ListJobsRequest.filter] or
// [order_by][google.cloud.scheduler.v1.ListJobsRequest.order_by] while iterating through pages.
// [next_page_token][google.cloud.scheduler.v1.ListJobsResponse.next_page_token]
// returned from the previous call to
// [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. It is an
// error to switch the value of
// [filter][google.cloud.scheduler.v1.ListJobsRequest.filter] or
// [order_by][google.cloud.scheduler.v1.ListJobsRequest.order_by] while
// iterating through pages.
string page_token = 6;
}

// Response message for listing jobs using [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
// Response message for listing jobs using
// [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
message ListJobsResponse {
// The list of jobs.
repeated Job jobs = 1;

// A token to retrieve next page of results. Pass this value in the
// [page_token][google.cloud.scheduler.v1.ListJobsRequest.page_token] field in the subsequent call to
// [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs] to retrieve the next page of results.
// If this is empty it indicates that there are no more results
// through which to paginate.
// [page_token][google.cloud.scheduler.v1.ListJobsRequest.page_token] field in
// the subsequent call to
// [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs] to retrieve
// the next page of results. If this is empty it indicates that there are no
// more results through which to paginate.
//
// The page token is valid for only 2 hours.
string next_page_token = 2;
}

// Request message for [GetJob][google.cloud.scheduler.v1.CloudScheduler.GetJob].
// Request message for
// [GetJob][google.cloud.scheduler.v1.CloudScheduler.GetJob].
message GetJobRequest {
// Required. The job name. For example:
// `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
Expand All @@ -185,7 +199,8 @@ message GetJobRequest {
];
}

// Request message for [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob].
// Request message for
// [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob].
message CreateJobRequest {
// Required. The location name. For example:
// `projects/PROJECT_ID/locations/LOCATION_ID`.
Expand All @@ -197,24 +212,26 @@ message CreateJobRequest {
];

// Required. The job to add. The user can optionally specify a name for the
// job in [name][google.cloud.scheduler.v1.Job.name]. [name][google.cloud.scheduler.v1.Job.name] cannot be the same as an
// job in [name][google.cloud.scheduler.v1.Job.name].
// [name][google.cloud.scheduler.v1.Job.name] cannot be the same as an
// existing job. If a name is not specified then the system will
// generate a random unique name that will be returned
// ([name][google.cloud.scheduler.v1.Job.name]) in the response.
Job job = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
// Request message for
// [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
message UpdateJobRequest {
// Required. The new job properties. [name][google.cloud.scheduler.v1.Job.name] must be specified.
// Required. The new job properties.
// [name][google.cloud.scheduler.v1.Job.name] must be specified.
//
// Output only fields cannot be modified using UpdateJob.
// Any value specified for an output only field will be ignored.
Job job = 1 [(google.api.field_behavior) = REQUIRED];

// A mask used to specify which fields of the job are being updated.
google.protobuf.FieldMask update_mask = 2
[(google.api.field_behavior) = REQUIRED];
google.protobuf.FieldMask update_mask = 2;
}

// Request message for deleting a job using
Expand All @@ -230,7 +247,8 @@ message DeleteJobRequest {
];
}

// Request message for [PauseJob][google.cloud.scheduler.v1.CloudScheduler.PauseJob].
// Request message for
// [PauseJob][google.cloud.scheduler.v1.CloudScheduler.PauseJob].
message PauseJobRequest {
// Required. The job name. For example:
// `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
Expand All @@ -242,7 +260,8 @@ message PauseJobRequest {
];
}

// Request message for [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob].
// Request message for
// [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob].
message ResumeJobRequest {
// Required. The job name. For example:
// `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`.
Expand Down
93 changes: 58 additions & 35 deletions packages/google-cloud-scheduler/protos/google/cloud/scheduler/v1/job.proto
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2019 Google LLC.
// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand All @@ -11,7 +11,6 @@
// 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";

Expand All @@ -29,7 +28,7 @@ option java_outer_classname = "JobProto";
option java_package = "com.google.cloud.scheduler.v1";

// Configuration for a job.
// The maximum allowed size for a job is 100KB.
// The maximum allowed size for a job is 1MB.
message Job {
option (google.api.resource) = {
type: "cloudscheduler.googleapis.com/Job"
Expand All @@ -53,13 +52,16 @@ message Job {
// cannot directly set a job to be disabled.
DISABLED = 3;

// The job state resulting from a failed [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]
// The job state resulting from a failed
// [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]
// operation. To recover a job from this state, retry
// [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob] until a successful response is received.
// [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]
// until a successful response is received.
UPDATE_FAILED = 4;
}

// Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob], after
// Optionally caller-specified in
// [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob], after
// which it becomes output only.
//
// The job name. For example:
Expand All @@ -78,7 +80,8 @@ message Job {
// hyphens (-), or underscores (_). The maximum length is 500 characters.
string name = 1;

// Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob] or
// Optionally caller-specified in
// [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob] or
// [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
//
// A human-readable description for the job. This string must not contain
Expand All @@ -99,13 +102,14 @@ message Job {
HttpTarget http_target = 6;
}

// Required, except when used with [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
// Required, except when used with
// [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob].
//
// Describes the schedule on which the job will be executed.
//
// The schedule can be either of the following types:
//
// * [Crontab](http://en.wikipedia.org/wiki/Cron#Overview)
// * [Crontab](https://en.wikipedia.org/wiki/Cron#Overview)
// * English-like
// [schedule](https://cloud.google.com/scheduler/docs/configuring/cron-job-schedules)
//
Expand All @@ -118,15 +122,16 @@ message Job {
// A scheduled start time will be delayed if the previous
// execution has not ended when its scheduled time occurs.
//
// If [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] > 0 and a job attempt fails,
// the job will be tried a total of [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count]
// times, with exponential backoff, until the next scheduled start
// time.
// If [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] > 0 and
// a job attempt fails, the job will be tried a total of
// [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times,
// with exponential backoff, until the next scheduled start time.
string schedule = 20;

// Specifies the time zone to be used in interpreting
// [schedule][google.cloud.scheduler.v1.Job.schedule]. The value of this field must be a time
// zone name from the [tz database](http://en.wikipedia.org/wiki/Tz_database).
// [schedule][google.cloud.scheduler.v1.Job.schedule]. The value of this field
// must be a time zone name from the [tz
// database](http://en.wikipedia.org/wiki/Tz_database).
//
// Note that some time zones include a provision for
// daylight savings time. The rules for daylight saving time are
Expand Down Expand Up @@ -161,18 +166,31 @@ message Job {
// execution logs. Cloud Scheduler will retry the job according
// to the [RetryConfig][google.cloud.scheduler.v1.RetryConfig].
//
// The allowed duration for this deadline is:
// * For [HTTP targets][google.cloud.scheduler.v1.Job.http_target], between 15 seconds and 30 minutes.
// * For [App Engine HTTP targets][google.cloud.scheduler.v1.Job.app_engine_http_target], between 15
// seconds and 24 hours.
// The default and the allowed values depend on the type of target:
//
// * For [HTTP targets][google.cloud.scheduler.v1.Job.http_target], the
// default is 3 minutes. The deadline must be in the interval [15 seconds, 30
// minutes].
//
// * For [App Engine HTTP
// targets][google.cloud.scheduler.v1.Job.app_engine_http_target], 0 indicates
// that the request has the default deadline. The default deadline depends on
// the scaling type of the service: 10 minutes for standard apps with
// automatic scaling, 24 hours for standard apps with manual and basic
// scaling, and 60 minutes for flex apps. If the request deadline is set, it
// must be in the interval [15 seconds, 24 hours 15 seconds].
//
// * For [Pub/Sub targets][google.cloud.scheduler.v1.Job.pubsub_target], this
// field is ignored.
google.protobuf.Duration attempt_deadline = 22;
}

// Settings that determine the retry behavior.
//
// By default, if a job does not complete successfully (meaning that
// an acknowledgement is not received from the handler, then it will be retried
// with exponential backoff according to the settings in [RetryConfig][google.cloud.scheduler.v1.RetryConfig].
// with exponential backoff according to the settings in
// [RetryConfig][google.cloud.scheduler.v1.RetryConfig].
message RetryConfig {
// The number of attempts that the system will make to run a job using the
// exponential backoff procedure described by
Expand All @@ -194,8 +212,8 @@ message RetryConfig {

// The time limit for retrying a failed job, measured from time when an
// execution was first attempted. If specified with
// [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count], the job will be retried until both
// limits are reached.
// [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count], the job
// will be retried until both limits are reached.
//
// The default value for max_retry_duration is zero, which means retry
// duration is unlimited.
Expand All @@ -216,20 +234,25 @@ message RetryConfig {
// The time between retries will double `max_doublings` times.
//
// A job's retry interval starts at
// [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration], then doubles
// `max_doublings` times, then increases linearly, and finally
// retries retries at intervals of
// [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] up to
// [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times.
// [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration],
// then doubles `max_doublings` times, then increases linearly, and finally
// retries at intervals of
// [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration]
// up to [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count]
// times.
//
// For example, if [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration] is
// 10s, [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] is 300s, and
// `max_doublings` is 3, then the a job will first be retried in 10s. The
// retry interval will double three times, and then increase linearly by
// 2^3 * 10s. Finally, the job will retry at intervals of
// [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] until the job has
// been attempted [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times. Thus, the
// requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s, ....
// For example, if
// [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration]
// is 10s,
// [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration]
// is 300s, and `max_doublings` is 3, then the a job will first be retried in
// 10s. The retry interval will double three times, and then increase linearly
// by 2^3 * 10s. Finally, the job will retry at intervals of
// [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration]
// until the job has been attempted
// [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times.
// Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s,
// 300s, ....
//
// The default value of this field is 5.
int32 max_doublings = 5;
Expand Down
Loading

0 comments on commit 304eac5

Please sign in to comment.