> ## Documentation Index > Fetch the complete documentation index at: https://docs.eorion.com/llms.txt > Use this file to discover all available pages before exploring further. # 获取并锁定任务 > Fetches and locks a specific number of external tasks for execution by a worker. Query can be restricted to specific task topics and for each task topic an individual lock time can be provided. ## OpenAPI ````yaml POST /external-task/fetchAndLock openapi: 3.0.2 info: title: ORION Platform REST API description: OpenApi Spec for ORION Camunda Platform REST API. version: 7.22.6-ee license: name: Apache License 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: http://{host}:{port}/{contextPath} description: The API server for the default process engine variables: host: default: localhost port: default: '8080' contextPath: default: engine-rest - url: http://{host}:{port}/{contextPath}/engine/{engineName} description: The API server for a named process engine variables: host: default: localhost port: default: '8080' contextPath: default: engine-rest engineName: default: default - url: '{url}' description: The API server with a custom url variables: url: default: '' security: - basicAuth: [] tags: - name: Authorization - name: Batch - name: Condition - name: Decision Definition - name: Decision Requirements Definition - name: Deployment - name: Engine - name: Event Subscription - name: Execution - name: External Task - name: Filter - name: Group - name: Historic Activity Instance - name: Historic Batch - name: Historic Decision Definition - name: Historic Decision Instance - name: Historic Decision Requirements Definition - name: Historic Detail - name: Historic External Task Log - name: Historic Identity Link Log - name: Historic Incident - name: Historic Job Log - name: Historic Process Definition - name: Historic Process Instance - name: Historic Task Instance - name: Historic User Operation Log - name: Historic Variable Instance - name: History Cleanup - name: Identity - name: Incident - name: Job - name: Job Definition - name: Message - name: Metrics - name: Migration - name: Modification - name: Process Definition - name: Process Instance - name: Signal - name: Schema Log - name: Task - name: Task Attachment - name: Task Comment - name: Task Identity Link - name: Task Local Variable - name: Task Variable - name: Telemetry - name: Tenant - name: User - name: Variable Instance - name: Version externalDocs: description: Find out more about ORION Rest API url: https://docs.eorion.com paths: /external-task/fetchAndLock: post: tags: - External Task summary: Fetch and Lock description: >- Fetches and locks a specific number of external tasks for execution by a worker. Query can be restricted to specific task topics and for each task topic an individual lock time can be provided. operationId: fetchAndLock requestBody: content: application/json: schema: $ref: '#/components/schemas/FetchExternalTasksDto' examples: example-1: summary: POST /external-task/fetchAndLock (1) description: Request with variable filtering value: workerId: aWorkerId maxTasks: 2 usePriority: true topics: - topicName: createOrder lockDuration: 10000 variables: - orderId example-2: summary: POST /external-task/fetchAndLock (2) description: Request with all variables included value: workerId: aWorkerId maxTasks: 2 usePriority: true topics: - topicName: createOrder lockDuration: 10000 processDefinitionId: aProcessDefinitionId tenantIdIn: tenantOne example-3: summary: POST /external-task/fetchAndLock (3) description: Request with includeExtensionProperties value: workerId: aWorkerId maxTasks: 1 usePriority: true topics: - topicName: createOrder lockDuration: 10000 includeExtensionProperties: true example-4: summary: POST /external-task/fetchAndLock (4) description: Request with order by priority & createTime value: workerId: aWorkerId maxTasks: 2 usePriority: true sorting: - sortBy: createTime sortOrder: asc responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/LockedExternalTaskDto' examples: example-1: summary: POST /external-task/fetchAndLock (1) description: Request with variable filtering value: - activityId: anActivityId activityInstanceId: anActivityInstanceId errorMessage: anErrorMessage errorDetails: anErrorDetails executionId: anExecutionId id: anExternalTaskId lockExpirationTime: 2015-10-06T16:34:42.000+0200 createTime: 2015-10-06T16:34:42.000+0200 processDefinitionId: aProcessDefinitionId processDefinitionKey: aProcessDefinitionKey processInstanceId: aProcessInstanceId tenantId: null retries: 3 workerId: aWorkerId priority: 4 topicName: createOrder variables: orderId: type: String value: '1234' valueInfo: {} - activityId: anActivityId activityInstanceId: anActivityInstanceId errorMessage: anErrorMessage errorDetails: anotherErrorDetails executionId: anExecutionId id: anExternalTaskId lockExpirationTime: 2015-10-06T16:34:42.000+0200 createTime: 2015-10-06T16:34:42.000+0200 processDefinitionId: aProcessDefinitionId processDefinitionKey: aProcessDefinitionKey processInstanceId: aProcessInstanceId tenantId: null retries: 3 workerId: aWorkerId priority: 0 topicName: createOrder variables: orderId: type: String value: '3456' valueInfo: {} example-2: summary: POST /external-task/fetchAndLock (2) description: Request with all variables included value: - activityId: anActivityId activityInstanceId: anActivityInstanceId errorMessage: anErrorMessage errorDetails: anErrorDetails executionId: anExecutionId id: anExternalTaskId lockExpirationTime: 2015-10-06T16:34:42.00+0200 createTime: 2015-10-06T16:34:42.000+0200 processDefinitionId: aProcessDefinitionId processDefinitionKey: aProcessDefinitionKey processInstanceId: aProcessInstanceId tenantId: tenantOne retries: 3 workerId: aWorkerId priority: 4 topicName: createOrder businessKey: aBusinessKey variables: orderId: type: String value: '1234' valueInfo: {} - activityId: anActivityId activityInstanceId: anActivityInstanceId errorMessage: anErrorMessage errorDetails: anotherErrorDetails executionId: anExecutionId id: anExternalTaskId lockExpirationTime: 2015-10-06T16:34:42.000+0200 createTime: 2015-10-06T16:34:42.000+0200 processDefinitionId: aProcessDefinitionId processDefinitionKey: aProcessDefinitionKey processInstanceId: aProcessInstanceId tenantId: null retries: 3 workerId: aWorkerId priority: 0 topicName: createOrder businessKey: aBusinessKey variables: orderId: type: String value: '3456' valueInfo: {} example-3: summary: POST /external-task/fetchAndLock (3) description: Request with includeExtensionProperties value: - activityId: anActivityId activityInstanceId: anActivityInstanceId errorMessage: anErrorMessage errorDetails: anErrorDetails executionId: anExecutionId id: anExternalTaskId lockExpirationTime: 2015-10-06T16:34:42.000+0200 createTime: 2015-10-06T16:34:42.000+0200 processDefinitionId: aProcessDefinitionId processDefinitionKey: aProcessDefinitionKey processInstanceId: aProcessInstanceId retries: null suspended: false workerId: aWorkerId topicName: createOrder tenantId: null variables: {} priority: 0 businessKey: default extensionProperties: property2: value2 property1: value1 description: Request successful. '400': content: application/json: schema: $ref: '#/components/schemas/ExceptionDto' description: >- Bad Request. See the [Introduction](https://docs.camunda.org/manual/7.22/reference/rest/overview/#error-handling) for the error response format. components: schemas: FetchExternalTasksDto: type: object required: - workerId - maxTasks properties: workerId: type: string description: >- **Mandatory.** The id of the worker on which behalf tasks are fetched. The returned tasks are locked for that worker and can only be completed when providing the same worker id. maxTasks: type: integer format: int32 nullable: true description: '**Mandatory.** The maximum number of tasks to return.' usePriority: type: boolean nullable: true description: >- A `boolean` value, which indicates whether the task should be fetched based on its priority or arbitrarily. asyncResponseTimeout: type: integer format: int64 nullable: true description: >- The [Long Polling](https://docs.camunda.org/manual/7.22/user-guide/process-engine/external-tasks/#long-polling-to-fetch-and-lock-external-tasks) timeout in milliseconds. **Note:** The value cannot be set larger than 1.800.000 milliseconds (corresponds to 30 minutes). topics: type: array nullable: true items: $ref: '#/components/schemas/FetchExternalTaskTopicDto' description: >- A JSON array of topic objects for which external tasks should be fetched. The returned tasks may be arbitrarily distributed among these topics. Each topic object has the following properties: sorting: type: array nullable: true description: Apply sorting of the result items: type: object properties: sortBy: type: string nullable: true enum: - createTime description: |- Sort the results lexicographically by a given criterion. Must be used in conjunction with the sortOrder parameter. sortOrder: type: string nullable: true enum: - asc - desc description: >- Sort the results in a given order. Values may be `asc` for ascending order or `desc` for descending order. Must be used in conjunction with the sortBy parameter. LockedExternalTaskDto: title: LockedExternalTaskDto type: object properties: activityId: type: string nullable: true description: The id of the activity that this external task belongs to. activityInstanceId: type: string nullable: true description: The id of the activity instance that the external task belongs to. errorMessage: type: string nullable: true description: >- The full error message submitted with the latest reported failure executing this task;`null` if no failure was reported previously or if no error message was submitted errorDetails: type: string nullable: true description: >- The error details submitted with the latest reported failure executing this task.`null` if no failure was reported previously or if no error details was submitted executionId: type: string nullable: true description: The id of the execution that the external task belongs to. id: type: string nullable: true description: The id of the external task. lockExpirationTime: type: string format: date-time nullable: true description: The date that the task's most recent lock expires or has expired. processDefinitionId: type: string nullable: true description: The id of the process definition the external task is defined in. processDefinitionKey: type: string nullable: true description: The key of the process definition the external task is defined in. processDefinitionVersionTag: type: string nullable: true description: >- The version tag of the process definition the external task is defined in. processInstanceId: type: string nullable: true description: The id of the process instance the external task belongs to. tenantId: type: string nullable: true description: The id of the tenant the external task belongs to. retries: type: integer format: int32 nullable: true description: The number of retries the task currently has left. suspended: type: boolean nullable: true description: >- Whether the process instance the external task belongs to is suspended. workerId: type: string nullable: true description: The id of the worker that posesses or posessed the most recent lock. priority: type: integer format: int64 nullable: true description: The priority of the external task. topicName: type: string nullable: true description: The topic name of the external task. businessKey: type: string nullable: true description: >- The business key of the process instance the external task belongs to. variables: type: object nullable: true additionalProperties: $ref: '#/components/schemas/VariableValueDto' description: >- A JSON object containing a property for each of the requested variables. The key is the variable name, the value is a JSON object of serialized variable values with the following properties: ExceptionDto: title: ExceptionDto type: object properties: type: type: string nullable: true description: An exception class indicating the occurred error. message: type: string nullable: true description: A detailed message of the error. code: type: number description: >- The code allows your client application to identify the error in an automated fashion. You can look up the meaning of all built-in codes and learn how to add custom codes in the [User Guide](https://docs.camunda.org/manual/7.22/user-guide/process-engine/error-handling/#exception-codes). FetchExternalTaskTopicDto: type: object required: - topicName - lockDuration properties: topicName: type: string description: '**Mandatory.** The topic''s name.' lockDuration: type: integer format: int64 nullable: true description: >- **Mandatory.** The duration to lock the external tasks for in milliseconds. variables: type: array nullable: true items: type: string description: >- A JSON array of `String` values that represent variable names. For each result task belonging to this topic, the given variables are returned as well if they are accessible from the external task's execution. If not provided - all variables will be fetched. localVariables: type: boolean nullable: true default: false description: If `true` only local variables will be fetched. businessKey: type: string nullable: true description: >- A `String` value which enables the filtering of tasks based on process instance business key. processDefinitionId: type: string nullable: true description: Filter tasks based on process definition id. processDefinitionIdIn: type: array nullable: true items: type: string description: Filter tasks based on process definition ids. processDefinitionKey: type: string nullable: true description: Filter tasks based on process definition key. processDefinitionKeyIn: type: array nullable: true items: type: string description: Filter tasks based on process definition keys. processDefinitionVersionTag: type: string nullable: true description: Filter tasks based on process definition version tag. withoutTenantId: type: boolean nullable: true default: false description: Filter tasks without tenant id. tenantIdIn: type: array nullable: true items: type: string description: Filter tasks based on tenant ids. processVariables: type: object additionalProperties: true description: >- A `JSON` object used for filtering tasks based on process instance variable values. A property name of the object represents a process variable name, while the property value represents the process variable value to filter tasks by. deserializeValues: type: boolean nullable: true default: false description: >- Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `false`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using [Jackson's](https://github.com/FasterXML/jackson) POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML. includeExtensionProperties: type: boolean nullable: true default: false description: >- Determines whether custom extension properties defined in the BPMN activity of the external task (e.g. via the Extensions tab in the Camunda modeler) should be included in the response. Default: false VariableValueDto: type: object properties: value: $ref: '#/components/schemas/AnyValue' type: type: string nullable: true description: The value type of the variable. valueInfo: type: object additionalProperties: true description: >- A JSON object containing additional, value-type-dependent properties. For serialized variables of type Object, the following properties can be provided: * `objectTypeName`: A string representation of the object's type name. * `serializationDataFormat`: The serialization format used to store the variable. For serialized variables of type File, the following properties can be provided: * `filename`: The name of the file. This is not the variable name but the name that will be used when downloading the file again. * `mimetype`: The MIME type of the file that is being uploaded. * `encoding`: The encoding of the file that is being uploaded. The following property can be provided for all value types: * `transient`: Indicates whether the variable should be transient or not. See [documentation](https://docs.camunda.org/manual/7.22/user-guide/process-engine/variables#transient-variables) for more informations. (Not applicable for `decision-definition`, ` /process-instance/variables-async`, and `/migration/executeAsync` endpoints) AnyValue: description: |- Can be any value - string, number, boolean, array or object. **Note**: Not every endpoint supports every type. securitySchemes: basicAuth: type: http scheme: basic ````