docs/dyn/remotebuildexecution_v2.actions.html - platform/external/python/google-api-python-client - Git at Google

 <html><body>
 <style>

 body, h1, h2, h3, div, span, p, pre, a {
   margin: 0;
   padding: 0;
   border: 0;
   font-weight: inherit;
   font-style: inherit;
   font-size: 100%;
   font-family: inherit;
   vertical-align: baseline;
 }

 body {
   font-size: 13px;
   padding: 1em;
 }

 h1 {
   font-size: 26px;
   margin-bottom: 1em;
 }

 h2 {
   font-size: 24px;
   margin-bottom: 1em;
 }

 h3 {
   font-size: 20px;
   margin-bottom: 1em;
   margin-top: 1em;
 }

 pre, code {
   line-height: 1.5;
   font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
 }

 pre {
   margin-top: 0.5em;
 }

 h1, h2, h3, p {
   font-family: Arial, sans serif;
 }

 h1, h2, h3 {
   border-bottom: solid #CCC 1px;
 }

 .toc_element {
   margin-top: 0.5em;
 }

 .firstline {
   margin-left: 2 em;
 }

 .method  {
   margin-top: 1em;
   border: solid 1px #CCC;
   padding: 1em;
   background: #EEE;
 }

 .details {
   font-weight: bold;
   font-size: 14px;
 }

 </style>

 <h1><a href="remotebuildexecution_v2.html">Remote Build Execution API</a> . <a href="remotebuildexecution_v2.actions.html">actions</a></h1>
 <h2>Instance Methods</h2>
 <p class="toc_element">
   <code><a href="#execute">execute(instanceName, body, x__xgafv=None)</a></code></p>
 <p class="firstline">Execute an action remotely.</p>
 <h3>Method Details</h3>
 <div class="method">
     <code class="details" id="execute">execute(instanceName, body, x__xgafv=None)</code>
   <pre>Execute an action remotely.

 In order to execute an action, the client must first upload all of the
 inputs, the
 Command to run, and the
 Action into the
 ContentAddressableStorage.
 It then calls `Execute` with an `action_digest` referring to them. The
 server will run the action and eventually return the result.

 The input `Action`'s fields MUST meet the various canonicalization
 requirements specified in the documentation for their types so that it has
 the same digest as other logically equivalent `Action`s. The server MAY
 enforce the requirements and return errors if a non-canonical input is
 received. It MAY also proceed without verifying some or all of the
 requirements, such as for performance reasons. If the server does not
 verify the requirement, then it will treat the `Action` as distinct from
 another logically equivalent action if they hash differently.

 Returns a stream of
 google.longrunning.Operation messages
 describing the resulting execution, with eventual `response`
 ExecuteResponse. The
 `metadata` on the operation is of type
 ExecuteOperationMetadata.

 If the client remains connected after the first response is returned after
 the server, then updates are streamed as if the client had called
 WaitExecution
 until the execution completes or the request reaches an error. The
 operation can also be queried using Operations
 API.

 The server NEED NOT implement other methods or functionality of the
 Operations API.

 Errors discovered during creation of the `Operation` will be reported
 as gRPC Status errors, while errors that occurred while running the
 action will be reported in the `status` field of the `ExecuteResponse`. The
 server MUST NOT set the `error` field of the `Operation` proto.
 The possible errors include:

 * `INVALID_ARGUMENT`: One or more arguments are invalid.
 * `FAILED_PRECONDITION`: One or more errors occurred in setting up the
   action requested, such as a missing input or command or no worker being
   available. The client may be able to fix the errors and retry.
 * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run
   the action.
 * `UNAVAILABLE`: Due to a transient condition, such as all workers being
   occupied (and the server does not support a queue), the action could not
   be started. The client should retry.
 * `INTERNAL`: An internal error occurred in the execution engine or the
   worker.
 * `DEADLINE_EXCEEDED`: The execution timed out.
 * `CANCELLED`: The operation was cancelled by the client. This status is
   only possible if the server implements the Operations API CancelOperation
   method, and it was called for the current execution.

 In the case of a missing input or command, the server SHOULD additionally
 send a PreconditionFailure error detail
 where, for each requested blob not present in the CAS, there is a
 `Violation` with a `type` of `MISSING` and a `subject` of
 `"blobs/{hash}/{size}"` indicating the digest of the missing blob.

 Args:
   instanceName: string, The instance of the execution system to operate against. A server may
 support multiple instances of the execution system (with their own workers,
 storage, caches, etc.). The server MAY require use of this field to select
 between them in an implementation-defined fashion, otherwise it can be
 omitted. (required)
   body: object, The request body. (required)
     The object takes the form of:

 { # A request message for
       # Execution.Execute.
     "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.
         # The server will have a default policy if this is not provided.
         # This may be applied to both the ActionResult and the associated blobs.
         # outputs are stored in the CAS and Action Cache.
       "priority": 42, # The priority (relative importance) of this content in the overall cache.
           # Generally, a lower value means a longer retention time or other advantage,
           # but the interpretation of a given value is server-dependent. A priority of
           # 0 means a *default* value, decided by the server.
           #
           # The particular semantics of this field is up to the server. In particular,
           # every server will have their own supported range of priorities, and will
           # decide how these map into retention/eviction policy.
     },
     "skipCacheLookup": True or False, # If true, the action will be executed even if its result is already
         # present in the ActionCache.
         # The execution is still allowed to be merged with other in-flight executions
         # of the same action, however - semantically, the service MUST only guarantee
         # that the results of an execution with this field set were not visible
         # before the corresponding execution request was sent.
         # Note that actions from execution requests setting this field set are still
         # eligible to be entered into the action cache upon completion, and services
         # SHOULD overwrite any existing entries that may exist. This allows
         # skip_cache_lookup requests to be used as a mechanism for replacing action
         # cache entries that reference outputs no longer available or that are
         # poisoned in any way.
         # If false, the result may be served from the action cache.
     "actionDigest": { # A content digest. A digest for a given blob consists of the size of the blob # The digest of the Action to
         # execute.
         # and its hash. The hash algorithm to use is defined by the server, but servers
         # SHOULD use SHA-256.
         #
         # The size is considered to be an integral part of the digest and cannot be
         # separated. That is, even if the `hash` field is correctly specified but
         # `size_bytes` is not, the server MUST reject the request.
         #
         # The reason for including the size in the digest is as follows: in a great
         # many cases, the server needs to know the size of the blob it is about to work
         # with prior to starting an operation with it, such as flattening Merkle tree
         # structures or streaming it to a worker. Technically, the server could
         # implement a separate metadata store, but this results in a significantly more
         # complicated implementation as opposed to having the client specify the size
         # up-front (or storing the size along with the digest in every message where
         # digests are embedded). This does mean that the API leaks some implementation
         # details of (what we consider to be) a reasonable server implementation, but
         # we consider this to be a worthwhile tradeoff.
         #
         # When a `Digest` is used to refer to a proto message, it always refers to the
         # message in binary encoded form. To ensure consistent hashing, clients and
         # servers MUST ensure that they serialize messages according to the following
         # rules, even if there are alternate valid encodings for the same message:
         #
         # * Fields are serialized in tag order.
         # * There are no unknown fields.
         # * There are no duplicate fields.
         # * Fields are serialized according to the default semantics for their type.
         #
         # Most protocol buffer implementations will always follow these rules when
         # serializing, but care should be taken to avoid shortcuts. For instance,
         # concatenating two messages to merge them may produce duplicate fields.
       "sizeBytes": "A String", # The size of the blob, in bytes.
       "hash": "A String", # The hash. In the case of SHA-256, it will always be a lowercase hex string
           # exactly 64 characters long.
     },
     "executionPolicy": { # An `ExecutionPolicy` can be used to control the scheduling of the action. # An optional policy for execution of the action.
         # The server will have a default policy if this is not provided.
       "priority": 42, # The priority (relative importance) of this action. Generally, a lower value
           # means that the action should be run sooner than actions having a greater
           # priority value, but the interpretation of a given value is server-
           # dependent. A priority of 0 means the *default* priority. Priorities may be
           # positive or negative, and such actions should run later or sooner than
           # actions having the default priority, respectively. The particular semantics
           # of this field is up to the server. In particular, every server will have
           # their own supported range of priorities, and will decide how these map into
           # scheduling policy.
     },
   }

   x__xgafv: string, V1 error format.
     Allowed values
       1 - v1 error format
       2 - v2 error format

 Returns:
   An object of the form:

     { # This resource represents a long-running operation that is the result of a
       # network API call.
     "response": { # The normal response of the operation in case of success.  If the original
         # method returns no data on success, such as `Delete`, the response is
         # `google.protobuf.Empty`.  If the original method is standard
         # `Get`/`Create`/`Update`, the response should be the resource.  For other
         # methods, the response should have the type `XxxResponse`, where `Xxx`
         # is the original method name.  For example, if the original method name
         # is `TakeSnapshot()`, the inferred response type is
         # `TakeSnapshotResponse`.
       "a_key": "", # Properties of the object. Contains field @type with type URL.
     },
     "metadata": { # Service-specific metadata associated with the operation.  It typically
         # contains progress information and common metadata such as create time.
         # Some services might not provide such metadata.  Any method that returns a
         # long-running operation should document the metadata type, if any.
       "a_key": "", # Properties of the object. Contains field @type with type URL.
     },
     "done": True or False, # If the value is `false`, it means the operation is still in progress.
         # If `true`, the operation is completed, and either `error` or `response` is
         # available.
     "name": "A String", # The server-assigned name, which is only unique within the same service that
         # originally returns it. If you use the default HTTP mapping, the
         # `name` should be a resource name ending with `operations/{unique_id}`.
     "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.
         # different programming environments, including REST APIs and RPC APIs. It is
         # used by [gRPC](https://github.com/grpc). Each `Status` message contains
         # three pieces of data: error code, error message, and error details.
         #
         # You can find out more about this error model and how to work with it in the
         # [API Design Guide](https://cloud.google.com/apis/design/errors).
       "message": "A String", # 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.
       "code": 42, # The status code, which should be an enum value of google.rpc.Code.
       "details": [ # A list of messages that carry the error details.  There is a common set of
           # message types for APIs to use.
         {
           "a_key": "", # Properties of the object. Contains field @type with type URL.
         },
       ],
     },
   }</pre>
 </div>

 </body></html>
	<html><body>
	<style>

	body, h1, h2, h3, div, span, p, pre, a {
	margin: 0;
	padding: 0;
	border: 0;
	font-weight: inherit;
	font-style: inherit;
	font-size: 100%;
	font-family: inherit;
	vertical-align: baseline;
	}

	body {
	font-size: 13px;
	padding: 1em;
	}

	h1 {
	font-size: 26px;
	margin-bottom: 1em;
	}

	h2 {
	font-size: 24px;
	margin-bottom: 1em;
	}

	h3 {
	font-size: 20px;
	margin-bottom: 1em;
	margin-top: 1em;
	}

	pre, code {
	line-height: 1.5;
	font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
	}

	pre {
	margin-top: 0.5em;
	}

	h1, h2, h3, p {
	font-family: Arial, sans serif;
	}

	h1, h2, h3 {
	border-bottom: solid #CCC 1px;
	}

	.toc_element {
	margin-top: 0.5em;
	}

	.firstline {
	margin-left: 2 em;
	}

	.method {
	margin-top: 1em;
	border: solid 1px #CCC;
	padding: 1em;
	background: #EEE;
	}

	.details {
	font-weight: bold;
	font-size: 14px;
	}

	</style>

	<h1><a href="remotebuildexecution_v2.html">Remote Build Execution API</a> . <a href="remotebuildexecution_v2.actions.html">actions</a></h1>
	<h2>Instance Methods</h2>
	<p class="toc_element">
	<code><a href="#execute">execute(instanceName, body, x__xgafv=None)</a></code></p>
	<p class="firstline">Execute an action remotely.</p>
	<h3>Method Details</h3>
	<div class="method">
	<code class="details" id="execute">execute(instanceName, body, x__xgafv=None)</code>
	<pre>Execute an action remotely.

	In order to execute an action, the client must first upload all of the
	inputs, the
	Command to run, and the
	Action into the
	ContentAddressableStorage.
	It then calls `Execute` with an `action_digest` referring to them. The
	server will run the action and eventually return the result.

	The input `Action`'s fields MUST meet the various canonicalization
	requirements specified in the documentation for their types so that it has
	the same digest as other logically equivalent `Action`s. The server MAY
	enforce the requirements and return errors if a non-canonical input is
	received. It MAY also proceed without verifying some or all of the
	requirements, such as for performance reasons. If the server does not
	verify the requirement, then it will treat the `Action` as distinct from
	another logically equivalent action if they hash differently.

	Returns a stream of
	google.longrunning.Operation messages
	describing the resulting execution, with eventual `response`
	ExecuteResponse. The
	`metadata` on the operation is of type
	ExecuteOperationMetadata.

	If the client remains connected after the first response is returned after
	the server, then updates are streamed as if the client had called
	WaitExecution
	until the execution completes or the request reaches an error. The
	operation can also be queried using Operations
	API.

	The server NEED NOT implement other methods or functionality of the
	Operations API.

	Errors discovered during creation of the `Operation` will be reported
	as gRPC Status errors, while errors that occurred while running the
	action will be reported in the `status` field of the `ExecuteResponse`. The
	server MUST NOT set the `error` field of the `Operation` proto.
	The possible errors include:

	* `INVALID_ARGUMENT`: One or more arguments are invalid.
	* `FAILED_PRECONDITION`: One or more errors occurred in setting up the
	action requested, such as a missing input or command or no worker being
	available. The client may be able to fix the errors and retry.
	* `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run
	the action.
	* `UNAVAILABLE`: Due to a transient condition, such as all workers being
	occupied (and the server does not support a queue), the action could not
	be started. The client should retry.
	* `INTERNAL`: An internal error occurred in the execution engine or the
	worker.
	* `DEADLINE_EXCEEDED`: The execution timed out.
	* `CANCELLED`: The operation was cancelled by the client. This status is
	only possible if the server implements the Operations API CancelOperation
	method, and it was called for the current execution.

	In the case of a missing input or command, the server SHOULD additionally
	send a PreconditionFailure error detail
	where, for each requested blob not present in the CAS, there is a
	`Violation` with a `type` of `MISSING` and a `subject` of
	`"blobs/{hash}/{size}"` indicating the digest of the missing blob.

	Args:
	instanceName: string, The instance of the execution system to operate against. A server may
	support multiple instances of the execution system (with their own workers,
	storage, caches, etc.). The server MAY require use of this field to select
	between them in an implementation-defined fashion, otherwise it can be
	omitted. (required)
	body: object, The request body. (required)
	The object takes the form of:

	{ # A request message for
	# Execution.Execute.
	"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.
	# The server will have a default policy if this is not provided.
	# This may be applied to both the ActionResult and the associated blobs.
	# outputs are stored in the CAS and Action Cache.
	"priority": 42, # The priority (relative importance) of this content in the overall cache.
	# Generally, a lower value means a longer retention time or other advantage,
	# but the interpretation of a given value is server-dependent. A priority of
	# 0 means a default value, decided by the server.
	#
	# The particular semantics of this field is up to the server. In particular,
	# every server will have their own supported range of priorities, and will
	# decide how these map into retention/eviction policy.
	},
	"skipCacheLookup": True or False, # If true, the action will be executed even if its result is already
	# present in the ActionCache.
	# The execution is still allowed to be merged with other in-flight executions
	# of the same action, however - semantically, the service MUST only guarantee
	# that the results of an execution with this field set were not visible
	# before the corresponding execution request was sent.
	# Note that actions from execution requests setting this field set are still
	# eligible to be entered into the action cache upon completion, and services
	# SHOULD overwrite any existing entries that may exist. This allows
	# skip_cache_lookup requests to be used as a mechanism for replacing action
	# cache entries that reference outputs no longer available or that are
	# poisoned in any way.
	# If false, the result may be served from the action cache.
	"actionDigest": { # A content digest. A digest for a given blob consists of the size of the blob # The digest of the Action to
	# execute.
	# and its hash. The hash algorithm to use is defined by the server, but servers
	# SHOULD use SHA-256.
	#
	# The size is considered to be an integral part of the digest and cannot be
	# separated. That is, even if the `hash` field is correctly specified but
	# `size_bytes` is not, the server MUST reject the request.
	#
	# The reason for including the size in the digest is as follows: in a great
	# many cases, the server needs to know the size of the blob it is about to work
	# with prior to starting an operation with it, such as flattening Merkle tree
	# structures or streaming it to a worker. Technically, the server could
	# implement a separate metadata store, but this results in a significantly more
	# complicated implementation as opposed to having the client specify the size
	# up-front (or storing the size along with the digest in every message where
	# digests are embedded). This does mean that the API leaks some implementation
	# details of (what we consider to be) a reasonable server implementation, but
	# we consider this to be a worthwhile tradeoff.
	#
	# When a `Digest` is used to refer to a proto message, it always refers to the
	# message in binary encoded form. To ensure consistent hashing, clients and
	# servers MUST ensure that they serialize messages according to the following
	# rules, even if there are alternate valid encodings for the same message:
	#
	# * Fields are serialized in tag order.
	# * There are no unknown fields.
	# * There are no duplicate fields.
	# * Fields are serialized according to the default semantics for their type.
	#
	# Most protocol buffer implementations will always follow these rules when
	# serializing, but care should be taken to avoid shortcuts. For instance,
	# concatenating two messages to merge them may produce duplicate fields.
	"sizeBytes": "A String", # The size of the blob, in bytes.
	"hash": "A String", # The hash. In the case of SHA-256, it will always be a lowercase hex string
	# exactly 64 characters long.
	},
	"executionPolicy": { # An `ExecutionPolicy` can be used to control the scheduling of the action. # An optional policy for execution of the action.
	# The server will have a default policy if this is not provided.
	"priority": 42, # The priority (relative importance) of this action. Generally, a lower value
	# means that the action should be run sooner than actions having a greater
	# priority value, but the interpretation of a given value is server-
	# dependent. A priority of 0 means the default priority. Priorities may be
	# positive or negative, and such actions should run later or sooner than
	# actions having the default priority, respectively. The particular semantics
	# of this field is up to the server. In particular, every server will have
	# their own supported range of priorities, and will decide how these map into
	# scheduling policy.
	},
	}

	x__xgafv: string, V1 error format.
	Allowed values
	1 - v1 error format
	2 - v2 error format

	Returns:
	An object of the form:

	{ # This resource represents a long-running operation that is the result of a
	# network API call.
	"response": { # The normal response of the operation in case of success. If the original
	# method returns no data on success, such as `Delete`, the response is
	# `google.protobuf.Empty`. If the original method is standard
	# `Get`/`Create`/`Update`, the response should be the resource. For other
	# methods, the response should have the type `XxxResponse`, where `Xxx`
	# is the original method name. For example, if the original method name
	# is `TakeSnapshot()`, the inferred response type is
	# `TakeSnapshotResponse`.
	"a_key": "", # Properties of the object. Contains field @type with type URL.
	},
	"metadata": { # Service-specific metadata associated with the operation. It typically
	# contains progress information and common metadata such as create time.
	# Some services might not provide such metadata. Any method that returns a
	# long-running operation should document the metadata type, if any.
	"a_key": "", # Properties of the object. Contains field @type with type URL.
	},
	"done": True or False, # If the value is `false`, it means the operation is still in progress.
	# If `true`, the operation is completed, and either `error` or `response` is
	# available.
	"name": "A String", # The server-assigned name, which is only unique within the same service that
	# originally returns it. If you use the default HTTP mapping, the
	# `name` should be a resource name ending with `operations/{unique_id}`.
	"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.
	# different programming environments, including REST APIs and RPC APIs. It is
	# used by [gRPC](https://github.com/grpc). Each `Status` message contains
	# three pieces of data: error code, error message, and error details.
	#
	# You can find out more about this error model and how to work with it in the
	# [API Design Guide](https://cloud.google.com/apis/design/errors).
	"message": "A String", # 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.
	"code": 42, # The status code, which should be an enum value of google.rpc.Code.
	"details": [ # A list of messages that carry the error details. There is a common set of
	# message types for APIs to use.
	{
	"a_key": "", # Properties of the object. Contains field @type with type URL.
	},
	],
	},
	}</pre>
	</div>

	</body></html>