Engage 使用 API

Engage 使用 API 向 . 发送数据或从 Engage.

注意

Engage 使用OData版本4。

关于本主题

端点
读取控制面板数据
创建文件
创建想法
获取作业状态

端点

API Engage 目前支持以下终端节点。

操作	说明
`Read Dashboard Data`	从仪表板报表和所有工作流构思中包含的所有项目获取全局数据值。
`Create File`	创建新的项目概念或非工作流项目。注意推荐于 `Create Idea`。
`Create File`	创建新的项目构思。注意要获得扩展功能，请使用 `Create File`。
`Get Job Stats`	获取指定后台作业的状态信息。

读取控制面板数据

该 Read Dashboard Data 作将检索仪表板报表和所有工作流构想中包含的所有项目的全局项目数据。此终端节点使用 OData 标准查询数据。

不支持以下 OData 功能：

$filter
$apply
$orderby
$select
$expand
$count
$skip
$top

请求

Read Dashboard Data 该请求的构造方式如下。替换为 subscription-id 订阅的 ID。

方法	请求 URL
`GET`	`https://engage.minitab.com/api/v1/subscription-id/export/odata`

请求标头

Header	说明
`Authorization`	必填。通过 `Bearer` 授权方案提供 API 令牌。

示例请求

Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/export/odata HTTP/1.1 Headers: Authorization: Bearer token

响应

响应包括一个 HTTP 状态代码、一组响应标头和一个正文。

状态代码

成功的请求将返回状态代码 200 （OK）。

响应标头

此作的响应包括以下标头。响应还可能包括其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 protocol specification.

Header	说明
`Content-Type`	指示响应正文的媒体类型。

响应正文

响应正文包含格式为请求的数据 JSON ，根据 OData 标准进行结构化。下面是响应的示例：

{ "value": [ { "ProjectId": "12345", "ProjectName": "Project A", "Status": "Active", "StartDate": "2025-01-01", "EndDate": "2025-12-31" }, { "ProjectId": "67890", "ProjectName": "Project B", "Status": "Completed", "StartDate": "2024-01-01", "EndDate": "2024-12-31" } ] }

示例响应

Response Status: HTTP/1.1 200 OK Response headers: Content-Type: application/json Response Body: { "value": [ { "ProjectId": "12345", "ProjectName": "Project A", "Status": "Active", "StartDate": "2025-01-01", "EndDate": "2025-12-31" }, { "ProjectId": "67890", "ProjectName": "Project B", "Status": "Completed", "StartDate": "2024-01-01", "EndDate": "2024-12-31" } ] }

创建文件

Create File 作将启动一个作业，以在订阅中创建新项目概念或非工作流项目。

请求

您可以构建 Create File 请求，如下所示。将 subscription-id 替换为您的订阅 ID。

方法	请求 URL
`POST`	`https://engage.minitab.com/api/v2/subscription-id/Item`

请求标头

Header	说明
`Authorization`	必填。通过 `Bearer` 授权方案提供 API 令牌。需要令牌才能具有 `Create Idea` 权限。
`Content-Type`	必填。`application/json`必须是。

请求正文

请求正文由一个 JSON 对象组成，该对象具有三个必需的属性：FileName、ProjectTemplateName 和 CreateFileType。

{ “文件名”：{ “文件名”：“name of idea” “ProjectTemplateName”：“用于项目的项目模板的名称”，#Only 非工作流项目是必需的。该名称必须与订阅中的项目模板匹配。“CreateFileType”：0， #（0 个想法， 1 个非工作流项目） }

您可以包括以下任何选项。

OwnerEmail：将拥有此新文件的用户的电子邮件地址。
IncludeInDashboard中：true 或 false 值，用于覆盖订阅设置中的默认值。
Data：用于在文件中设置数据字段值的对象。Data 由映射到字段代号和值的对象的单值类别代号组成。
TableData中：用于在文件中设置表数据值的对象。TableData 由映射到字段代号和值集对象的数据表类别代号组成。
- 对于想法，表数据必须位于想法表单上。
- 在表数据中，当字段的值数不相等时，值较少的字段将在其余行中设置为其默认值。
- 使用 null 获取空白值。
- 某些数据表具有必填字段，例如 [teammember / name]。当必填字段为空时，不会创建项目。
NotificationRecipients：用于在 Create File 作成功或失败时接收消息的电子邮件地址。

{ “文件名”：“想法名称”、“项目模板名称”：“Just Do It”， “CreateFileType”：1， “OwnerEmail”： user@company.com“， ”IncludeInDashboard“： false， ”NotificationRecipients“：[“fmae@mortgage.gov”， “user@domain.com”]， “数据”：{ “项目摘要”：{ “belt_level”：“绿带”、“critical_to”：“长文本\r\nwith\r\n换行符” }， “annualized_financial”：{ “annualized_actual_hard_savings”：100 } } “TableData”：{ “teammember”：{ “name”：[“John Q. Public”，“房利美”，“房地美”]， “role”：[“项目负责人”，null，“抵押贷款经纪人”]， “email”：[null，“fmae@mortgage.gov”] }， “task”：{ “subject”：[“再融资”，“origination”] “startdate”：[“2025-04-24”] } } }

注意

要查看可用于共享的有效数据字段和类别名称的列表，数据架构师可以从设置Engageweb app.

注意

要将团队成员的姓名设置为团队角色（发起人、 支持者、 财务分析师等），请将 Team Member / Role 字段连接到 Role 字段。在前面的示例中， Team Role / Project Leader 将设置为“John Q. Public”。

注意

Create File 作不支持为所有字段设置数据值。尝试为公式、富文本或内部字段提供数据将导致错误。

样品请求

Request: POST https://engage.minitab.com/api/v2/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1 Headers: Authorization: Bearer token Content-Type: application/json Content-Length: 785 Body: { "FileName": "file name", "ProjectTemplateName":"DMAIC Project", "CreateFileType": 1, "OwnerEmail":"user@yourcompany.com", "IncludeInDaashboard":true, "Data": { "_category1": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 }, "_category2": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 } }, "TableData": { "_tableCategory1": { "_text_field": ["text value","text_value2","text_value"], "_date_field": ["2025-03-20","2025-04-21","2024-03-20"], "_number_field": [3.1415,2.73,1.414] }, "_tableCategory2": { "_text_field": ["text value",null,"text_3"], "_date_field": ["2025-03-20","2025-08-23"], "_number_field": [3.1415,null] } } }

响应

响应包括一个 HTTP 状态代码、一组响应标头和一个正文。

状态代码

成功的作将返回状态代码 202 （Accepted）。

响应标头

此作的响应包括以下标头。响应还可能包括其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范。

Header	说明
`Location`	可用于检索作业状态的 URL。

响应正文

作的 Create File 响应包含将创建项目或概念的作业的标识符。格式 JSON 如下所示：

{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

创建想法

该 Create Idea 作将启动一个作业，以在您的订阅中创建项目概念。

注意

在创建新的项目概念时，您可以使用 Create Idea，但建议使用 Create File 。

请求

您可以构建 Create Idea 请求，如下所示。替换为 subscription-id 订阅的 ID。

方法	请求 URL
`POST`	`https://engage.minitab.com/api/v1/subscription-id/Item`

请求标头

Header	说明
`Authorization`	必填。通过 `Bearer` 授权方案提供 API 令牌。需要令牌才能具有 `Create Idea` 权限。
`Content-Type`	必填。`application/json`必须是。

请求正文

请求正文由具有 JSON 一个 required 属性 FileName的对象组成。

{ "FileName": "name of idea" }

您可以选择在概念中包含一个 Data 对象来设置数据字段值。数据由映射到字段代号和值的对象的单值类别代号组成。

{ "FileName": "name of idea", "Data": { "projectsummary": { "belt_level": "Green Belt", "critical_to": "Long text\r\nwith\r\nnewlines" }, "annualized_financial": { "annualized_actual_hard_savings": 100 } } }

注意

要查看可用于共享的有效数据字段和类别名称的列表，数据架构师可以从设置Engageweb app.

注意

只有在作请求中才能指定 Create Idea 共享给概念表单上的控件的数据字段。此外，不支持指定富文本、公式、只读或数据表字段。尝试为未共享到概念表单上的控件的字段或富文本、公式、只读或数据表字段提供数据将导致错误。

样品请求

Request: POST https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1 Headers: Authorization: Bearer token Content-Type: application/json Content-Length: 287 Body: { "FileName": "idea name", "Data": { "_category1": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 }, "_category2": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 } } }

响应

响应包括一个 HTTP 状态代码、一组响应标头和一个正文。

状态代码

成功的作将返回状态代码 202 （Accepted）。

响应标头

此作的响应包括以下标头。响应还可能包括其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范。

Header	说明
`Location`	可用于检索作业状态的 URL。

响应正文

作的 Create Idea 响应包含将创建项目概念的作业的标识符。格式 JSON 如下所示：

{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

示例响应

Response Status: HTTP/1.1 202 ACCEPTED Response headers: Location: /api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb Content-Type: application/json Response Body: { "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

获取作业状态

该 Get Job Status 作将检索指定作业的状态。

请求

Get Job Status （获取作业状态）请求的构造方式如下。替换为 subscription-id 订阅的 ID 和 job-id 有效的作业标识符。

方法	请求 URL
`GET`	`https://engage.minitab.com/api/v1/subscription-id/job/job-id`

请求标头

Header	说明
`Authorization`	必填。通过 `Bearer` 授权方案提供 API 令牌。

示例请求

Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb HTTP/1.1 Headers: Authorization: Bearer token

响应

响应包括状态 HTTP 代码和正文。

状态代码

成功的请求将返回状态代码 200 （OK）。

响应正文

该 Get Job Status 作的响应包含一个 Status integer 属性，该属性表示作业的各种可能状态，如以下示例所示。

{ "Status": 1 }

作业状态	说明
0	作业尚未开始
1	作业已启动;进行中
2	作业已完成
3	作业已失败
4	找不到作业
5	作业已取消

示例响应

Response Status: HTTP/1.1 200 OK Response headers: Content-Type: application/json Response Body: { "Status": 2 }