기술 자료

Workflow Engine API

Workflow Engine API

Workflow Engine API

Introduction

The Workflow Engine API enables you to create, trigger, and monitor RT3D templates in the cloud. It offers built-in templates for common RT3D data preparation (convert, optimize, transform) so your assets can be interoperable. You can also create your own custom templates to be used by members of your organization. This helps scale your workload, eliminate repetitive tasks, and improve data integrity.
With the Workflow Engine API you can:
  • Run built-in RT3D templates offered by Unity Technologies using industry leading solutions like Pixyz
  • Run custom templates with your own operators using custom scripts
  • Monitor jobs and debug your custom templates

Get Started

Prerequisites: You have a Unity account. To get started, you will first need to create a service account and assign suitable roles for it. Note that you must be an Organization Owner to manage service accounts.

Set up a service account

You can find information on how to create a service account here. After the service account has been created, you will need to authenticate an API and choose the roles that would be assigned to it.

Authentication & Authorization

To learn how to authenticate your requests, please visit the Admin API authentication page.

Roles and Permissions

The service account must have the relevant access to be able to call the APIs. The Workflow Engine API uses the Automation roles. Please see below for the available service account roles and their corresponding access rights:

Role

Access Rights

Automation DeveloperGrants full read and write access.
Automation UserGrants access to the read, list and trigger endpoints. Also grants access to retry and terminate job.
Automation ViewerGrants access to the read and list endpoints.
You can learn more about the Automation roles available on the Admin API authentication page under St (Storage and transformation) section.

Guides

This section contains guides on how to use the API.

Jobs

Get job list

You can retrieve jobs from your organization in a paginated list and narrow the results using filters via [GET /workflow-engine/v1/organizations/{organizationId}/jobs]. The available filters are:
  • inputDatasetId
  • inputDatasetVersion
  • outputDatasetId
  • outputDatasetVersion
  • status
  • template

Monitor a Job

With a job id, you can directly view the state of a job by calling [GET /workflow-engine/v1/organizations/{organizationId}/jobs/{id}]. The response can be used to determine the progress of the job and its individual steps. If its status equals succeeded then it will also contain any output data generated from the workflow.

Retry a Job

With a job id, you can retry a job that failed by calling [PUT /workflow-engine/v1/organizations/{organizationId}/jobs/{id}/retry].

Terminate a Job

With a job id, you can terminate a job that is running by calling [PUT /workflow-engine/v1/organizations/{organizationId}/jobs/{id}/terminate].

Custom Templates

Get custom template list

You can retrieve the list of custom template for your organization via [GET /workflow-engine/v1/organizations/{organizationId}/templates].

Get custom template details

With a custom template's id you can retrieve the template details by calling [GET /workflow-engine/v1/organizations/{organizationId}/templates/{template_id}].

Trigger custom template by id

With a custom template's id you can trigger a template by calling [POST /workflow-engine/v1/organizations/{organizationId}/templates/{template_id}/trigger].
Download OpenAPI specification:

List workflow jobs

Returns list of workflow jobs scoped by organization with optional filters.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

Query parameters for "{title}"

inputDatasetId

string
example: b40397bf-ef96-4106-ab01-4a0dea914aa6
UUID of the input dataset

inputDatasetVersion

string
example: b40397bf-ef96-4106-ab01-4a0dea914aa6
UUID of the input dataset version

outputDatasetId

string
example: b40397bf-ef96-4106-ab01-4a0dea914aa6
UUID of the output dataset

outputDatasetVersion

string
example: b40397bf-ef96-4106-ab01-4a0dea914aa6
UUID of the output dataset version

status

string
example: Running
Status of the workflow job

template

string
example: My Custom Workflow
Name of the workflow template

limit

integer
기본: 10
example: 10
The maximum number of records to return

offset

기본: 0
example: 0
Offset of the records to return

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs"

Response example

{ "offset": 0, "limit": 0, "total": 0, "results": [ { "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "user_id": "5772981717015", "organization_id": "5772981717015", "from_template": "b40397bf-ef96-4106-ab01-4a0dea914aa6", "template_name": "my-template", "started_at": "2023-02-13T23:17:22+00:00", "finished_at": "2023-02-13T23:17:22+00:00", "duration_in_seconds": 1900, "progress": 100, "error": "Error (exit code 255)", "steps": [ { "id": "file-import-template-2fpj4-3759637542", "name": "download-dataset", "status": "Failed", "error": "Error code 404", "host_node_name": "file-import-template-2fpj4-workspace-index-download-3759637542", "progress": "0.1", "started_at": "2023-02-13T21:45:52+00:00", "finished_at": "2023-02-13T22:45:52+00:00", "duration_seconds": 0 } ], "resource_duration": { "cpu": 1000, "memory": 1000 }, "results": { "step0": { "/output/model.glb": "/api/datasets/822d400b-8565-428b/versions/db127388-adc754a01a9a" } }, "input_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "output_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "outputs": [ { "name": "string", "value": "string" } ], "external_workflow_id": "123e4567-e89b-12d3-a456-426614174000", "updated_at": "2023-02-13T23:17:22+00:00" } ]}

Get workflow job details

Get a workflow job details by providing its ID.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

id

string
필수
Workflow job id

Query parameters for "{title}"

force_refresh

boolean
기본: false
example: true
enforce job synchronization

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs/{id}"

Response example

{ "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "user_id": "5772981717015", "organization_id": "5772981717015", "from_template": "b40397bf-ef96-4106-ab01-4a0dea914aa6", "template_name": "my-template", "started_at": "2023-02-13T23:17:22+00:00", "finished_at": "2023-02-13T23:17:22+00:00", "duration_in_seconds": 1900, "progress": 100, "error": "Error (exit code 255)", "steps": [ { "id": "file-import-template-2fpj4-3759637542", "name": "download-dataset", "status": "Failed", "error": "Error code 404", "host_node_name": "file-import-template-2fpj4-workspace-index-download-3759637542", "progress": "0.1", "started_at": "2023-02-13T21:45:52+00:00", "finished_at": "2023-02-13T22:45:52+00:00", "duration_seconds": 0 } ], "resource_duration": { "cpu": 1000, "memory": 1000 }, "results": { "step0": { "/output/model.glb": "/api/datasets/822d400b-8565-428b/versions/db127388-adc754a01a9a" } }, "input_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "output_datasets": [ { "dataset_id": "", "dataset_version": "string", "uri": "string" } ], "outputs": [ { "name": "string", "value": "string" } ], "external_workflow_id": "123e4567-e89b-12d3-a456-426614174000", "updated_at": "2023-02-13T23:17:22+00:00"}

List custom templates

List custom templates for your Organization.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

Query parameters for "{title}"

creatorId

Template's Creator ID

offset

기본: 0
example: 0
Offset to list from

limit

integer
기본: 10
example: 10
The maximum number of templates to return

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates"

Response example

{ "offset": 0, "limit": 0, "total": 0, "results": [ { "id": "string", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "name": "string", "labels": {}, "description": "string", "creator_id": "string", "annotations": {}, "spec": { "name": "My Custom Workflow", "parameters": [ { "name": "inputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" }, { "name": "inputDatasetVersion", "required": false, "type": "str", "defaultValue": "latest" }, { "name": "outputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" } ], "mounts": [ { "path": "/workspace/inputs", "url": "https://dt.unity.com/api/datasets/{{ inputDatasetId }}/versions/{{ inputDatasetVersion }}" } ], "artifacts": [ { "path": "/workspace/directorylist.txt", "url": "https://dt.unity.com/api/datasets/{{ outputDatasetId }}" } ], "steps": [ { "name": "job-2", "image": "us-central1-docker.pkg.dev/unity-vert-reflect-mgmt/docker/pixyz-compute_engine_cpu:2022.2.0.7", "command": [ "bash" ], "args": [ "find", "/workspace", ">", "/workspace/directorylist.txt" ], "outputs": [ { "name": "OutputDirectoryList", "valueFrom": { "path": "/workspace/directorylist.txt" }, "default": "Empty" } ] } ] }, "inputs": [ { "name": "", "description": "", "defaultValue": null, "type": "str", "required": true, "metadata": {} } ], "organization_ids": [ "string" ], "type": "string" } ]}

Retry a job

Retry a job by providing its ID.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

job_id

string
필수
Job id to retry

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X PUT \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs/{job_id}/retry"

Response example

{ "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "created_at": "2023-02-13T22:46:01+00:00"}

Terminate a job

Terminate a job by providing its ID.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

job_id

string
필수
Job id to terminate

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X PUT \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/jobs/{job_id}/terminate"

Response example

{ "status": "string"}

Get custom template details

Get a custom template details for your Organization by providing its template ID.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

template_id

string
필수
WorkflowTemplate ID

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates/{template_id}"

Response example

{ "id": "string", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "name": "string", "labels": {}, "description": "string", "creator_id": "string", "annotations": {}, "spec": { "name": "My Custom Workflow", "parameters": [ { "name": "inputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" }, { "name": "inputDatasetVersion", "required": false, "type": "str", "defaultValue": "latest" }, { "name": "outputDatasetId", "required": true, "type": "str", "defaultValue": "9d618978-0ba1-4961-9086-caa69a898304" } ], "mounts": [ { "path": "/workspace/inputs", "url": "https://dt.unity.com/api/datasets/{{ inputDatasetId }}/versions/{{ inputDatasetVersion }}" } ], "artifacts": [ { "path": "/workspace/directorylist.txt", "url": "https://dt.unity.com/api/datasets/{{ outputDatasetId }}" } ], "steps": [ { "name": "job-2", "image": "us-central1-docker.pkg.dev/unity-vert-reflect-mgmt/docker/pixyz-compute_engine_cpu:2022.2.0.7", "command": [ "bash" ], "args": [ "find", "/workspace", ">", "/workspace/directorylist.txt" ], "outputs": [ { "name": "OutputDirectoryList", "valueFrom": { "path": "/workspace/directorylist.txt" }, "default": "Empty" } ] } ] }, "inputs": [ { "name": "", "description": "", "defaultValue": null, "type": "str", "required": true, "metadata": {} } ], "organization_ids": [ "string" ], "type": "string"}

Trigger a custom template

Trigger a custom template for your Organization by providing its template ID.
Authorizations
Client (Client)
HTTP: Client
HTTP Authorization Scheme: bearer
Required scopes: Client
ServiceAccount (ServiceAccount)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: basic
Required scopes: ServiceAccount

Path parameters for "{title}"

organizationId

string
필수
example: 3973850012340
The active Organization ID

template_id

string
필수
Template ID

Request body for "{title}"

Media Type:
application/json
Schema:
The request body for a template is defined by the parameters outlined in its 
WorkflowTemplate.inputs
. The fields in the body correspond with the 
name
of each input parameter and their values must adhere to its defined 
type
. Required parameters must be included in the request body, while optional parameters can be omitted.
{}

HTTP response status codes for "{title}":

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{}' \ "https://services.api.unity.com/workflow-engine/v1/organizations/{organizationId}/templates/{template_id}/trigger"

Response example

{ "id": "c2535cac-969d-4cab-b7b5-9c8b4c7d4658", "name": "my-first-custom-workflow-zpjdt", "status": "Failed", "inputs": {}, "errors": [ { "message": "string", "code": "400" } ], "created_at": "2023-02-13T22:46:01+00:00"}