Modify a job - Reality Data Analysis

Reality Data Analysis

Download API definition:

This API is a Technical Preview and is available for testing purposes only. Do not use in production.

PATCH https://qa-api.bentley.com/realitydataanalysis/jobs/{jobId}

Patch an existing job

Patch can be used for changing the job state (to active or cancelled), updating job type and settings or changing cost estimation parameters.

Authentication

Requires Authorization header with valid Bearer token for scope realitydataanalysis:modify.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request headers

Authorization

Yes

OAuth access token with scope realitydataanalysis:modify

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Job Patch

state

Only 'Active' or 'Cancelled' are valid values, see tutorials.

costEstimationParameters

New cost estimation parameters.

type

jobType

New job type (requires compatible settings)

settings

One of: objects2DSettingsIn segmentation2DSettingsIn

New settings for this job, must be in sync with type

Example

json

{
    "type": "objects2D",
    "settings": {
        "inputs": [{
                "name": "photos",
                "realityDataId": "e9803e0e-70ce-4ea6-b2ad-1c653cbf2f76"
            },
            {
                "name": "photoObjectDetector",
                "realityDataId": "111d3524-2bd3-46c4-9bf4-e0c650f5f8f2"
            }
        ],
        "outputs": ["objects2D"]
    }
}

Job Patch

state

Only 'Active' or 'Cancelled' are valid values, see tutorials.

costEstimationParameters

New cost estimation parameters.

type

jobType

New job type (requires compatible settings)

settings

One of: objects2DSettingsIn segmentation2DSettingsIn

New settings for this job, must be in sync with type

Example

json

{
    "costEstimationParameters": {
        "gigaPixels": 2,
        "numberOfPhotos": 150
    }
}

Job Patch

state

Only 'Active' or 'Cancelled' are valid values, see tutorials.

costEstimationParameters

New cost estimation parameters.

type

jobType

New job type (requires compatible settings)

settings

One of: objects2DSettingsIn segmentation2DSettingsIn

New settings for this job, must be in sync with type

Example

json

{
    "state": "active"
}

Response 200 OK

Created

json

{
    "job": {
        "state": "unsubmitted",
        "settings": {
            "outputs": [{
                "name": "objects2D",
                "realityDataId": "00000000-0000-0000-0000-000000000000"
            }],
            "inputs": [{
                    "name": "photos",
                    "realityDataId": "00000000-0000-0000-0000-000000000000"
                },
                {
                    "name": "photoObjectDetector",
                    "realityDataId": "00000000-0000-0000-0000-000000000000"
                }
            ]
        },
        "createdDateTime": "2021-11-04T14:13:27Z",
        "lastModifiedDateTime": "2021-11-04T14:13:27Z",
        "id": "6f51448f-6377-4330-9ab0-f13fe994b3f1",
        "email": "Joffrey.Germain@bentley.com",
        "dataCenter": "EastUs",
        "type": "objects2D",
        "name": "My first objects2D job",
        "projectId": "510cd1a3-3703-4729-b08c-fecd9c87c3be",
        "costEstimation": {
            "gigaPixels": 2,
            "sceneWidth": 4.5,
            "sceneHeight": 3.0,
            "sceneLength": 1.7,
            "detectorScale": 1.2,
            "detectorCost": 1.4,
            "numberOfPhotos": 150,
            "estimatedCost": 2.1
        }
    }
}

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
}

Response 404 Not Found

Not Found

json

{
    "error": {
        "code": "JobNotFound",
        "message": "Requested job is not available."
    }
}

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

json

{
    "error": {
        "code": "InvalidRealityDataAnalysisRequest",
        "message": "Cannot modify job.",
        "details": [{
            "code": "InvalidChange",
            "message": "Cannot resubmit an already submitted job."
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

Job type

Available job types among 'objects2D', 'segmentation2D'.

objects2D

String

segmentation2D

String

json

{
    "title": "Job type",
    "enum": [
        "objects2D",
        "segmentation2D"
    ],
    "description": "Available job types among 'objects2D', 'segmentation2D'."
}

Job state

Possible state of a job among 'unsubmitted', 'active', 'success', 'failed' and 'cancelled'.

unsubmitted

String

active

String

success

String

failed

String

cancelled

String

json

{
    "title": "Job state",
    "enum": [
        "unsubmitted",
        "active",
        "success",
        "failed",
        "cancelled"
    ],
    "description": "Possible state of a job among 'unsubmitted', 'active', 'success', 'failed' and 'cancelled'."
}

Input format

Input format available for inputs. Refer to tutorials for per job type list.

photos

String

photoObjectDetector

String

json

{
    "title": "Input format",
    "enum": [
        "photos",
        "photoObjectDetector"
    ],
    "description": "Input format available for inputs. Refer to tutorials for per job type list."
}

Job Input

Input description for an Objects 2D job

name

jobO2DInputFormat

Input name

realityDataId

String

Reality Data id of the input

json

{
    "type": "object",
    "title": "Job Input",
    "description": "Input description for an Objects 2D job",
    "properties": {
        "name": {
            "$ref": "#/components/schemas/jobO2DInputFormat",
            "description": "Input name"
        },
        "realityDataId": {
            "type": "string",
            "description": "Reality Data id of the input"
        }
    }
}

Input format

Input format available for inputs. Refer to tutorials for per job type list.

photos

String

photoSegmentationDetector

String

orthophoto

String

orthophotoSegmentationDetector

String

json

{
    "title": "Input format",
    "enum": [
        "photos",
        "photoSegmentationDetector",
        "orthophoto",
        "orthophotoSegmentationDetector"
    ],
    "description": "Input format available for inputs. Refer to tutorials for per job type list."
}

Job Input

Input description for a Segmentation 2D job

name

jobS2DInputFormat

Input name

realityDataId

String

Reality Data id of the input

json

{
    "type": "object",
    "title": "Job Input",
    "description": "Input description for a Segmentation 2D job",
    "properties": {
        "name": {
            "$ref": "#/components/schemas/jobS2DInputFormat",
            "description": "Input name"
        },
        "realityDataId": {
            "type": "string",
            "description": "Reality Data id of the input"
        }
    }
}

Output format

Output format available for outputs. Refer to tutorials for per job type list.

objects2D

String

segmentation2D

String

json

{
    "title": "Output format",
    "enum": [
        "objects2D",
        "segmentation2D"
    ],
    "description": "Output format available for outputs. Refer to tutorials for per job type list."
}

Job Output

Output description for a job

name

jobOutputFormat

Output name

realityDataId

String, null

Reality Data id of the output

json

{
    "type": "object",
    "title": "Job Output",
    "description": "Output description for a job",
    "properties": {
        "name": {
            "$ref": "#/components/schemas/jobOutputFormat",
            "description": "Output name"
        },
        "realityDataId": {
            "type": "string",
            "description": "Reality Data id of the output",
            "nullable": true
        }
    }
}

Input Objects2D Settings

Settings for an Objects2D job

inputs

jobO2DInput[]

List of inputs of the job

outputs

jobOutputFormat[]

List of output formats of the job

json

{
    "type": "object",
    "title": "Input Objects2D Settings",
    "description": "Settings for an Objects2D job",
    "properties": {
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobO2DInput"
            },
            "description": "List of inputs of the job"
        },
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutputFormat"
            },
            "description": "List of output formats of the job"
        }
    },
    "required": [
        "inputs",
        "outputs"
    ]
}

Input Segmentation2D Settings

Input settings for a Segmentation2D job

inputs

jobS2DInput[]

List of inputs of the job

outputs

jobOutputFormat[]

List of output formats of the job

json

{
    "type": "object",
    "title": "Input Segmentation2D Settings",
    "description": "Input settings for a Segmentation2D job",
    "properties": {
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobS2DInput"
            },
            "description": "List of inputs of the job"
        },
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutputFormat"
            },
            "description": "List of output formats of the job"
        }
    },
    "required": [
        "inputs",
        "outputs"
    ]
}

Cost Estimation Parameters

Optional parameters for estimating job cost before its processing

gigaPixels

Double, null

Number of giga pixels in inputs

numberOfPhotos

Int32, null

Number of photos in inputs

sceneWidth

Double, null

Width of the scene

sceneHeight

Double, null

Height of the scene

sceneLength

Double, null

Length of the scene

detectorScale

Double, null

Scale of the detector

detectorCost

Double, null

Cost of the detector

json

{
    "type": "object",
    "title": "Cost Estimation Parameters",
    "description": "Optional parameters for estimating job cost before its processing",
    "properties": {
        "gigaPixels": {
            "description": "Number of giga pixels in inputs",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "numberOfPhotos": {
            "type": "integer",
            "description": "Number of photos in inputs",
            "format": "int32",
            "nullable": true
        },
        "sceneWidth": {
            "description": "Width of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneHeight": {
            "description": "Height of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneLength": {
            "description": "Length of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorScale": {
            "description": "Scale of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorCost": {
            "description": "Cost of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        }
    }
}

Job Patch

Patch information to be applied

state

Only 'Active' or 'Cancelled' are valid values, see tutorials.

costEstimationParameters

New cost estimation parameters.

type

jobType

New job type (requires compatible settings)

settings

One of: objects2DSettingsIn segmentation2DSettingsIn

New settings for this job, must be in sync with type

json

{
    "type": "object",
    "title": "Job Patch",
    "description": "Patch information to be applied",
    "properties": {
        "state": {
            "$ref": "#/components/schemas/state",
            "description": "Only 'Active' or 'Cancelled' are valid values, see tutorials."
        },
        "costEstimationParameters": {
            "$ref": "#/components/schemas/costEstimationParameters",
            "description": "New cost estimation parameters."
        },
        "type": {
            "$ref": "#/components/schemas/jobType",
            "description": "New job type (requires compatible settings)"
        },
        "settings": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/objects2DSettingsIn"
                },
                {
                    "$ref": "#/components/schemas/segmentation2DSettingsIn"
                }
            ],
            "description": "New settings for this job, must be in sync with type"
        }
    }
}

Complete Objects2D Settings

Settings for an Objects2D job

inputs

jobO2DInput[]

List of inputs of the job

outputs

jobOutput[]

List of output formats of the job

json

{
    "type": "object",
    "title": "Complete Objects2D Settings",
    "description": "Settings for an Objects2D job",
    "properties": {
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobO2DInput"
            },
            "description": "List of inputs of the job"
        },
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutput"
            },
            "description": "List of output formats of the job"
        }
    }
}

Complete Segmentation2D Settings

Settings for an Segmentation2D job

inputs

jobS2DInput[]

List of inputs of the job

outputs

jobOutput[]

List of output formats of the job

json

{
    "type": "object",
    "title": "Complete Segmentation2D Settings",
    "description": "Settings for an Segmentation2D job",
    "properties": {
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobS2DInput"
            },
            "description": "List of inputs of the job"
        },
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutput"
            },
            "description": "List of output formats of the job"
        }
    }
}

Execution information

Execution details regarding a job

exitCode

Integer, null

Exit code of the processing

submissionDateTime

Date-time, null

Submission date time of the job

startedDateTime

Date-time, null

Start date time of the job

endedDateTime

Date-time, null

End date time of the job

estimatedUnits

Double, null

Estimated cost of the executed job

json

{
    "title": "Execution information",
    "description": "Execution details regarding a job",
    "type": "object",
    "properties": {
        "exitCode": {
            "type": "integer",
            "description": "Exit code of the processing",
            "nullable": true
        },
        "submissionDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Submission date time of the job",
            "nullable": true
        },
        "startedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Start date time of the job",
            "nullable": true
        },
        "endedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "End date time of the job",
            "nullable": true
        },
        "estimatedUnits": {
            "description": "Estimated cost of the executed job",
            "type": "number",
            "format": "double",
            "nullable": true
        }
    }
}

Cost Estimation information

Cost estimate based on parameters before job processing

gigaPixels

Double, null

Number of giga pixels in inputs

numberOfPhotos

Int32, null

Number of photos in inputs

sceneWidth

Double, null

Width of the scene

sceneHeight

Double, null

Height of the scene

sceneLength

Double, null

Length of the scene

detectorScale

Double, null

Scale of the detector

detectorCost

Double, null

Cost of the detector

estimatedCost

Double

Estimated Cost of the job using the CostEstimationParameters

json

{
    "type": "object",
    "title": "Cost Estimation information",
    "description": "Cost estimate based on parameters before job processing",
    "properties": {
        "gigaPixels": {
            "description": "Number of giga pixels in inputs",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "numberOfPhotos": {
            "type": "integer",
            "description": "Number of photos in inputs",
            "format": "int32",
            "nullable": true
        },
        "sceneWidth": {
            "description": "Width of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneHeight": {
            "description": "Height of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneLength": {
            "description": "Length of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorScale": {
            "description": "Scale of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorCost": {
            "description": "Cost of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "estimatedCost": {
            "type": "number",
            "description": "Estimated Cost of the job using the CostEstimationParameters",
            "format": "double"
        }
    }
}

Job

Job complete details

String

Job id

String

User email address

state

Job state

type

jobType

Job type

name

String

Job name

projectId

String

Project Id

settings

One of: objects2DSettings segmentation2DSettings

Settings for this job, must be in sync with type

createdDateTime

Date-time

Created date time of the job

lastModifiedDateTime

Date-time

Date time of the latest modification of the job

executionInformation

Execution Information of the job

costEstimation

Cost estimation before job processing

dataCenter

String

Data center location of the job

json

{
    "type": "object",
    "title": "Job",
    "description": "Job complete details",
    "properties": {
        "id": {
            "type": "string",
            "description": "Job id"
        },
        "email": {
            "type": "string",
            "description": "User email address"
        },
        "state": {
            "$ref": "#/components/schemas/state",
            "description": "Job state"
        },
        "type": {
            "$ref": "#/components/schemas/jobType",
            "description": "Job type"
        },
        "name": {
            "type": "string",
            "description": "Job name"
        },
        "projectId": {
            "type": "string",
            "description": "Project Id"
        },
        "settings": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/objects2DSettings"
                },
                {
                    "$ref": "#/components/schemas/segmentation2DSettings"
                }
            ],
            "description": "Settings for this job, must be in sync with type"
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Created date time of the job"
        },
        "lastModifiedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Date time of the latest modification of the job"
        },
        "executionInformation": {
            "$ref": "#/components/schemas/executionInformation",
            "description": "Execution Information of the job"
        },
        "costEstimation": {
            "$ref": "#/components/schemas/costEstimation",
            "description": "Cost estimation before job processing"
        },
        "dataCenter": {
            "type": "string",
            "description": "Data center location of the job"
        }
    }
}

Job response

job

Complete job details

json

{
    "title": "Job response",
    "type": "object",
    "properties": {
        "job": {
            "$ref": "#/components/schemas/job",
            "description": "Complete job details"
        }
    },
    "required": [
        "job"
    ]
}

error-response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error.code

String

One of a server-defined set of error codes.

error.message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "type": "object",
            "description": "The error object.",
            "properties": {
                "code": {
                    "type": "string",
                    "description": "One of a server-defined set of error codes."
                },
                "message": {
                    "type": "string",
                    "description": "A human-readable representation of the error."
                }
            }
        }
    }
}

Error

Contains error information and an optional array of more specific errors.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

details

ErrorDetails[]

Optional array of more specific errors.

json

{
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
}

Error Details

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

json

{
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
}

Error Response

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
}

On this page

Was this page helpful?