Edit

Long running operations

  • Article

Long running operations pattern for Fabric APIs behaves in the following manner, if the operation that was started by the initiating API was completed by the time the response is sent, you will get the result in the response, if not then you will get an operation ID in the x-ms-operation-id header of the response, and in the location header you will get the URL for the next API you will need to call.

Initiating API responses

You will get one of two responses:

  • Operation completed, status code 201 created or 200 OK: the operation is completed, and the result (if exists) is returned in the body.

  • Operation ongoing, status code 202 accepted: this means the operation is ongoing, and the next steps would be to poll on the state until the operation is complete and then to get the result (if exists).

Another header that is returned in case of a long running operation is the Retry-After header, which should be used to set the intervals of time (in second) for the polling loop.

Polling on state and getting result

There are two approaches you can take for polling on state and getting the result once the operation is completed:

  • Using location header: the location header that will be returned to you while the operation is still running is the Get Operation State API with the operation ID for the ongoing operation. Once the operation has completed running the location header that is returned is the Get Operation Result API with the operation ID, which will get you the result.

  • Using x-ms-operation-id: you can build the API calls that are returned in the operation header yourself, by using the x-ms-operation-id header that is returned in the response of the initial call. Pull on the state with Get Operation State API, using the operation ID, and get the result with Get Operation Result API (using the operation ID).

C# code sample for polling the operation state

// Get operationUrl from location header or by building it with operation ID and Get State API.  
do 
{ 
  Thread.Sleep(retryAfter * 1000); // Get retryAfter value from Retry-After header. 
  response = client.GetAsync(operationUrl).Result;  
  jsonOperation = response.Content.ReadAsStringAsync().Result; 
  operation = JsonSerializer.Deserialize<FabricOperation>(jsonOperation); 
} while (operation.status != "Succeeded" && operation.status != "Failed");

Item creation example

  1. Create item - Notebook

    1. Notebook 1 - got 201-Created http status code. Response body:
     { 
     "id": "551e6a4d-d81a-4079-b08c-25cec3cebba9", 
     "type": "Notebook", 
     "displayName": "Notebook1", 
     "description": "", 
     "workspaceId": "a91e61ef-862e-4611-9d09-9c7cc07b2519" 
 }
    1. Notebook 2 - got 202-Accepted http status code. Response headers:
      1. Retry-After: 20
      2. x-ms-operation-id: b80e135a-adca-42e7-aaf0-59849af2ed78
      3. Location: https://api.fabric.microsoft.com/v1/operations/b80e135a-adca-42e7-aaf0-59849af2ed78

  2. Get operation state for Notebook 2:

    1. Get operation state API: https://api.fabric.microsoft.com/v1/operations/b80e135a-adca-42e7-aaf0-59849af2ed78
    2. Operation is still running - got 200-OK http status code. Response body:
     { 
   "status": "Running", 
   "createdTimeUtc": "2023-11-13T22:24:40.477Z", 
   "lastUpdatedTimeUtc": "2023-11-13T22:24:41.532Z", 
   "percentComplete": 25 
 }
    1. Operation is completed - got 200-OK http status code. Response body:
     { 
   "status": "Succeeded", 
   "createdTimeUtc": "2023-11-13T22:25:06.1193103", 
   "lastUpdatedTimeUtc": "2023-11-13T22:25:09.0255787", 
   "percentComplete": 100, 
   "error": null 
 }

  3. Get operation result for Notebook 2

    1. Get operation result API: https://api.fabric.microsoft.com/v1/operations/b80e135a-adca-42e7-aaf0-59849af2ed78/result
    2. Got 200-OK http status code, Response body:
    { 
 "id": "221a6eea-0f27-41eb-bcc5-e4d7b216ed43", 
 "type": "Notebook", 
 "displayName": " Notebook2", 
 "description": "", 
 "workspaceId": "a91e61ef-862e-4611-9d09-9c7cc07b2519" 
}