Background Jobs - Run On Demand Execute

Service:

Dataflow

API Version:

v1

Note

This API is in preview.

Run on-demand execute job instance.

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/instances?jobType={jobType}

URI Parameters

Name	In	Required	Type	Description
dataflowId	path	True	string (uuid)	The dataflow ID.
workspaceId	path	True	string (uuid)	The workspace ID.
jobType	query	True	string	Execute job type. Refresh can also be used as an alias for Execute.

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

HTTP

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

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

HTTP

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

{
  "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