Managing long-running operations

This page describes how to manage the lifecycle of a Cloud Life Sciences API long-running operation (LRO).

Long-running operations are returned when method calls might take a long time to complete. The Cloud Life Sciences API creates an LRO every time you call projects.locations.pipelines.run or gcloud beta lifesciences pipelines run. The LRO tracks the status of the pipeline.

You can use the operations APIs that the Cloud Life Sciences API provides to check the status of LROs. You can also list, poll, or cancel LROs.

When calling the Cloud Life Sciences API directly, LROs are managed at the Google Cloud project and location level. When making a request to the LRO directly, include the Google Cloud project and the location in which the LRO is running.

If you have set up the gcloud tool, then when you call the Cloud Life Sciences API using the gcloud tool your request to the LRO only needs to contain the operation identifier. The Google Cloud project ID and the location where the LRO is running are inferred from the operation ID.

You can manage your Cloud Life Sciences LROs using the Google Cloud Console, the gcloud command-line tool, or by calling the API directly. The Cloud Console does not contain all of the details about an LRO that are available when using the gcloud tool and calling the Cloud Life Sciences API directly.

The record of an LRO is kept for approximately 30 days after the LRO finishes, meaning that you cannot view or list an LRO after that point.

Getting details about a long-running operation

The following samples show how to get details about an LRO.

Console

  1. In the Cloud Console, go to the Life Sciences Pipelines page.

    Go to the Life Sciences Pipelines page

  2. A list of LROs and their status displays. Find the LRO you are looking for and view its status. The possible values for the Status column are Running, Completed, and Failed.

gcloud

Suppose that you receive the following response after calling gcloud beta lifesciences pipelines run:

Running [projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID].

The response shows that the Cloud Life Sciences API created an LRO with an operation ID.

To get details about the LRO, run the gcloud beta lifesciences operations describe command, specifying the operation ID.

gcloud beta lifesciences operations describe OPERATION_ID

You can also retrieve the operation ID by listing long-running database operations.

If the request is successful, the command prompt displays the operation details. The output shown here is taken from the pipeline operation in the Quickstart.

API

To get the status of and view details about an LRO, call the projects.locations.operations.get method.

REST & CMD LINE

Suppose that you receive the following response after calling projects.locations.pipelines.run:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID"
}

The name value in the response shows that the Cloud Life Sciences API created an LRO named projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID.

You can also retrieve the LRO name by listing long-running operations.

Before using any of the request data below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location where the LRO is running
  • OPERATION_ID: the identifier for the LRO

HTTP method and URL:

GET https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

PowerShell

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content

API Explorer

Open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

You should receive a JSON response similar to the following. The output shown here is taken from the pipeline operation in the Quickstart.

Listing long-running operations

The following samples show how to list the LROs in a Google Cloud project and location.

Console

  1. In the Cloud Console, go to the Life Sciences Pipelines page.

    Go to the Life Sciences Pipelines page

  2. A list of LROs and their status displays. The possible values for the Status column are Running, Completed, and Failed.

gcloud

To list the LROs in a Google Cloud project and location, run the gcloud beta lifesciences operations list command.

gcloud beta lifesciences operations list

If the request is successful, the command prompt lists the LROs:

ID                    LOCATION     DONE
OPERATION_ID          LOCATION       {TRUE|FALSE}
...

API

To list the LROs in a Google Cloud project and location, call the projects.locations.operations.list method.

REST & CMD LINE

Before using any of the request data below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location where one or more LROs are running

HTTP method and URL:

GET https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations

PowerShell

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations" | Select-Object -Expand Content

API Explorer

Open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

You should receive a JSON response similar to the following:

{
  "operations": [
    {
      "name": "PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.lifesciences.v2beta.Metadata",
        "pipeline": {
          ...
        }
        "createTime": "CREATE_TIME",
        "startTime": "START_TIME",
        "endTime": "END_TIME"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/cloud.lifesciences.pipelines.RunPipelineResponse"
      }
    },
    ...
  ]
}

Polling a long-running operation

The following samples show how to poll the status of an LRO.

Console

  1. In the Cloud Console, go to the Life Sciences Pipelines page.

    Go to the Life Sciences Pipelines page

  2. A list of LROs and their status displays. Click the Refresh icon to see the updated status for an LRO.

gcloud

After starting a pipeline, you can poll the LRO by running the gcloud beta lifesciences operations wait command.

gcloud beta lifesciences operations wait OPERATION_ID 

If the request is successful, the command prompt displays the following:

Waiting for [projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID] to complete...

When the operation finishes, the command prompt displays the following:

Waiting for [projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID] to complete...done.

API

To poll an LRO, repeatedly call the projects.locations.operations.get method until the operation finishes. Use a backoff between each poll request, such as 10 seconds.

Before using any of the request data below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location where the LRO is running
  • OPERATION_ID: the identifier for the LRO

HTTP method and URL:

GET https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID 

To send your request, choose one of these options:

curl command

Execute the following command to poll for the status of an LRO every 10 seconds:

while true; \
    do curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    "https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"; \
    sleep 10; \
    done

You should receive a JSON response similar to the following. The output shown here is taken from the pipeline operation in the Quickstart. When the operation finishes, the response will contain "done": true and a value in the endTime field.

PowerShell

Execute the following command to poll for the status of an LRO every ten seconds:

$cred = gcloud auth print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Do {
  Invoke-WebRequest `
    -Method Get `
    -Headers $headers `
    -Uri "https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
sleep 10
}

while ($true)

You should receive a JSON response similar to the following. The output shown here is taken from the pipeline operation in the Quickstart. When the operation finishes, the response will contain "done": true and a value in the endTime field.

Cancelling a long-running operation

The following samples show how to cancel an LRO while it is running.

Console

  1. In the Cloud Console, go to the Life Sciences Pipelines page.

    Go to the Life Sciences Pipelines page

  2. Click the ID of the LRO you want to cancel.
  3. Click the Cancel icon.

gcloud

To cancel an LRO, run the gcloud beta lifesciences operations cancel command.

gcloud beta lifesciences operations cancel OPERATION_ID

If the request is successful, a cancellation prompt displays:

Operation [OPERATION_ID] will be canceled.

Do you want to continue (Y/n)?  Y

To confirm, type Y. After you confirm the cancellation, the response returns an empty body.

Operation [OPERATION_ID] will be canceled.

Do you want to continue (Y/n)?  Y

{}

API

To cancel an LRO, call the projects.locations.operations.cancel method.

REST & CMD LINE

Before using any of the request data below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location where the LRO is running
  • OPERATION_ID: the identifier for the LRO

HTTP method and URL:

POST https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel

To send your request, choose one of these options:

curl

Execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel

PowerShell

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://lifesciences.googleapis.com/v2beta/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

API Explorer

Open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

You should receive a JSON response similar to the following:

{}