feat(json): updated API descriptions

2026-02-23 15:49:49 +01:00 · 2016-01-30 14:05:22 +01:00
parent a2c6b58d5b
commit 8f01e8e918
145 changed files with 50073 additions and 3975 deletions
--- a/etc/api/dataflow/v1b3/dataflow-api.json
+++ b/etc/api/dataflow/v1b3/dataflow-api.json
@@ -1,11 +1,11 @@
 {
 "kind": "discovery#restDescription",
- "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/5KuD_AhxWtT--XElMYogfy5V-SU\"",
+ "etag": "\"bRFOOrZKfO9LweMbPqu0kcu6De8/z_qEBVG4geak7DrKYhi9NJcxQa4\"",
 "discoveryVersion": "v1",
 "id": "dataflow:v1b3",
 "name": "dataflow",
 "version": "v1b3",
- "revision": "20150401",
+ "revision": "20160123",
 "title": "Google Dataflow API",
 "description": "Google Dataflow API.",
 "ownerDomain": "google.com",
@@ -17,7 +17,7 @@
 "documentationLink": "https://cloud.google.com/dataflow",
 "protocol": "rest",
 "baseUrl": "https://dataflow.googleapis.com/",
- "basePath": "/",
+ "basePath": "",
 "rootUrl": "https://dataflow.googleapis.com/",
 "servicePath": "",
 "batchPath": "batch",
@@ -160,7 +160,9 @@
      "JOB_STATE_DONE",
      "JOB_STATE_FAILED",
      "JOB_STATE_CANCELLED",
-      "JOB_STATE_UPDATED"
+      "JOB_STATE_UPDATED",
+      "JOB_STATE_DRAINING",
+      "JOB_STATE_DRAINED"
     ]
    },
    "currentStateTime": {
@@ -177,7 +179,9 @@
      "JOB_STATE_DONE",
      "JOB_STATE_FAILED",
      "JOB_STATE_CANCELLED",
-      "JOB_STATE_UPDATED"
+      "JOB_STATE_UPDATED",
+      "JOB_STATE_DRAINING",
+      "JOB_STATE_DRAINED"
     ]
    },
    "executionInfo": {
@@ -206,6 +210,13 @@
    "replacedByJobId": {
     "type": "string",
     "description": "If another job is an update of this job (and thus, this job is in JOB_STATE_UPDATED), this field will contain the ID of that job."
+    },
+    "tempFiles": {
+     "type": "array",
+     "description": "A set of files the system should be aware of that are used for temporary storage. These temporary files will be removed on job completion. No duplicates are allowed. No file patterns are supported. The supported files are: Google Cloud Storage: storage.googleapis.com/{bucket}/{object} bucket.storage.googleapis.com/{object}",
+     "items": {
+      "type": "string"
+     }
    }
   }
  },
@@ -334,7 +345,7 @@
    },
    "zone": {
     "type": "string",
-     "description": "Zone to run the worker pools in (e.g. \"us-central1-b\"). If empty or unspecified, the service will attempt to choose a reasonable default."
+     "description": "Zone to run the worker pools in. If empty or unspecified, the service will attempt to choose a reasonable default."
    },
    "taskrunnerSettings": {
     "$ref": "TaskRunnerSettings",
@@ -589,7 +600,7 @@
  "JobExecutionStageInfo": {
   "id": "JobExecutionStageInfo",
   "type": "object",
-   "description": "Contains information about how a particular [google.dataflow.v1beta3.Step][google.dataflow.v1beta3.Step] will be executed.",
+   "description": "Contains information about how a particular google.dataflow.v1beta3.Step will be executed.",
   "properties": {
    "stepName": {
     "type": "array",
@@ -808,9 +819,9 @@
      "$ref": "MetricUpdate"
     }
    },
-    "progress": {
-     "$ref": "ApproximateProgress",
-     "description": "The WorkItem's approximate progress."
+    "reportedProgress": {
+     "$ref": "ApproximateReportedProgress",
+     "description": "The worker's progress through this WorkItem."
    },
    "stopPosition": {
     "$ref": "Position",
@@ -827,22 +838,26 @@
    "sourceFork": {
     "$ref": "SourceFork",
     "description": "DEPRECATED in favor of dynamic_source_split."
+    },
+    "progress": {
+     "$ref": "ApproximateProgress",
+     "description": "DEPRECATED in favor of reported_progress."
    }
   }
  },
  "Status": {
   "id": "Status",
   "type": "object",
-   "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). The error model is designed to be: - Simple to use and understand for most users - Flexible enough to meet unexpected needs # Overview The `Status` message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of [google.rpc.Code][], but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers *understand* and *resolve* the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package `google.rpc` which can be used for common error conditions. # Language mapping The `Status` message is the logical representation of the error model, but it is not necessarily the actual wire format. When the `Status` message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C. # Other uses The error model and the `Status` message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments. Example uses of this error model include: - Partial errors. If a service needs to return partial errors to the client, it may embed the `Status` in the normal response to indicate the partial errors. - Workflow errors. A typical workflow has multiple steps. Each step may have a `Status` message for error reporting purpose. - Batch operations. If a client uses batch request and batch response, the `Status` message should be used directly inside batch response, one for each error sub-response. - Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the `Status` message. - Logging. If some API errors are stored in logs, the message `Status` could be used directly after any stripping needed for security/privacy reasons.",
+   "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). The error model is designed to be: - Simple to use and understand for most users - Flexible enough to meet unexpected needs # Overview The `Status` message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of google.rpc.Code, but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers *understand* and *resolve* the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package `google.rpc` which can be used for common error conditions. # Language mapping The `Status` message is the logical representation of the error model, but it is not necessarily the actual wire format. When the `Status` message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C. # Other uses The error model and the `Status` message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments. Example uses of this error model include: - Partial errors. If a service needs to return partial errors to the client, it may embed the `Status` in the normal response to indicate the partial errors. - Workflow errors. A typical workflow has multiple steps. Each step may have a `Status` message for error reporting purpose. - Batch operations. If a client uses batch request and batch response, the `Status` message should be used directly inside batch response, one for each error sub-response. - Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the `Status` message. - Logging. If some API errors are stored in logs, the message `Status` could be used directly after any stripping needed for security/privacy reasons.",
   "properties": {
    "code": {
     "type": "integer",
-     "description": "The status code, which should be an enum value of [google.rpc.Code][].",
+     "description": "The status code, which should be an enum value of google.rpc.Code.",
     "format": "int32"
    },
    "message": {
     "type": "string",
-     "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client."
+     "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client."
    },
    "details": {
     "type": "array",
@@ -857,8 +872,8 @@
    }
   }
  },
-  "ApproximateProgress": {
-   "id": "ApproximateProgress",
+  "ApproximateReportedProgress": {
+   "id": "ApproximateReportedProgress",
   "type": "object",
   "description": "A progress measurement of a WorkItem by a worker.",
   "properties": {
@@ -866,14 +881,18 @@
     "$ref": "Position",
     "description": "A Position within the work to represent a progress."
    },
-    "percentComplete": {
+    "fractionConsumed": {
     "type": "number",
-     "description": "Completion as percentage of the work, from 0.0 (beginning, nothing complete), to 1.0 (end of the work range, entire WorkItem complete).",
-     "format": "float"
+     "description": "Completion as fraction of the input consumed, from 0.0 (beginning, nothing consumed), to 1.0 (end of the input, entire input consumed).",
+     "format": "double"
    },
-    "remainingTime": {
-     "type": "string",
-     "description": "Completion as an estimated time remaining."
+    "remainingParallelism": {
+     "$ref": "ReportedParallelism",
+     "description": "Total amount of parallelism in the input of this WorkItem that has not been consumed yet (i.e. can be delegated to a new WorkItem via dynamic splitting). \"Amount of parallelism\" refers to how many non-empty parts of the input can be read in parallel. This does not necessarily equal number of records. An input that can be read in parallel down to the individual records is called \"perfectly splittable\". An example of non-perfectly parallelizable input is a block-compressed file format where a block of records has to be read as a whole, but different blocks can be read in parallel. Examples: * If we have read 30 records out of 50 in a perfectly splittable 50-record input, this value should be 20. * If we are reading through block 3 in a block-compressed file consisting of 5 blocks, this value should be 2 (since blocks 4 and 5 can be processed in parallel by new work items via dynamic splitting). * If we are reading through the last block in a block-compressed file, or reading or processing the last record in a perfectly splittable input, this value should be 0, because the remainder of the work item cannot be further split."
+    },
+    "consumedParallelism": {
+     "$ref": "ReportedParallelism",
+     "description": "Total amount of parallelism in the portion of input of this work item that has already been consumed. In the first two examples above (see remaining_parallelism), the value should be 30 or 3 respectively. The sum of remaining_parallelism and consumed_parallelism should equal the total amount of parallelism in this work item. If specified, must be finite."
    }
   }
  },
@@ -926,6 +945,22 @@
    }
   }
  },
+  "ReportedParallelism": {
+   "id": "ReportedParallelism",
+   "type": "object",
+   "description": "Represents the level of parallelism in a WorkItem's input, reported by the worker.",
+   "properties": {
+    "isInfinite": {
+     "type": "boolean",
+     "description": "Specifies whether the parallelism is infinite. If true, \"value\" is ignored. Infinite parallelism means the service will assume that the work item can always be split into more non-empty work items by dynamic splitting. This is a work-around for lack of support for infinity by the current JSON-based Java RPC stack."
+    },
+    "value": {
+     "type": "number",
+     "description": "Specifies the level of parallelism in case it is finite.",
+     "format": "double"
+    }
+   }
+  },
  "DynamicSourceSplit": {
   "id": "DynamicSourceSplit",
   "type": "object",
@@ -1124,6 +1159,26 @@
    }
   }
  },
+  "ApproximateProgress": {
+   "id": "ApproximateProgress",
+   "type": "object",
+   "description": "Obsolete in favor of ApproximateReportedProgress and ApproximateSplitRequest.",
+   "properties": {
+    "position": {
+     "$ref": "Position",
+     "description": "Obsolete."
+    },
+    "percentComplete": {
+     "type": "number",
+     "description": "Obsolete.",
+     "format": "float"
+    },
+    "remainingTime": {
+     "type": "string",
+     "description": "Obsolete."
+    }
+   }
+  },
  "ReportWorkItemStatusResponse": {
   "id": "ReportWorkItemStatusResponse",
   "type": "object",
@@ -1143,8 +1198,8 @@
   "type": "object",
   "description": "The Dataflow service's idea of the current state of a WorkItem being processed by a worker.",
   "properties": {
-    "suggestedStopPoint": {
-     "$ref": "ApproximateProgress",
+    "splitRequest": {
+     "$ref": "ApproximateSplitRequest",
     "description": "The progress point in the WorkItem where the Dataflow service suggests that the worker truncate the task."
    },
    "leaseExpireTime": {
@@ -1171,6 +1226,26 @@
    "suggestedStopPosition": {
     "$ref": "Position",
     "description": "Obsolete, always empty."
+    },
+    "suggestedStopPoint": {
+     "$ref": "ApproximateProgress",
+     "description": "DEPRECATED in favor of split_request."
+    }
+   }
+  },
+  "ApproximateSplitRequest": {
+   "id": "ApproximateSplitRequest",
+   "type": "object",
+   "description": "A suggestion by the service to the worker to dynamically split the WorkItem.",
+   "properties": {
+    "position": {
+     "$ref": "Position",
+     "description": "A Position at which to split the work item."
+    },
+    "fractionConsumed": {
+     "type": "number",
+     "description": "A fraction at which to split the work item, from 0.0 (beginning of the input) to 1.0 (end of the input).",
+     "format": "double"
    }
   }
  },
@@ -1276,7 +1351,7 @@
    },
    "leaseExpireTime": {
     "type": "string",
-     "description": "Time when the lease on this [Work][] will expire."
+     "description": "Time when the lease on this Work will expire."
    },
    "configuration": {
     "type": "string",
@@ -1518,6 +1593,13 @@
      "type": "any",
      "description": "Properties of the object."
     }
+    },
+    "sideInputs": {
+     "type": "array",
+     "description": "Zero or more side inputs.",
+     "items": {
+      "$ref": "SideInputInfo"
+     }
    }
   }
  },
@@ -1676,6 +1758,11 @@
     "additionalProperties": {
      "type": "string"
     }
+    },
+    "forwardingKeyBits": {
+     "type": "integer",
+     "description": "The size (in bits) of keys that will be assigned to source messages.",
+     "format": "int32"
    }
   }
  },
@@ -2012,10 +2099,164 @@
     "description": "The name of the data disk where data for this range is stored. This name is local to the Google Cloud Platform project and uniquely identifies the disk within that project, for example \"myproject-1014-104817-4c2-harness-0-disk-1\"."
    }
   }
+  },
+  "SendWorkerMessagesRequest": {
+   "id": "SendWorkerMessagesRequest",
+   "type": "object",
+   "description": "A request for sending worker messages to the service.",
+   "properties": {
+    "workerMessages": {
+     "type": "array",
+     "description": "The WorkerMessages to send.",
+     "items": {
+      "$ref": "WorkerMessage"
+     }
+    }
+   }
+  },
+  "WorkerMessage": {
+   "id": "WorkerMessage",
+   "type": "object",
+   "description": "WorkerMessage provides information to the backend about a worker.",
+   "properties": {
+    "labels": {
+     "type": "object",
+     "description": "Labels are used to group WorkerMessages. For example, a worker_message about a particular container might have the labels: { \"JOB_ID\": \"2015-04-22\", \"WORKER_ID\": \"wordcount-vm-2015…\" \"CONTAINER_TYPE\": \"worker\", \"CONTAINER_ID\": \"ac1234def\"} Label tags typically correspond to Label enum values. However, for ease of development other strings can be used as tags. LABEL_UNSPECIFIED should not be used here.",
+     "additionalProperties": {
+      "type": "string"
+     }
+    },
+    "time": {
+     "type": "string",
+     "description": "The timestamp of the worker_message."
+    },
+    "workerHealthReport": {
+     "$ref": "WorkerHealthReport",
+     "description": "The health of a worker."
+    },
+    "workerMessageCode": {
+     "$ref": "WorkerMessageCode",
+     "description": "A worker message code."
+    }
+   }
+  },
+  "WorkerHealthReport": {
+   "id": "WorkerHealthReport",
+   "type": "object",
+   "description": "WorkerHealthReport contains information about the health of a worker. The VM should be identified by the labels attached to the WorkerMessage that this health ping belongs to.",
+   "properties": {
+    "vmIsHealthy": {
+     "type": "boolean",
+     "description": "Whether the VM is healthy."
+    },
+    "vmStartupTime": {
+     "type": "string",
+     "description": "The time the VM was booted."
+    },
+    "reportInterval": {
+     "type": "string",
+     "description": "The interval at which the worker is sending health reports. The default value of 0 should be interpreted as the field is not being explicitly set by the worker."
+    },
+    "pods": {
+     "type": "array",
+     "description": "The pods running on the worker. See: http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html#_v1_pod This field is used by the worker to send the status of the indvidual containers running on each worker.",
+     "items": {
+      "type": "object",
+      "additionalProperties": {
+       "type": "any",
+       "description": "Properties of the object."
+      }
+     }
+    }
+   }
+  },
+  "WorkerMessageCode": {
+   "id": "WorkerMessageCode",
+   "type": "object",
+   "description": "A message code is used to report status and error messages to the service. The message codes are intended to be machine readable. The service will take care of translating these into user understandable messages if necessary. Example use cases: 1. Worker processes reporting successful startup. 2. Worker processes reporting specific errors (e.g. package staging failure).",
+   "properties": {
+    "code": {
+     "type": "string",
+     "description": "The code is a string intended for consumption by a machine that identifies the type of message being sent. Examples: 1. \"HARNESS_STARTED\" might be used to indicate the worker harness has started. 2. \"GCS_DOWNLOAD_ERROR\" might be used to indicate an error downloading a GCS file as part of the boot process of one of the worker containers. This is a string and not an enum to make it easy to add new codes without waiting for an API change."
+    },
+    "parameters": {
+     "type": "object",
+     "description": "Parameters contains specific information about the code. This is a struct to allow parameters of different types. Examples: 1. For a \"HARNESS_STARTED\" message parameters might provide the name of the worker and additional data like timing information. 2. For a \"GCS_DOWNLOAD_ERROR\" parameters might contain fields listing the GCS objects being downloaded and fields containing errors. In general complex data structures should be avoided. If a worker needs to send a specific and complicated data structure then please consider defining a new proto and adding it to the data oneof in WorkerMessageResponse. Conventions: Parameters should only be used for information that isn't typically passed as a label. hostname and other worker identifiers should almost always be passed as labels since they will be included on most messages.",
+     "additionalProperties": {
+      "type": "any",
+      "description": "Properties of the object."
+     }
+    }
+   }
+  },
+  "SendWorkerMessagesResponse": {
+   "id": "SendWorkerMessagesResponse",
+   "type": "object",
+   "description": "The response to the worker messages.",
+   "properties": {
+    "workerMessageResponses": {
+     "type": "array",
+     "description": "The servers response to the worker messages.",
+     "items": {
+      "$ref": "WorkerMessageResponse"
+     }
+    }
+   }
+  },
+  "WorkerMessageResponse": {
+   "id": "WorkerMessageResponse",
+   "type": "object",
+   "description": "A worker_message response allows the server to pass information to the sender.",
+   "properties": {
+    "workerHealthReportResponse": {
+     "$ref": "WorkerHealthReportResponse",
+     "description": "The service's response to a worker's health report."
+    }
+   }
+  },
+  "WorkerHealthReportResponse": {
+   "id": "WorkerHealthReportResponse",
+   "type": "object",
+   "description": "WorkerHealthReportResponse contains information returned to the worker in response to a health ping.",
+   "properties": {
+    "reportInterval": {
+     "type": "string",
+     "description": "A positive value indicates the worker should change its reporting interval to the specified value. The default value of zero means no change in report rate is requested by the server."
+    }
+   }
  }
 },
 "resources": {
  "projects": {
+   "methods": {
+    "workerMessages": {
+     "id": "dataflow.projects.workerMessages",
+     "path": "v1b3/projects/{projectId}/WorkerMessages",
+     "httpMethod": "POST",
+     "description": "Send a worker_message to the service.",
+     "parameters": {
+      "projectId": {
+       "type": "string",
+       "description": "The project to send the WorkerMessages to.",
+       "required": true,
+       "location": "path"
+      }
+     },
+     "parameterOrder": [
+      "projectId"
+     ],
+     "request": {
+      "$ref": "SendWorkerMessagesRequest"
+     },
+     "response": {
+      "$ref": "SendWorkerMessagesResponse"
+     },
+     "scopes": [
+      "https://www.googleapis.com/auth/cloud-platform",
+      "https://www.googleapis.com/auth/userinfo.email"
+     ]
+    }
+   },
   "resources": {
    "jobs": {
     "methods": {