Edit

Share via

Background Jobs - Run On Demand Execute

Service:
Dataflow
API Version:
v1

Run on-demand execute job instance.

Note

This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use. The URL for this API has been updated to include the job type as part of the path, replacing the previous use of a query parameter. For backward compatibility, invocations using the query parameter are still supported.

Required Delegated Scopes

For dataflows APIs use these scope types:

  • Specific scope: Dataflow.Execute.All

for more information about scopes, see: scopes article.

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity Support
User Yes
Service principal and Managed identities No

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/Execute/instances

URI Parameters

Name In Required Type Description
dataflowId
 path True

string (uuid)

The dataflow ID.
workspaceId
 path True

string (uuid)

The workspace ID.

Request Body

Name Type Description
executionData

DataflowExecutionPayload

Payload for run on-demand execute job request. Needed only if the dataflow has parameterization enabled.

Responses

Name Type Description
202 Accepted

Request accepted, job execution is in progress.

Headers

  • Location: string
  • Retry-After: integer
Other Status Codes

ErrorResponse

Common error codes:

  • InsufficientPrivileges - The caller does not have sufficient permissions to run job instance.

  • InvalidJobType - The requested job type is invalid.

  • TooManyRequestsForJobs - The caller requests too many on-demand job requests.

  • ItemNotFound - Requested item ID not found.

Examples

Run dataflow Execute job instance with no request body example
Run dataflow Execute job instance with request body containing parameters example

Run dataflow Execute job instance with no request body example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/dataflows/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/Execute/instances

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/instances/bbbbbbbb-1111-2222-3333-cccccccccccc
Retry-After: 60

Run dataflow Execute job instance with request body containing parameters example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/dataflows/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/Execute/instances

{
  "executionData": {
    "executeOption": "ApplyChangesIfNeeded",
    "parameters": [
      {
        "parameterName": "OrderKey",
        "type": "Automatic",
        "value": 25
      },
      {
        "parameterName": "Threshold",
        "type": "Automatic",
        "value": "start"
      }
    ]
  }
}

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/instances/bbbbbbbb-1111-2222-3333-cccccccccccc
Retry-After: 60

Definitions

Name Description
DataflowExecutionPayload

The execution data payload for Dataflow
ErrorRelatedResource

The error related resource details object.
ErrorResponse

The error response.
ErrorResponseDetails

The error response details.
ExecuteOption

Options to run the execute operation. Additional executeOptions may be added over time.
ItemJobParameter

Parameter details.
RunOnDemandDataflowExecuteJobRequest

Run on demand execute dataflow job instance payload
Type

The parameter type. Additional parameter types may be added over time.

DataflowExecutionPayload

Object

The execution data payload for Dataflow

Name Type Description
executeOption

ExecuteOption

Options to run the execute operation. Additional executeOptions may be added over time.
parameters

ItemJobParameter[]

A list of parameters to override during execution.

ErrorRelatedResource

Object

The error related resource details object.

Name Type Description
resourceId

string

The resource ID that's involved in the error.
resourceType

string

The type of the resource that's involved in the error.

ErrorResponse

Object

The error response.

Name Type Description
errorCode

string

A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message

string

A human readable representation of the error.
moreDetails

ErrorResponseDetails[]

List of additional error details.
relatedResource

ErrorRelatedResource

The error related resource details.
requestId

string

ID of the request associated with the error.

ErrorResponseDetails

Object

The error response details.

Name Type Description
errorCode

string

A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message

string

A human readable representation of the error.
relatedResource

ErrorRelatedResource

The error related resource details.

ExecuteOption

Enumeration

Options to run the execute operation. Additional executeOptions may be added over time.

Value Description
SkipApplyChanges

Default Value. Apply Changes operation is skipped.
ApplyChangesIfNeeded

Appply Changes operation is done if needed. Can be used when the latest changes are required for Execute.

ItemJobParameter

Object

Parameter details.

Name Type Description
parameterName

string

Name of the parameter.
type

Type

The parameter type. Additional parameter types may be added over time.
value

The value of the parameter to override during execution.

RunOnDemandDataflowExecuteJobRequest

Object

Run on demand execute dataflow job instance payload

Name Type Description
executionData

DataflowExecutionPayload

Payload for run on-demand execute job request. Needed only if the dataflow has parameterization enabled.

Type

Enumeration

The parameter type. Additional parameter types may be added over time.

Value Description
Automatic

Value must be Automatic