Jobs

Use the jobs APIs to review job details. For more information about working with jobs, see Job objects API and asynchronous processes.

Retrieve jobs

Use the method listed in the following table to retrieve all jobs or a subset of the jobs. Specifying a tenant_id will return only the jobs belonging to that tenant.

HTTP Method Path Description Parameters

GET

/v2.1/jobs

Retrieve jobs.

tenant_id: (Optional) Return the block stores belonging to the specified tenant.

offset and limit– see Common Pagination

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "total_records": 2625,
    "sort_by": "created",
    "order_by": "desc",
    "offset": 0,
    "limit": 1,
    "records": [
      {
        "id": "5ed72c8c6342e90001439d54",
        "action": "create",
        "job_summary": "Create request is successfully submitted",
        "created": "2020-06-03T04:52:28.478Z",
        "updated": "2020-06-03T04:52:32.636Z",
        "object_id": "5ed72c8c6342e90001439d55",
        "object_type": "sg_buckets",
        "object_name": "test1234",
        "status": "successful",
        "status_detail": "Creation of s3 bucket 'test1234' completed successfully.",
        "last_error": "",
        "user_id": "5e85225af038943eb4b74684",
        "job_tasks": [
          {
            "id": "5ed72c8c6342e90001439d57",
            "job_id": "5ed72c8c6342e90001439d54",
            "action": "create",
            "driver": "storagegrid_ansible",
            "object_id": "5ed72c8c6342e90001439d55",
            "object_type": "sg_buckets",
            "resource_type": "sg_bucket",
            "status": "successful",
            "status_detail": "Worker completed task successfully.",
            "last_error": "",
            "user_id": "5e85225af038943eb4b74684",
            "request_payload": {
              "grid_account_id": "05336917559886003354",
              "grid_admin_base_url": "https://sggmi-dev.dev.ausngs.netapp.au/api/v3",
              "org_password": "netapp01",
              "org_username": "root",
              "s3_bucket_name": "test1234"
            }
          }
        ]
      }
    ]
  }
}

Retrieve a job by job ID

Use the method listed in the following table to retrieve a job by ID.

HTTP Method Path Description Parameters

GET

/v2.1/jobs/{id}

Retrieve a job by ID.

id (string): The unique identifier for the job.

Required request body attributes: job identifier

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "total_records": 1,
    "records": [
      {
        "id": "5e66f18e09a74c0001b89640",
        "action": "create",
        "job_summary": "Create S3 bucket for Sub Tenant",
        "created": "2020-03-10T01:46:54.097Z",
        "updated": "2020-03-10T01:46:57.664Z",
        "object_id": "5e66f18e09a74c0001b89641",
        "object_type": "sg_buckets",
        "status": "successful",
        "status_detail": "Creation of s3 bucket 'mys3bucket' completed successfully.",
        "last_error": "",
        "user_id": "5bbee380a2df7a04d43acaee",
        "job_tasks": [
          {
            "id": "5e66f18e09a74c0001b89642",
            "job_id": "5e66f18e09a74c0001b89640",
            "action": "create",
            "driver": "storagegrid_ansible",
            "object_id": "5e66f18e09a74c0001b89641",
            "object_type": "sg_buckets",
            "resource_type": "sg_bucket",
            "status": "successful",
            "status_detail": "Worker completed task successfully.",
            "last_error": "",
            "user_id": "5bbee380a2df7a04d43acaee",
            "request_payload": {
              "grid_account_id": "47490102387197219062",
              "grid_admin_base_url": "https://sggmi-dev.dev.ausngs.netapp.au/api/v3",
              "org_password": "netapp01",
              "org_username": "root",
              "s3_bucket_name": "mys3bucket"
            }
          }
        ]
      }
    ]
  }
}

Job objects API and asynchronous processes

Some of the API calls, particularly those that are used for adding or modifying resources, can take longer to complete than other calls. NetApp Service Engine processes these long-running requests asynchronously.

After making an API call that runs asynchronously, the HTTP response code 202 indicates the request has been successfully validated and accepted, but not yet completed. The request is processed as a background task which continues to run after the initial HTTP response to the client. The response includes the job object anchoring the request, including its unique identifier.

Querying the job object associated with an API request

The job object returned in the HTTP response contains several properties. You can query the state property to determine if the request completed successfully. A job object can be in one of the following states:

  • NORMAL

  • WARNING

  • PARTIAL_FAILURES

  • ERROR

There are two techniques you can use when polling a job object to detect a terminal state for the task, either success or failure:

  • Standard polling request: The current job state is returned immediately.

  • Long polling request: When the job state moves to NORMAL, ERROR, or PARTIAL_FAILURES.

Steps for an asynchronous request

You can use the following high-level procedure to complete an asynchronous API call:

  1. Issue the asynchronous API call.

  2. Receive an HTTP response 202 indicating successful acceptance of the request.

  3. Extract the identifier for the job object from the response body.

  4. Within a loop, wait for the job object to reach the terminal state NORMAL, ERROR, or PARTIAL_FAILURES.

  5. Verify the terminal state of the job and retrieve the job result.