docs: update comments

Google APIs · copybara-github · commit 47444ff0e3c8 · 2025-01-26T06:08:34.000-08:00
docs: annotate output-only fields as such

PiperOrigin-RevId: 719865415
diff --git a/google/cloud/scheduler/v1/cloudscheduler.proto b/google/cloud/scheduler/v1/cloudscheduler.proto
@@ -161,11 +161,7 @@ message ListJobsRequest {
   // 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.
+  // [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs].
   string page_token = 6;
 }
 
diff --git a/google/cloud/scheduler/v1/cloudscheduler_v1.yaml b/google/cloud/scheduler/v1/cloudscheduler_v1.yaml
@@ -6,6 +6,7 @@ title: Cloud Scheduler API
 apis:
 - name: google.cloud.location.Locations
 - name: google.cloud.scheduler.v1.CloudScheduler
+- name: google.longrunning.Operations
 
 documentation:
   summary: Creates and manages jobs run on a regular recurring schedule.
@@ -16,15 +17,6 @@ documentation:
   - selector: google.cloud.location.Locations.ListLocations
     description: Lists information about the supported locations for this service.
 
-backend:
-  rules:
-  - selector: google.cloud.location.Locations.GetLocation
-    deadline: 30.0
-  - selector: google.cloud.location.Locations.ListLocations
-    deadline: 30.0
-  - selector: 'google.cloud.scheduler.v1.CloudScheduler.*'
-    deadline: 30.0
-
 http:
   rules:
   - selector: google.cloud.location.Locations.GetLocation
diff --git a/google/cloud/scheduler/v1/job.proto b/google/cloud/scheduler/v1/job.proto
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.cloud.scheduler.v1;
 
+import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/scheduler/v1/target.proto";
 import "google/protobuf/duration.proto";
@@ -33,6 +34,8 @@ message Job {
   option (google.api.resource) = {
     type: "cloudscheduler.googleapis.com/Job"
     pattern: "projects/{project}/locations/{location}/jobs/{job}"
+    plural: "jobs"
+    singular: "job"
   };
 
   // State of the job.
@@ -125,7 +128,11 @@ message Job {
   // 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.
+  // with exponential backoff, until the next scheduled start time. If
+  // retry_count is 0, a job attempt will not be retried if it fails. Instead
+  // the Cloud Scheduler system will wait for the next scheduled execution time.
+  // Setting retry_count to 0 does not prevent failed jobs from running
+  // according to schedule after the failure.
   string schedule = 20;
 
   // Specifies the time zone to be used in interpreting
@@ -141,21 +148,24 @@ message Job {
   string time_zone = 21;
 
   // Output only. The creation time of the job.
-  google.protobuf.Timestamp user_update_time = 9;
+  google.protobuf.Timestamp user_update_time = 9
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. State of the job.
-  State state = 10;
+  State state = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The response from the target for the last attempted execution.
-  google.rpc.Status status = 11;
+  google.rpc.Status status = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The next time the job is scheduled. Note that this may be a
   // retry of a previously failed attempt or the next execution time
   // according to the schedule.
-  google.protobuf.Timestamp schedule_time = 17;
+  google.protobuf.Timestamp schedule_time = 17
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The time the last job attempt started.
-  google.protobuf.Timestamp last_attempt_time = 18;
+  google.protobuf.Timestamp last_attempt_time = 18
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Settings that determine the retry behavior.
   RetryConfig retry_config = 19;
@@ -198,9 +208,10 @@ message RetryConfig {
   //
   // The default value of retry_count is zero.
   //
-  // If retry_count is zero, a job attempt will *not* be retried if
+  // If retry_count is 0, a job attempt will not be retried if
   // it fails. Instead the Cloud Scheduler system will wait for the
-  // next scheduled execution time.
+  // next scheduled execution time. Setting retry_count to 0 does not prevent
+  // failed jobs from running according to schedule after the failure.
   //
   // If retry_count is set to a non-zero number then Cloud Scheduler
   // will retry failed attempts, using exponential backoff,
@@ -245,7 +256,7 @@ message RetryConfig {
   // [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
+  // is 300s, and `max_doublings` is 3, then the 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]
diff --git a/google/cloud/scheduler/v1/target.proto b/google/cloud/scheduler/v1/target.proto
@@ -46,14 +46,20 @@ message HttpTarget {
   // Which HTTP method to use for the request.
   HttpMethod http_method = 2;
 
+  // HTTP request headers.
+  //
+  // This map contains the header field names and values.
+  //
   // The user can specify HTTP request headers to send with the job's
-  // HTTP request. This map contains the header field names and
-  // values. Repeated headers are not supported, but a header value can
-  // contain commas. These headers represent a subset of the headers
-  // that will accompany the job's HTTP request. Some HTTP request
-  // headers will be ignored or replaced. A partial list of headers that
-  // will be ignored or replaced is below:
-  // - Host: This will be computed by Cloud Scheduler and derived from
+  // HTTP request. Repeated headers are not supported, but a header value can
+  // contain commas.
+  //
+  // The following headers represent a subset of the headers
+  // that accompany the job's HTTP request. Some HTTP request
+  // headers are ignored or replaced. A partial list of headers that
+  // are ignored or replaced is below:
+  //
+  // * Host: This will be computed by Cloud Scheduler and derived from
   // [uri][google.cloud.scheduler.v1.HttpTarget.uri].
   // * `Content-Length`: This will be computed by Cloud Scheduler.
   // * `User-Agent`: This will be set to `"Google-Cloud-Scheduler"`.
@@ -65,6 +71,15 @@ message HttpTarget {
   // the unix-cron format, this header will contain the job schedule as an
   // offset of UTC parsed according to RFC3339.
   //
+  // If the job has a [body][google.cloud.scheduler.v1.HttpTarget.body] and the
+  // following headers are not set by the user, Cloud Scheduler sets default
+  // values:
+  //
+  // * `Content-Type`: This will be set to `"application/octet-stream"`. You
+  //   can override this default by explicitly setting `Content-Type` to a
+  //   particular media type when creating the job. For example, you can set
+  //   `Content-Type` to `"application/json"`.
+  //
   // The total size of headers must be less than 80KB.
   map<string, string> headers = 3;
 
@@ -144,20 +159,18 @@ message AppEngineHttpTarget {
   // the unix-cron format, this header will contain the job schedule as an
   // offset of UTC parsed according to RFC3339.
   //
-  // If the job has an
-  // [body][google.cloud.scheduler.v1.AppEngineHttpTarget.body], Cloud Scheduler
-  // sets the following headers:
+  // If the job has a [body][google.cloud.scheduler.v1.AppEngineHttpTarget.body]
+  // and the following headers are not set by the user, Cloud Scheduler sets
+  // default values:
   //
-  // * `Content-Type`: By default, the `Content-Type` header is set to
-  //   `"application/octet-stream"`. The default can be overridden by explictly
-  //   setting `Content-Type` to a particular media type when the job is
-  //   created.
-  //   For example, `Content-Type` can be set to `"application/json"`.
-  // * `Content-Length`: This is computed by Cloud Scheduler. This value is
-  //   output only. It cannot be changed.
+  // * `Content-Type`: This will be set to `"application/octet-stream"`. You
+  //   can override this default by explicitly setting `Content-Type` to a
+  //   particular media type when creating the job. For example, you can set
+  //   `Content-Type` to `"application/json"`.
   //
   // The headers below are output only. They cannot be set or overridden:
   //
+  // * `Content-Length`: This is computed by Cloud Scheduler.
   // * `X-Google-*`: For Google internal use only.
   // * `X-AppEngine-*`: For Google internal use only.
   //
