Package google.longrunning

Índice

Operaciones

Administra operaciones de larga duración con un servicio de API

Cuando un método de API tarda mucho tiempo en completarse, puede diseñarse para mostrar Operation al cliente, que puede usar esta interfaz a fin de recibir la respuesta real de manera asíncrona si sondea el recurso de operación o lo pasa a otra API (como la API de Google Cloud Pub/Sub) a fin de recibir la respuesta. Cualquier servicio de API que muestre operaciones de larga duración debe implementar la interfaz Operations para que los desarrolladores puedan tener una experiencia de cliente coherente.

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty)

Inicia la cancelación asincrónica en una operación de larga duración. El servidor realiza su mejor esfuerzo para cancelar la operación, pero no se garantiza el éxito. Si el servidor no es compatible con este método, muestra google.rpc.Code.UNIMPLEMENTED. Los clientes pueden usar Operations.GetOperation o los otros métodos para comprobar si la cancelación se realizó de forma correcta o si la operación se completó a pesar de la cancelación. Si la cancelación se realiza de forma correcta, la operación no se borrará; en lugar de ello, se convertirá en una operación con un valor Operation.error con un google.rpc.Status.code de 1, que corresponde a Code.CANCELLED.

Alcances de autorización

Se necesita uno de los siguientes alcances de OAuth:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

Para obtener más información, consulta Descripción general de la autenticación.

DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

Borra una operación de larga duración. Este método indica que el cliente ya no está interesado en el resultado de la operación. No cancela la operación. Si el servidor no es compatible con este método, muestra google.rpc.Code.UNIMPLEMENTED.

Alcances de autorización

Se necesita uno de los siguientes alcances de OAuth:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

Para obtener más información, consulta Descripción general de la autenticación.

GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

Obtiene el último estado de una operación de larga duración. Los clientes pueden usar este método para consultar el resultado de la operación por intervalos según la recomendación del servicio de la API.

Alcances de autorización

Se necesita uno de los siguientes alcances de OAuth:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

Para obtener más información, consulta Descripción general de la autenticación.

ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

Enumera las operaciones que coinciden con el filtro especificado en la solicitud. Si el servidor no es compatible con este método, muestra UNIMPLEMENTED.

NOTA: La vinculación name permite que los servicios de API anulen la vinculación para usar diferentes esquemas de nombres de recursos, como users/*/operations. Para anular la vinculación, los servicios de API pueden agregar una vinculación como "/v1/{name=users/*}/operations" a la configuración del servicio. Para la retrocompatibilidad, el nombre predeterminado incluye el ID de colección de operaciones; sin embargo, los usuarios que realizan la anulación deben garantizar que la vinculación de nombre sea el recurso principal, sin el ID de colección de operaciones.

Alcances de autorización

Se necesita uno de los siguientes alcances de OAuth:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

Para obtener más información, consulta Descripción general de la autenticación.

WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

Espera hasta que la operación de larga duración especificada se completa o alcanza, como máximo, un tiempo de espera especificado, y muestra el último estado. Si la operación ya se realizó, se muestra de inmediato el estado más reciente. Si el tiempo de espera especificado es mayor que el tiempo de espera HTTP/RPC predeterminado, se usa este último. Si el servidor no es compatible con este método, muestra google.rpc.Code.UNIMPLEMENTED. Ten en cuenta que este método se basa en el mejor esfuerzo. Puede mostrar el estado más reciente antes del tiempo de espera especificado (incluso de inmediato), lo que significa que ni siquiera una respuesta inmediata es garantía de que la operación ya finalizó.

Alcances de autorización

Se necesita uno de los siguientes alcances de OAuth:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

Para obtener más información, consulta Descripción general de la autenticación.

CancelOperationRequest

El mensaje de solicitud para Operations.CancelOperation.

Campos
name

string

El nombre del recurso de la operación que se cancelará.

DeleteOperationRequest

El mensaje de solicitud para Operations.DeleteOperation.

Campos
name

string

El nombre del recurso de la operación que se borrará.

GetOperationRequest

El mensaje de solicitud para Operations.GetOperation.

Campos
name

string

El nombre del recurso de operación.

ListOperationsRequest

El mensaje de solicitud para Operations.ListOperations.

Campos
name

string

El nombre del recurso principal de la operación.

filter

string

El filtro de lista estándar.

page_size

int32

El tamaño de página de lista estándar.

page_token

string

El token de página de lista estándar.

ListOperationsResponse

El mensaje de respuesta para Operations.ListOperations.

Campos
operations[]

Operation

Una lista de operaciones que coincide con el filtro especificado en la solicitud.

next_page_token

string

El token de página siguiente de lista estándar.

Operación

Este recurso representa una operación de larga duración que es el resultado de una llamada a la API de la red.

Campos
name

string

El nombre asignado por el servidor, que solo es único dentro del mismo servicio que lo muestra en un principio. Si usas la asignación HTTP predeterminada, el name debe ser un nombre de recurso que termine con operations/{unique_id}.

metadata

Any

Metadatos específicos del servicio asociados con la operación. Por lo general, contiene información de progreso y metadatos comunes, como la fecha de creación. Puede que algunos servicios no proporcionen estos metadatos. Cualquier método que muestra una operación de larga duración debe documentar el tipo de metadatos, si corresponde.

done

bool

Si el valor es false, significa que la operación aún está en progreso. Si es true, la operación está completa, y error o response están disponibles.

Campo de unión result. El resultado de la operación, que puede ser un error o una response válida. Si done == false, no se establecen error ni response. Si done == true, se establece error o response. result puede ser uno de los siguientes:
error

Status

El resultado de error de la operación en caso de falla o cancelación.

response

Any

La respuesta normal de la operación en caso de éxito. Si el método original no muestra datos en caso de éxito, como Delete, la respuesta es google.protobuf.Empty. Si el método original es Get, Create o Update estándar, la respuesta debe ser el recurso. Para otros métodos, la respuesta debe tener el tipo XxxResponse, en la que Xxx es el nombre del método original. Por ejemplo, si el nombre del método original es TakeSnapshot(), el tipo de respuesta inferido es TakeSnapshotResponse.

WaitOperationRequest

El mensaje de solicitud para Operations.WaitOperation.

Campos
name

string

El nombre del recurso de la operación por esperar.

timeout

Duration

La duración máxima a esperar antes de que se agote el tiempo. Si se deja en blanco, la espera será como máximo el tiempo que permite el protocolo HTTP/RPC subyacente. Si también se especifica el plazo del contexto de  RPC, se usará el que resulte más corto.