Blame - docs/dyn/remotebuildexecution_v2.actions.html - platform/external/python/google-api-python-client

blob: 27823dad17084beaca74253551238f9ad3b66451 [file] [log] [blame]

Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	1	<html><body>
				2	<style>
				3
				4	body, h1, h2, h3, div, span, p, pre, a {
				5	margin: 0;
				6	padding: 0;
				7	border: 0;
				8	font-weight: inherit;
				9	font-style: inherit;
				10	font-size: 100%;
				11	font-family: inherit;
				12	vertical-align: baseline;
				13	}
				14
				15	body {
				16	font-size: 13px;
				17	padding: 1em;
				18	}
				19
				20	h1 {
				21	font-size: 26px;
				22	margin-bottom: 1em;
				23	}
				24
				25	h2 {
				26	font-size: 24px;
				27	margin-bottom: 1em;
				28	}
				29
				30	h3 {
				31	font-size: 20px;
				32	margin-bottom: 1em;
				33	margin-top: 1em;
				34	}
				35
				36	pre, code {
				37	line-height: 1.5;
				38	font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
				39	}
				40
				41	pre {
				42	margin-top: 0.5em;
				43	}
				44
				45	h1, h2, h3, p {
				46	font-family: Arial, sans serif;
				47	}
				48
				49	h1, h2, h3 {
				50	border-bottom: solid #CCC 1px;
				51	}
				52
				53	.toc_element {
				54	margin-top: 0.5em;
				55	}
				56
				57	.firstline {
				58	margin-left: 2 em;
				59	}
				60
				61	.method {
				62	margin-top: 1em;
				63	border: solid 1px #CCC;
				64	padding: 1em;
				65	background: #EEE;
				66	}
				67
				68	.details {
				69	font-weight: bold;
				70	font-size: 14px;
				71	}
				72
				73	</style>
				74
				75	<h1><a href="remotebuildexecution_v2.html">Remote Build Execution API</a> . <a href="remotebuildexecution_v2.actions.html">actions</a></h1>
				76	<h2>Instance Methods</h2>
				77	<p class="toc_element">
Dan O'Meara	dd49464	2020-05-01 07:42:23 -0700	[diff] [blame]	78	<code><a href="#execute">execute(instanceName, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	79	<p class="firstline">Execute an action remotely.</p>
				80	<h3>Method Details</h3>
				81	<div class="method">
Dan O'Meara	dd49464	2020-05-01 07:42:23 -0700	[diff] [blame]	82	<code class="details" id="execute">execute(instanceName, body=None, x__xgafv=None)</code>
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	83	<pre>Execute an action remotely.
				84
				85	In order to execute an action, the client must first upload all of the
				86	inputs, the
				87	Command to run, and the
				88	Action into the
				89	ContentAddressableStorage.
				90	It then calls `Execute` with an `action_digest` referring to them. The
				91	server will run the action and eventually return the result.
				92
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	93	The input `Action`'s fields MUST meet the various canonicalization
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	94	requirements specified in the documentation for their types so that it has
				95	the same digest as other logically equivalent `Action`s. The server MAY
				96	enforce the requirements and return errors if a non-canonical input is
				97	received. It MAY also proceed without verifying some or all of the
				98	requirements, such as for performance reasons. If the server does not
				99	verify the requirement, then it will treat the `Action` as distinct from
				100	another logically equivalent action if they hash differently.
				101
				102	Returns a stream of
				103	google.longrunning.Operation messages
				104	describing the resulting execution, with eventual `response`
				105	ExecuteResponse. The
				106	`metadata` on the operation is of type
				107	ExecuteOperationMetadata.
				108
				109	If the client remains connected after the first response is returned after
				110	the server, then updates are streamed as if the client had called
				111	WaitExecution
				112	until the execution completes or the request reaches an error. The
				113	operation can also be queried using Operations
				114	API.
				115
				116	The server NEED NOT implement other methods or functionality of the
				117	Operations API.
				118
				119	Errors discovered during creation of the `Operation` will be reported
				120	as gRPC Status errors, while errors that occurred while running the
				121	action will be reported in the `status` field of the `ExecuteResponse`. The
				122	server MUST NOT set the `error` field of the `Operation` proto.
				123	The possible errors include:
				124
				125	* `INVALID_ARGUMENT`: One or more arguments are invalid.
				126	* `FAILED_PRECONDITION`: One or more errors occurred in setting up the
				127	action requested, such as a missing input or command or no worker being
				128	available. The client may be able to fix the errors and retry.
				129	* `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run
				130	the action.
				131	* `UNAVAILABLE`: Due to a transient condition, such as all workers being
				132	occupied (and the server does not support a queue), the action could not
				133	be started. The client should retry.
				134	* `INTERNAL`: An internal error occurred in the execution engine or the
				135	worker.
				136	* `DEADLINE_EXCEEDED`: The execution timed out.
				137	* `CANCELLED`: The operation was cancelled by the client. This status is
				138	only possible if the server implements the Operations API CancelOperation
				139	method, and it was called for the current execution.
				140
				141	In the case of a missing input or command, the server SHOULD additionally
				142	send a PreconditionFailure error detail
				143	where, for each requested blob not present in the CAS, there is a
				144	`Violation` with a `type` of `MISSING` and a `subject` of
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	145	`"blobs/{hash}/{size}"` indicating the digest of the missing blob.
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	146
				147	Args:
				148	instanceName: string, The instance of the execution system to operate against. A server may
				149	support multiple instances of the execution system (with their own workers,
				150	storage, caches, etc.). The server MAY require use of this field to select
				151	between them in an implementation-defined fashion, otherwise it can be
				152	omitted. (required)
Dan O'Meara	dd49464	2020-05-01 07:42:23 -0700	[diff] [blame]	153	body: object, The request body.
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	154	The object takes the form of:
				155
				156	{ # A request message for
				157	# Execution.Execute.
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	158	"skipCacheLookup": True or False, # If true, the action will be executed even if its result is already
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	159	# present in the ActionCache.
				160	# The execution is still allowed to be merged with other in-flight executions
				161	# of the same action, however - semantically, the service MUST only guarantee
				162	# that the results of an execution with this field set were not visible
				163	# before the corresponding execution request was sent.
				164	# Note that actions from execution requests setting this field set are still
				165	# eligible to be entered into the action cache upon completion, and services
				166	# SHOULD overwrite any existing entries that may exist. This allows
				167	# skip_cache_lookup requests to be used as a mechanism for replacing action
				168	# cache entries that reference outputs no longer available or that are
				169	# poisoned in any way.
				170	# If false, the result may be served from the action cache.
Bu Sun Kim	d059ad8	2020-07-22 17:02:09 -0700	[diff] [blame^]	171	"executionPolicy": { # An `ExecutionPolicy` can be used to control the scheduling of the action. # An optional policy for execution of the action.
				172	# The server will have a default policy if this is not provided.
				173	"priority": 42, # The priority (relative importance) of this action. Generally, a lower value
				174	# means that the action should be run sooner than actions having a greater
				175	# priority value, but the interpretation of a given value is server-
				176	# dependent. A priority of 0 means the default priority. Priorities may be
				177	# positive or negative, and such actions should run later or sooner than
				178	# actions having the default priority, respectively. The particular semantics
				179	# of this field is up to the server. In particular, every server will have
				180	# their own supported range of priorities, and will decide how these map into
				181	# scheduling policy.
				182	},
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	183	"actionDigest": { # A content digest. A digest for a given blob consists of the size of the blob # The digest of the Action to
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	184	# execute.
Dan O'Meara	dd49464	2020-05-01 07:42:23 -0700	[diff] [blame]	185	# and its hash. The hash algorithm to use is defined by the server.
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	186	#
				187	# The size is considered to be an integral part of the digest and cannot be
				188	# separated. That is, even if the `hash` field is correctly specified but
				189	# `size_bytes` is not, the server MUST reject the request.
				190	#
				191	# The reason for including the size in the digest is as follows: in a great
				192	# many cases, the server needs to know the size of the blob it is about to work
				193	# with prior to starting an operation with it, such as flattening Merkle tree
				194	# structures or streaming it to a worker. Technically, the server could
				195	# implement a separate metadata store, but this results in a significantly more
				196	# complicated implementation as opposed to having the client specify the size
				197	# up-front (or storing the size along with the digest in every message where
				198	# digests are embedded). This does mean that the API leaks some implementation
				199	# details of (what we consider to be) a reasonable server implementation, but
				200	# we consider this to be a worthwhile tradeoff.
				201	#
				202	# When a `Digest` is used to refer to a proto message, it always refers to the
				203	# message in binary encoded form. To ensure consistent hashing, clients and
				204	# servers MUST ensure that they serialize messages according to the following
				205	# rules, even if there are alternate valid encodings for the same message:
				206	#
				207	# * Fields are serialized in tag order.
				208	# * There are no unknown fields.
				209	# * There are no duplicate fields.
				210	# * Fields are serialized according to the default semantics for their type.
				211	#
				212	# Most protocol buffer implementations will always follow these rules when
				213	# serializing, but care should be taken to avoid shortcuts. For instance,
				214	# concatenating two messages to merge them may produce duplicate fields.
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	215	"sizeBytes": "A String", # The size of the blob, in bytes.
				216	"hash": "A String", # The hash. In the case of SHA-256, it will always be a lowercase hex string
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	217	# exactly 64 characters long.
				218	},
Bu Sun Kim	d059ad8	2020-07-22 17:02:09 -0700	[diff] [blame^]	219	"resultsCachePolicy": { # A `ResultsCachePolicy` is used for fine-grained control over how action # An optional policy for the results of this execution in the remote cache.
Bu Sun Kim	4ed7d3f	2020-05-27 12:20:54 -0700	[diff] [blame]	220	# The server will have a default policy if this is not provided.
Bu Sun Kim	d059ad8	2020-07-22 17:02:09 -0700	[diff] [blame^]	221	# This may be applied to both the ActionResult and the associated blobs.
				222	# outputs are stored in the CAS and Action Cache.
				223	"priority": 42, # The priority (relative importance) of this content in the overall cache.
				224	# Generally, a lower value means a longer retention time or other advantage,
				225	# but the interpretation of a given value is server-dependent. A priority of
				226	# 0 means a default value, decided by the server.
				227	#
				228	# The particular semantics of this field is up to the server. In particular,
				229	# every server will have their own supported range of priorities, and will
				230	# decide how these map into retention/eviction policy.
Bu Sun Kim	4ed7d3f	2020-05-27 12:20:54 -0700	[diff] [blame]	231	},
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	232	}
				233
				234	x__xgafv: string, V1 error format.
				235	Allowed values
				236	1 - v1 error format
				237	2 - v2 error format
				238
				239	Returns:
				240	An object of the form:
				241
				242	{ # This resource represents a long-running operation that is the result of a
				243	# network API call.
Bu Sun Kim	d059ad8	2020-07-22 17:02:09 -0700	[diff] [blame^]	244	"metadata": { # Service-specific metadata associated with the operation. It typically
				245	# contains progress information and common metadata such as create time.
				246	# Some services might not provide such metadata. Any method that returns a
				247	# long-running operation should document the metadata type, if any.
				248	"a_key": "", # Properties of the object. Contains field @type with type URL.
				249	},
Bu Sun Kim	4ed7d3f	2020-05-27 12:20:54 -0700	[diff] [blame]	250	"done": True or False, # If the value is `false`, it means the operation is still in progress.
				251	# If `true`, the operation is completed, and either `error` or `response` is
				252	# available.
Bu Sun Kim	d059ad8	2020-07-22 17:02:09 -0700	[diff] [blame^]	253	"error": { # The `Status` type defines a logical error model that is suitable for # The error result of the operation in case of failure or cancellation.
				254	# different programming environments, including REST APIs and RPC APIs. It is
				255	# used by [gRPC](https://github.com/grpc). Each `Status` message contains
				256	# three pieces of data: error code, error message, and error details.
				257	#
				258	# You can find out more about this error model and how to work with it in the
				259	# [API Design Guide](https://cloud.google.com/apis/design/errors).
				260	"message": "A String", # A developer-facing error message, which should be in English. Any
				261	# user-facing error message should be localized and sent in the
				262	# google.rpc.Status.details field, or localized by the client.
				263	"details": [ # A list of messages that carry the error details. There is a common set of
				264	# message types for APIs to use.
				265	{
				266	"a_key": "", # Properties of the object. Contains field @type with type URL.
				267	},
				268	],
				269	"code": 42, # The status code, which should be an enum value of google.rpc.Code.
				270	},
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	271	"response": { # The normal response of the operation in case of success. If the original
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	272	# method returns no data on success, such as `Delete`, the response is
				273	# `google.protobuf.Empty`. If the original method is standard
				274	# `Get`/`Create`/`Update`, the response should be the resource. For other
				275	# methods, the response should have the type `XxxResponse`, where `Xxx`
				276	# is the original method name. For example, if the original method name
				277	# is `TakeSnapshot()`, the inferred response type is
				278	# `TakeSnapshotResponse`.
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	279	"a_key": "", # Properties of the object. Contains field @type with type URL.
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	280	},
Bu Sun Kim	6502091	2020-05-20 12:08:20 -0700	[diff] [blame]	281	"name": "A String", # The server-assigned name, which is only unique within the same service that
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	282	# originally returns it. If you use the default HTTP mapping, the
				283	# `name` should be a resource name ending with `operations/{unique_id}`.
Bu Sun Kim	715bd7f	2019-06-14 16:50:42 -0700	[diff] [blame]	284	}</pre>
				285	</div>
				286
				287	</body></html>