Skip to main content

工作流端点

Workflow Endpoints and Parameters

要详细了解对象关系以及如何在 API 中使用对象关系,请转至 对象关系 部分。

如需详细了解工作流,请访问 工作流 帮助页面。

上传新工作流

要上传新工作流,请使用 POST {baseURL}/v3/workflows 端点。

参数

  • file (file):必填。选择您想上传到系统的实际文件。媒体类型必须是 YXZP 文件。

  • name (string):必填。输入工作流名称。这是要在 Server UI 中显示的工作流名称。

  • ownerId (string):必填。输入所有者 ID。

  • workerTag (string):可选。指定在工作程序中定义的工作程序标签,以帮助将作业分配给某些工作程序节点。如需了解详情,请访问 工作程序 帮助页面。

  • districtTags (string):可选。以 JSON 格式的数组进行提交,例如,["id1", "id2"]。使用分区功能,按照标记对共享的公共工作流进行分组,以便用户可以轻松找到。如需了解详情,请访问 分区 帮助页面。

  • comments (string):可选。输入注释。

  • isPublic (boolean):必填。选择“true”将工作流设为公开可用。选择“false”将工作流设为私有,不允许公开使用。

  • isReadyForMigration (boolean):必填。选择工作流是否已准备好进行迁移。如需详细了解如何从一个 Server 环境迁移到另一个 Server 环境,请参阅 启用工作流迁移 帮助页面。

  • sourceAppId (string):可选。设置工作流的源应用程序 ID。您可以将其用作 POST admin/v1/workflows  端点的“sourceId”。提供预先存在的 sourceAppId 将导致请求无效。

  • othersMayDownload (boolean):必填。指定其他用户是否可以下载此工作流。

  • othersCanExecute (boolean):必填。指定其他用户是否可以执行此工作流。

  • executionMode (string):必填。接受的值为“Safe”(安全)、“SemiSafe”(半安全)和“Standard”(标准)。如需详细了解执行模式,请参阅 安全和半安全运行模式:阻止的工具、事件和数据连接器 帮助页面。

  • hasPrivateDataExemption (boolean):可选。给予豁免以允许运行包含私有数据的工作流。选择“true”,以允许豁免;或选择“false”,以拒绝豁免。如需了解详情,请访问 管理员界面中的工作流选项 页面。

  • workflowCredentialType (string):必填。接受的值为“Default”、“Required”和“Specific”。

  • credentialId (string):可选。为此工作流指定 credentialId

  • collectionIds (string):可选。输入应将此工作流添加到的集合的 collectionId 。以 JSON 格式的数组进行提交,例如:["id1", "id2"]。

curl -X 'POST' \
  'http://localhost/webapi/v3/workflows' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Workflow2.yxzp;type=application/yxzp' \
  -F 'name=Workflow2' \
  -F 'ownerId=66ebd0896e52ae73b4951072' \
  -F 'isPublic=true' \
  -F 'isReadyForMigration=true' \
  -F 'othersMayDownload=true' \
  -F 'othersCanExecute=false' \
  -F 'executionMode=Standard' \
  -F 'workflowCredentialType=Default'
  • 200: OK

    "string"
  • 400: BadRequest

  • 401: Unauthorized

将新版本上传到现有工作流

要将新版本上传到现有工作流,请使用 POST {baseURL}/v3/workflows/{workflowId}/versions 端点。

参数

  • workflowId (string):必填。输入要为其上传新版本的工作流 ID。

  • file (file):必填。选择您想作为新版本上传到系统的实际文件。媒体类型必须是 YXZP 文件。

  • name (string):必填。输入工作流名称。这是要在 Server UI 中显示的工作流名称。

  • ownerId (string):必填。输入所有者 ID。

  • othersMayDownload (boolean):必填。默认值设置为“true”。

  • othersCanExecute (boolean):必填。默认值设置为“true”。

  • executionMode (string):必填。接受的值为“Safe”(安全)、“SemiSafe”(半安全)和“Standard”(biao'zhun)。如需详细了解执行模式,请参阅 安全和半安全运行模式:阻止的工具、事件和数据连接器 帮助页面。

  • hasPrivateDataExemption (boolean):可选。给予豁免以允许运行包含私有数据的工作流。选择“true”,以允许豁免;或选择“false”,以拒绝豁免。如需了解详情,请访问 管理员界面中的工作流选项 页面。

  • comments (string):可选。输入注释。

  • makePublished (boolean):必填。默认值设置为“true”。makePublished 参数是一种控制推送到 Server 的工作流的新版本是否应为发布版本的方法。当您将工作流推送到 Server 时,可以将其设置为“false”,这样只有您才能运行它。

  • workflowCredentialType (string):必填。输入用于此工作流的凭证类型。接受的值为“Default”、“Required”和“Specific”。

  • credentialId (string):可选。为此工作流指定 credentialId。如需详细了解凭证端点,请参阅 凭证端点

curl -X 'POST' \
  'http://localhost/webapi/v3/workflows/66ebd18d6e52ae73b4951085/versions' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Workflow3.yxzp;type=application/yxzp' \
  -F 'name=Workflow1_3' \
  -F 'ownerId=66ebd0896e52ae73b4951072' \
  -F 'othersMayDownload=true' \
  -F 'othersCanExecute=true' \
  -F 'executionMode=Standard' \
  -F 'makePublished=true' \
  -F 'workflowCredentialType=Default'
  • 200: OK

    {
      "id": "string",
      "sourceAppId": "string",
      "dateCreated": "2024-09-19T07:33:01.072Z",
      "runCount": 0,
      "versions": [
        {
          "versionId": "string",
          "versionNumber": 0,
          "dateCreated": "2024-09-19T07:33:01.072Z",
          "uploadSource": "Designer",
          "uploadDate": "2024-09-19T07:33:01.072Z",
          "packageWorkflowType": "App",
          "published": true,
          "comments": "string",
          "runDisabled": true,
          "executionMode": "Safe",
          "workflowCredentialType": "Default",
          "credentialId": "string",
          "hasPrivateDataExemption": true,
          "othersMayDownload": true,
          "othersCanViewHistory": true,
          "details": {
            "isAmp": true,
            "fileName": "string",
            "author": "string",
            "copyright": "string",
            "description": "string",
            "name": "string",
            "noOutputFilesMessage": "string",
            "outputMessage": "string",
            "url": "string",
            "urlText": "string"
          }
        }
      ],
      "name": "string",
      "ownerId": "string",
      "workerTag": "string",
      "districtTags": [
        "string"
      ],
      "comments": "string",
      "isPublic": true,
      "isReadyForMigration": true,
      "publishedVersionId": "string",
      "othersMayDownload": true,
      "othersCanViewHistory": true,
      "othersCanExecute": true,
      "executionMode": "Safe",
      "hasPrivateDataExemption": true
    }
  • 401: BadRequest

  • 401: Unauthorized

  • 404: Indicates that the workflowId in the path is invalid.

检索所有工作流

要获取有关所有工作流记录的信息,请使用 GET {baseURL}/v3/workflows/ 端点。

参数

  • view (string):可选。选择显示工作流信息的方式。可以保留此参数但不为其提供值。您可以从以下值中选择:“默认值(Default)”和“全部(Full)”。如果此参数设置为“Default”,则将返回一个减小的视图对象。未指定时,将使用“默认值(Default)”。

  • name (string):可选。输入工作流名称,以便按名称筛选工作流。这是在 Server UI 中显示的工作流名称。

  • ownerId (string):可选。输入所有者 ID,以便按其所有者筛选工作流。

  • createdAfter (string):可选。输入日期和时间,工作流是在此之后创建的。以 ISO8601 格式 输入日期和时间。

  • createdBefore (string):可选。输入日期时间,工作流是在此之前创建的。以 ISO8601 格式 输入日期和时间。

curl -X 'GET' \
  'http://localhost/webapi/v3/workflows' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'
  • 200: OK

      {
        "id": "string",
        "sourceAppId": "string",
        "name": "string",
        "ownerId": "string",
        "dateCreated": "2024-08-15T11:14:56.965Z",
        "publishedVersionNumber": 0,
        "isAmp": true,
        "executionMode": "Safe"
      }
    ]
  • 400: BadRequest

  • 401: Unauthorized

检索特定工作流记录

要获取有关特定工作流的信息,请使用 GET {baseURL}/v3/workflows/{workflowId} 端点。

注意

Non-Curators can use the GET v3/workflows/{workflowId} endpoint for workflows they have access to. Previously, this endpoint was limited to Curators only.

参数

  • workflowId (string):必填。输入工作流 ID,以获取有关此工作流的信息。

curl -X 'GET' \
  'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'
  • 200: OK

    {
      "id": "string",
      "sourceAppId": "string",
      "dateCreated": "2024-09-05T10:42:53.360Z",
      "runCount": 0,
      "versions": [
        {
          "versionId": "string",
          "versionNumber": 0,
          "dateCreated": "2024-09-05T10:42:53.360Z",
          "uploadSource": "Designer",
          "uploadDate": "2024-09-05T10:42:53.360Z",
          "packageWorkflowType": "App",
          "published": true,
          "comments": "string",
          "runDisabled": true,
          "executionMode": "Safe",
          "workflowCredentialType": "Default",
          "credentialId": "string",
          "hasPrivateDataExemption": true,
          "othersMayDownload": true,
          "othersCanViewHistory": true,
          "details": {
            "isAmp": true,
            "fileName": "string",
            "author": "string",
            "copyright": "string",
            "description": "string",
            "name": "string",
            "noOutputFilesMessage": "string",
            "outputMessage": "string",
            "url": "string",
            "urlText": "string"
          }
        }
      ],
      "name": "string",
      "ownerId": "string",
      "workerTag": "string",
      "districtTags": [
        "string"
      ],
      "comments": "string",
      "isPublic": true,
      "isReadyForMigration": true,
      "publishedVersionId": "string",
      "othersMayDownload": true,
      "othersCanViewHistory": true,
      "othersCanExecute": true,
      "executionMode": "Safe",
      "hasPrivateDataExemption": true
    }
  • 401: Unauthorized

  • 404: NotFound

更新现有工作流

要更改有关现有工作流的信息,请使用  PUT{baseURL}/v3/workflows/{workflowId} 端点。

注意

Only Curators can use this API endpoint.

要更改 ownerId,新所有者与当前所有者必须在同一订阅中。

参数

  • workflowId (string):必填。输入要更新的工作流 ID。

  • updateWorkflowContract (body):必填。输入要更新的工作流信息。

    • name (string): Required. Enter the workflow name. This is the name of the workflow to display in Server UI.

    • versionId (string): Required. Enter the version ID.

    • makePublished (boolean): Optional. When not specified, the value stays the same as before. The makePublished parameter is a way to control whether the new version of a workflow that you push to Server should be the published version or not. You can set the value to "false" when you push the workflow to Server, and then only you will have the ability to run it.

    • ownerId (string): Required. Enter the owner ID.

    • workerTag (string): Required. When there is no workerTag, use "" instead.

    • districtTags (string): Required. Enter the district tags. Use districts to group shared, public workflows by tags so that users can easily find them. For more information, visit the Districts help page.

    • comments (string): Required. Enter your comments.

    • isPublic (boolean): Optional. When not specified, the value stays the same as before.

    • isReadyForMigration (boolean): Optional. When not specified, the value stays the same as before.

    • othersMayDownload (boolean): Optional. When not specified, the value stays the same as before. When set to "false" for a public workflow, the workflow will be unusable.

    • othersCanExecute (boolean): Optional. When not specified, the value stays the same as before. When set to "false" for a public workflow, the workflow will be unusable.

    • executionMode (string): Optional. Accepted values are "Safe", "SemiSafe", "Standard". For more information about the execution mode, see the Safe and Semi-safe Run Modes: Blocked Tools, Events, and Data Connectors help page.

    • hasPrivateDataExemption (boolean): Optional. Give an exemption to allow a workflow with private data to run. Select "true" to allow an exemption or "false" to deny an exemption. When not specified, the value stays the same as before. For more information, visit the Workflow Options in Admin page.

    • workflowCredentialType (string): Optional. Accepted values are "Default", "Required", and "Specific".

    • credentialId (string): Optinal. Specify the credentialId for this workflow.

  • Example value of updateWorkflowContract:

    {
      "name": "string",
      "versionId": "string",
      "makePublished": true,
      "ownerId": "string",
      "workerTag": "string",
      "districtTags": [
        "string"
      ],
      "comments": "string",
      "isPublic": true,
      "isReadyForMigration": true,
      "othersMayDownload": true,
      "othersCanExecute": true,
      "executionMode": "Safe",
      "hasPrivateDataExemption": true,
      "workflowCredentialType": "Default",
      "credentialId": "string"
    }
curl -X 'PUT' \
  'http://localhost/webapi/v3/workflows/66ebd18d6e52ae73b4951085' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Workflow_3_4",
  "versionId": "66ebd18d3d6200007e000d89",
  "makePublished": true,
  "ownerId": "66ebd0896e52ae73b4951072",
  "workerTag": "",
  "districtTags": [],
  "comments": "nothing",
  "isPublic": true,
  "isReadyForMigration": true,
  "othersMayDownload": true,
  "othersCanExecute": true,
  "executionMode": "Safe",
  "hasPrivateDataExemption": true,
  "workflowCredentialType": "Default",
  "credentialId": ""
}'
  • 200: OK

    {
      "id": "string",
      "sourceAppId": "string",
      "dateCreated": "2024-08-15T11:20:45.231Z",
      "runCount": 0,
      "versions": [
        {
          "versionId": "string",
          "versionNumber": 0,
          "dateCreated": "2024-08-15T11:20:45.231Z",
          "uploadSource": "Designer",
          "uploadDate": "2024-08-15T11:20:45.231Z",
          "packageWorkflowType": "App",
          "published": true,
          "comments": "string",
          "runDisabled": true,
          "executionMode": "Safe",
          "workflowCredentialType": "Default",
          "credentialId": "string",
          "hasPrivateDataExemption": true,
          "othersMayDownload": true,
          "othersCanViewHistory": true,
          "details": {
            "isAmp": true,
            "fileName": "string",
            "author": "string",
            "copyright": "string",
            "description": "string",
            "name": "string",
            "noOutputFilesMessage": "string",
            "outputMessage": "string",
            "url": "string",
            "urlText": "string"
          }
        }
      ],
      "name": "string",
      "ownerId": "string",
      "workerTag": "string",
      "districtTags": [
        "string"
      ],
      "comments": "string",
      "isPublic": true,
      "isReadyForMigration": true,
      "publishedVersionId": "string",
      "othersMayDownload": true,
      "othersCanViewHistory": true,
      "othersCanExecute": true,
      "executionMode": "Safe",
      "hasPrivateDataExemption": true
    }
  • 400: BadRequest

  • 401: Unauthorized

  • 404: NotFound

下载工作流包

要下载工作流包,请使用 GET {baseURL}/v3/workflows/{workflowId}/package 端点。

参数

  • workflowId (string):必填。输入要为其下载包的工作流 ID。

  • versionId (string):可选。输入工作流的版本 ID。如果未提供版本,则下载发布版本。

    注意

    如果 versionID 是两位数,则可能会达到大小限制,并且您可能会收到“414 - URI 太长”的错误。在这种情况下,请解析 JSON versionID 字符串并对其进行剪裁,以仅显示最新版本。这样可以控制字段长度。

请求示例:cURL

curl -X GET --header 'Accept: application/octet-stream' --header 'Authorization: Bearer BearerTokenGoesHere' 'http://localhost/webapi/v3/workflows/635a4be7dc6e24bb8ff0/package'

Response Example

  • 200: The download stream of the YXZP file.

  • 400: Invalid VersionId

  • 401: Unauthorized

  • 403: The authenticated user does not have permission to download the workflow, or the workflow is not allowed to be downloaded directly.

  • 404: NotFound

检索工作流的问题信息

要获取工作流的问题信息,请使用 GET {baseURL}/v3/workflows/{workflowId}/questions 端点。

参数

  • workflowId (string):必填。输入要为其检索信息的的工作流 ID。

  • versionId (string):可选。输入工作流的版本 ID。如果未提供版本,则使用发布版本。

curl -X 'GET' \
  'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/questions' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'
  • 200: OK

    [
      {
        "name": "string",
        "questionType": "string",
        "description": "string",
        "value": "string",
        "multiple": true,
        "items": [
          {
            "key": "string",
            "value": "string"
          }
        ]
      }
    ]
  • 400: BadRequest

  • 401: Unauthorized

  • 403: The authenticated user does not have access to the workflow or questions.

  • 404: NotFound

获取有关特定工作流作业的信息

要获取有关特定工作流作业的信息,请使用 GET {baseURL}/v3/workflows/{workflowId}/jobs 端点。

注意

A job might be returned as Completed even if the query status is Error. This indicates an error occurred during execution, but the workflow was run.

参数

  • workflowId (string):必填。输入要为其检索信息的的工作流 ID。

  • sortField (string):可选。

  • direction (string):可选。

  • offset (string):可选。

  • limit (string):可选。

  • status (string): Optional. The overall status of the job execution. A completed job might still have failed. Accepted values are: "Complete", "Error", "Running", and "Queued".

  • resultCode (string): Optional. The result code of the execution of a workflow. This indicates a failed workflow, but a successful job. Accepted values are: "Success", "Warning", and "Error".

curl -X 'GET' \
  'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/jobs' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'
  • 200: OK

    [
      {
        "id": "string",
        "createDate": "2024-08-15T11:29:53.357Z",
        "status": "Created",
        "priority": "string",
        "workerTag": "string",
        "runWithE2": true
      }
    ]
  • 400: BadRequest

  • 401: Unauthorized

  • 404: NotFound

删除工作流

要删除特定工作流,请使用 DELETE {baseURL}/v3/workflows/{workflowId} 端点。

注意

Only Curators can use this API endpoint.

参数

  • workflowId (string):必填。输入要删除的工作流 ID。

  • force (boolean):可选。未选择时,默认值为“false”。如果已计划工作流,将参数设置为“true”会在删除工作流之前删除所有计划。

curl -X 'DELETE' \
  'http://localhost/webapi/v3/workflows/670ce95bf10214f22a665bc4' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'
  • 200: OK

  • 400: BadRequest

  • 401: Unauthorized

  • 404: NotFound

创建新作业

要创建新作业并将其添加到队列中,请使用 POST /v3/workflows/{workflowId}/jobs 端点。

参数

  • workflowId (string):必填。输入要计划的工作流 ID。

  • contract (body):要创建新作业,请指定以下参数:

    • workerTag (string):可选。指定分配的工作程序。如果未指定,值将为“无”。

    • credentialId (string):可选。为此工作流指定 credentialId。

    • questions (string):可选。对于分析应用程序,请指定运行工作流所用的问题和答案。

      • name (string): Optional.

      • value (string): Optional.

    • priority (string):可选。指定运行计划的优先级。从以下选项中选择:“低”、“中”、“高”和“紧急”。如果未指定,默认值将为“低”。

Example value of contract:

{
  "workerTag": "string",
  "credentialId": "string",
  "questions": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "priority": "Default"
}

Example of a request to create a job:

curl -X 'POST' \
  'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/jobs' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere' \
  -H 'Content-Type: application/json' \
  -d '{
  "workerTag": "",
  "credentialId": "",
  "priority": "Low"
}'
  • 200: OK

    {
      "id": "string",
      "appId": "string",
      "createDateTime": "2024-09-05T11:13:04.586Z",
      "status": "string",
      "disposition": "string",
      "outputs": [
        {
          "id": "string",
          "availableFormats": [
            "string"
          ],
          "fileName": "string"
        }
      ],
      "messages": [
        {
          "status": 0,
          "text": "string",
          "toolId": 0
        }
      ],
      "priority": "Default",
      "workerTag": "string",
      "runWithE2": true
    }
  • 400: BadRequest

  • 401: Unauthorized

  • 403: The authenticated user does not have access to execute the workflow.

  • 404: NotFound

Transfer Workflows and Schedules to a Specified Owner

To transfer a specific workflow to a specific owner, together with schedules if desired, use the PUT {baseURL}/v3/workflows/{workflowId}/transfer endpoint.

注意

  • Only Curators can use this API endpoint.

  • If any of the workflows require DCM connections, Server connections, or specific run as credentials to run, these items need to be updated before the workflow can run.

  • If users are not in the same studio and when a workflow is transferred to the new studio, all other users in the new owner's studio will also receive access to the workflow, and all users from the old studio will lose access.

  • Workflows can only be transferred to a user with the Artisan or Curator role.

  • If transferring schedules, the new owner must have access to the scheduled workflow, otherwise you won’t be able to transfer that workflow to the new owner.

  • If transferring schedules, the new owner must have permission to schedule workflows.

  • If the user is deleted, it returns a list of schedule Ids that will be broken or disabled after transfer.

Parameters

  • workflowId (string): Required. Specify the Id of the workflow to transfer.

  • contract (body): Required. Specify the following information:

    • ownerId (string): Required. Specify the Id of the new owner.

    • transferSchedules (Boolean): Required. Specify whether the schedules should be transferred to a new owner together with the workflow. Only the schedules owned by the current workflow owner will be transferred to the new owner.

Example value of contract:

{
  "ownerId": "string",
  "transferSchedules": true
}
curl -X 'PUT' \
  'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/transfer' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere' \
  -H 'Content-Type: application/json' \
  -d '{
  "ownerId": "670ceafbf10214f22a666c76",
  "transferSchedules": true
}'
  • 200: OK

  • 400: BadRequest

    "string"
  • 401: Unauthorized

  • 403: Forbidden

    "string"
  • 404: NotFound

    "string"
  • 500: InternalServerError

对象关系

如果您要上传工作流,则可以按如下方式使用创建的对象:

创建的对象:“ workflowId ”(例如“id”: “7917969784f84bd09442f66996ecb8f3”)

您可以将其用作:

Postman 请求示例

GET /v3/workflows/{workflowId}

Use GET /v3/workflows/{workflowId} endpoint.

如需详细了解有关 Postman 请求的更多信息,请访问 如何使用 Postman 帮助页面。