Adobe Workfront规划API基础知识

Adobe Workfront Planning API的目标是通过引入通过HTTP运行的RESTful架构来简化与Planning的构建集成。 本文档假设您熟悉REST和JSON响应。

有关完整的端点引用、请求/响应架构和特定于版本的详细信息，请参阅Workfront Planning API开发人员文档。

身份验证

Workfront计划API使用OAuth 2.0进行身份验证。 凭据通过Adobe Developer Console进行设置。

根据您的集成类型，我们支持以下两个流程：

要开始配置，请在Adobe Developer Console中创建一个项目，然后添加Workfront规划API以获取凭据。

要设置凭据，请在Workfront中创建OAuth2应用程序。

有关信息，请参阅为Workfront集成创建OAuth2应用程序。

API版本控制

Planning API通过URL路径进行版本控制。

以下是当前支持的版本：

有关当前支持的版本的详细信息，请参阅文章Workfront Planning API开发人员文档。

我们建议在所有集成中明确定向某个版本：

https://{customer-domain}/maestro/api/v2/...

发布新的主要版本后，在告知弃用日期之前，以前的版本将继续可用。

按照Workfront发行说明操作，及时了解API更改。

URL结构和操作

通过将HTTP请求发送到对象的唯一URI来控制对象。 操作由HTTP方法指定。

有关完整的端点路径和请求/响应示例，请参阅developer.adobe.com/wf-planning上的​API引用。

HTTP状态代码

Planning API返回标准HTTP状态代码：

错误处理

Planning API会以一致的格式返回错误。 每个错误响应包括人工可读消息、机器可读错误代码和支持升级请求ID。

示例错误响应：

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

使用errorCode （不是status）来推动程序化错误处理。 它提供了故障的最具体分类。

过滤记录

在记录搜索请求中使用filter参数可仅返回符合特定条件的记录。 对于POST请求，filter是请求正文中的JSON属性。 对于GET请求，filter是包含JSON编码的筛选器组的查询参数。 过滤器使用具有显式逻辑运算符的类型复合结构。

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

可以使用AND / OR运算符嵌套筛选器以生成复合条件：

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

字段类型和搜索修饰符

您可以使用带有字段的修饰符和过滤器来控制在结果中返回哪些数据。

有关示例，请参阅Workfront Planning API开发人员文档。

使用搜索修饰符

Workfront Planning支持以下搜索修饰符：

按字段类型支持的筛选条件

按人员字段筛选

人员字段筛选器(user、created-by、updated-by、approved-by)接受Adobe IMS用户ID和Workfront用户ID。 纯字符串值将解释为Adobe IMS用户ID。

要设置标识符类型以检查Workfront用户ID，您需要显式传递id和idType参数。 对于Workfront用户ID，idType支持的值为“WF”；对于Adobe IMS用户ID，支持的值为“IMS”。

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

按外部ID筛选外部引用字段

外部引用字段将记录链接到其他Adobe系统（如Workfront项目或AEM Assets）中的对象。 在内部，Planning将Planning记录ID分配给这些对象。 要直接按其原始对象ID筛选此类字段，请将"matchExternalId": true添加到筛选条件。

此标志仅对referenceOptions.isExternal为true的引用字段有效；对于非外部引用字段将忽略此标志。 如果无法解析单个字符串值，则请求将失败，并显示400 Bad Request。 如果提供了列表值，则未解析的条目将传递未更改并且只是不匹配而已。

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

外部连接字段

Planning记录类型可以承载外部引用字段，这些字段将记录链接到其他Adobe系统中的对象，而不是其他Planning记录类型。

要通过API创建外部引用字段，请将新REFERENCE字段上的referenceOptions.recordTypeId设置为所需外部记录类型的ID。 服务器自动从目标记录类型派生referenceOptions.isExternal=true和连接元数据(connectionName, objectName)。

支持的外部对象类型包括Workfront对象（项目、任务、项目、项目群、项目组合、公司、组、团队、用户）和AEM Assets（资源、内容片段）。

排序

通过在请求中包含sort数组来按任何字段对结果进行排序：

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

按顺序评估多个排序字段。 在分页时始终应用排序，以确保跨页面排序一致。

要对结果分组，请在排序时包含一个组数组：

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

场投影

要限制响应中返回的字段，请使用逗号分隔列表的fieldIds或fieldAliases查询参数。 这减小了响应有效负载的大小，建议用于高容量集成或对延迟敏感的集成。

分页

Planning API支持分页响应以管理大型数据集。

例如，使用以下请求从记录搜索中检索包含500条记录的第二页：

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

所有分页的响应都包括一个结构化包络，指示是否还有更多结果可用。 在分页时始终应用排序，以确保跨页面排序一致。

批量操作

Planning API支持在单个请求中批量创建、更新、修补和删除记录。 有关终结点路径、请求格式和每个操作的记录限制，请参阅developer.adobe.com/wf-planning上的​API引用。

权限

实体的权限通过专用权限API进行管理，独立于资源端点本身。 这允许您读取当前权限、管理共享列表以及独立于数据操作处理访问请求。 有关详细信息，请参阅文章Workfront规划API中的“API引用”部分。

将Planning API与Workfront自定义表单结合使用

您可以从Workfront自定义表单中的外部查找字段调用Planning API，以直接在Workfront对象中显示Planning数据。 有关详细信息，请参阅自定义表单中的外部查找字段示例。

相关资源

有关更多与API相关的文档，另请参阅以下文章：