文档Webhooks API

Adobe Workfront Document Webhooks定义了一组API端点，Workfront通过这些API端点向外部文档提供商发出授权的API调用。 这允许任何人为任何文档存储提供商创建中间件插件。

基于webhook的集成的用户体验将与现有文档集成的用户体验类似，例如Google Drive、Box和Dropbox。 例如，Workfront用户将能够执行以下操作：

参考实施

为了帮助快速启动新的Webhooks实施的开发，Workfront提供了一个参考实施。 可以在https://github.com/Workfront/webhooks-app中找到此代码。 此实施基于Java，允许Workfront通过网络文件系统连接文档。

注册Webhook集成

Workfront管理员可以通过导航到Workfront中的设置>文档>自定义集成，为其公司添加自定义webhook集成。 在“设置”的“自定义集成”页面中，管理员可以查看现有文档Webhook集成的列表。 在此页面中，可以添加、编辑、启用和禁用集成。 要添加集成，请单击“添加集成”按钮。

可用字段

添加集成时，管理员将在以下字段中输入值：

身份验证

Workfront文档webhook支持两种不同的身份验证形式：OAuth2和ApiKey。 在这两种情况下，Workfront在进行API调用时在标头中传递身份验证令牌。

OAuth2

OAuth2允许Workfront代表用户向webhook提供程序发出授权的API调用。 在执行此操作之前，用户必须将其外部文档提供商帐户连接到Workfront并授予Workfront

代表他们行事的权限。 此握手过程仅针对每个用户发生一次。 以下是它的工作方式：

ApiKey

使用ApiKey向webhook提供程序进行授权API调用比OAuth2简单得多。 进行API调用时，Workfront只需在HTTP请求标头中传递ApiKey和Workfront用户名即可：

-------------------------------

apiKey: 12345

username: johndoe@foo.com

-------------------------------

Webhook提供程序可以使用用户名来应用特定于用户的权限。 当两个系统都使用单点登录(SSO)连接到LDAP时，这种方法效果最佳。

添加请求标头（可选）

除了使用OAuth2令牌或ApiKey进行身份验证之外，Workfront还可以为每个API调用向webhook提供程序发送一组预定义的标头。 Workfront管理员可以在注册或编辑Webook集成时进行此设置，如上面的部分所述。 请参阅注册Webhook集成。

例如，这可用于基本身份验证。 为此，Workfront管理员将在自定义集成对话框中添加以下请求标头信息：

授权基本QWxhZGRpbjpvcGVuIHNlc2FtZQ==

其中，QWxhZGRpbjpvcGVuIHNlc2FtZQ==是“username：password”的base-64编码字符串。 请参阅基本身份验证。 如果添加了此标头，Workfront将会在HTTP请求标头中传递此标头，以及其他请求标头：

­­­­­­­­­­­­­­­­­­­­­­­­­­-------------------------------

apiKey: 12345

username: johndoe@foo.com

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

API规范

以下是webhook提供程序应该实施的API列表，以便文档webhook正常工作。

获取OAuth2令牌（仅需要OAuth2身份验证）

返回经过身份验证的用户的OAuth2刷新令牌和访问令牌。 当用户设置文档提供商时，将调用一次。 随后进行调用以获取更新的访问令牌。

HTTP请求POST/any/url

该URL是可配置的，并且对应于自定义集成设置页面上的令牌端点URL值。

查询参数

响应

示例

POST /oauth2/token
grant_type=authorization_code
code=d9ac7asdf6asdf579d7a8
client_id=123456
client_secret=6asdf7a7a9a4af

响应

{
"access_token":"ad8af5ad5ads759",
"refresh_token":"9a0h5d87d808ads",
"expires_id":"3600"
}

获取文件或文件夹的元数据

返回指定文件或文件夹的元数据。

URL

/metadata？id=[文档或文件夹ID]GET

查询参数

响应

示例： https://www.acme.com/api/metadata?id=12345

响应

{
"title":"My Document",
"kind":"file"
"id":"12345",
"viewLink":"https://www.acme.com/viewDocument?id=12345",
"downloadLink":"https://www.acme.com/downloadDocument?id=12345",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size": "32554694"
}

获取文件夹中的项目列表

返回给定文件夹的文件和文件夹的元数据。

URL

GET/files

查询参数

文档Webhooks API当前不支持分页。

响应

包含文件和文件夹列表的JSON。 每个项的元数据与/metadata端点返回的元数据相同。

示例： https://www.acme.com/api/files?parentId=123456

响应

[
{
"title":"Folder A",
"kind":"folder",
"id":"2lj23lkj",
"viewLink":"https://www.acme.com/viewDocument?id=2lj23lkj",
"downloadLink":"https://www.acme.com/downloadDocument?id=2lj23lkj",
"mimeType":"",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":""
},
{
"title":"My Document",
"kind":"file",
"id":"da8cj234"
"viewLink":"https://www.acme.com/viewDocument?id=da8cj234",
"downloadLink":"https://www.acme.com/downloadDocument?id=da8cj234",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":"32554694"
},
]

执行搜索

返回搜索返回的文件和文件夹的元数据。 这可以作为全文搜索或常规数据库查询来实现。 当用户从外部文件浏览器执行搜索时，Workfront会调用/search端点。

URL

GET/search

查询参数

文档Webhooks API当前不支持分页。

响应

JSON，其中包含与查询匹配的文件和文件夹的元数据列表。 构成“匹配”的内容由webhook提供程序决定。 理想情况下，应该进行全文搜索。 执行基于文件名的搜索也可正常工作。

示例： https://www.acme.com/api/search?query=test-query

响应

[
{ File/Folder Metadata },
{ File/Folder Metadata }
]

获取文档的内容

返回文档的原始字节

URL

GET/下载

查询参数

响应

文档的原始字节。

示例： https://www.acme.com/api/download?id=123456

获取文档的缩略图

返回文档的原始缩略图字节。

URL

GET/thumbnail

查询参数

响应

原始缩略图字节。

示例： https://www.acme.com/api/thumbnail?id=123456

上传文件 — 第1部分，共2部分

将文件上传到文档存储提供程序是一个两步过程，需要两个单独的API端点。 Workfront通过调用/uploadInit开始上传过程。 此端点返回一个文档ID，然后在上传文档字节时将其传递到/upload。 根据基础文档存储系统，可能需要创建一个长度为零的文档，然后稍后更新该文档的内容。

添加到此规范版本1.1中的文档ID和文档版本ID可用于从Workfront中检索额外信息。 例如，如果文档管理系统需要有关文档的额外信息，webhook实施代码可以使用文档ID使用Workfront的RESTful API检索该信息。 好的做法是，这些信息可能来自文档上的自定义数据字段，并且包含任务、问题或项目。

URL

POST/uploadInit

查询参数

响应

文件的元数据，由/metadata端点定义。

示例： https://www.acme.com/api/uploadInit?parentId=12345&filename=new-file.png&docu mentId=511ea6e000023edb38d2effb2f4e6e3b&documentVersionId=511ea6e000023edb38d2e ffb2f4e6e3b

响应

[file_metadata]包含文档提供程序使用的新文档ID。

上传文件 — 第2部分（共2部分）

将文档的字节上载到webhook提供程序。

URL

PUT/upload

查询参数

请求正文

文档的原始内容字节。

响应

{
"result": "success"
}

或

{
"result": "fail"
}

示例： https://www.acme.com/api/upload?id=1234 [文档字节包含在更新流中]

响应

{
"result":"success"
}

获取有关服务的信息

（发布日期 — 待定）返回有关该服务的信息，如特性和功能。 Workfront将使用此信息自定义Workfront中的用户界面。 例如，如果webhook实施包含一些自定义操作，则JSON应在JSON中列出这些操作。 随后，用户将能够从Workfront调用这些操作。

URL

GET/serviceInfo

查询参数

无。 此外，对此端点的调用不应需要身份验证。

响应

包含有关此服务的信息的JSON

示例： https://www.acme.com/api/serviceInfo

返回

{
"webhook version": "1.2", "version": "1.0", "publisher": "Acme, LLC", "availableEndpoints": ["files", "metadata", "search", "download"

"thumbnail", "uploadInit", "upload" ], "customActions" [
{
"name": "archive", "displayName": "Archive" }, {

"name": "doSomethingElse", "displayName": "Do Something" }, ] }

创建文件夹

（在1.2版中添加）在给定目录中创建文件夹。
URL

POST/createFolder

查询参数

响应

新创建文件夹的元数据，如/metadata端点定义。

示例： POST https://www.acme.com/api/createFolder

-------------------------------

parentId=1234

name=New Folder ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

返回

{"title":"New Folder",
 "kind":"folder""id":"5678",
 "viewLink":"",
 "downloadLink":"",
 "mimeType":"",
 "dateModified":"2014­06­05T17:39:45.251Z"
 "size": ""
 }

删除文档或文件夹

（发布日期 — 待定）删除外部系统中具有给定ID的文档或文件夹。 删除文件夹也会删除其内容。

URL

PUT/delete

查询参数

响应JSON字符串，指示成功或失败，如下面的错误处理部分中所述。

示例： PUThttps://www.acme.com/api/delete id=1234

返回

{
"status": "success"
}

返回

{
"status": "failure", "error": "File not found"
}

重命名文档或文件夹

（发布日期 — 待定）在外部系统中使用给定ID重命名文档或文件夹。

URL

PUT/rename

查询参数

响应

指示成功或失败的JSON字符串，如下面的错误处理部分中所述。

示例：

PUT https://www.acme.com/api/rename

-------------------------------

id=1234

name=Folder B ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

{
"status": "success"
}returns
{
"status": "failure", error: "Folder cannot be renamed because a folder with that name already exists."
}

执行自定义操作

（发布日期 — 待定）此端点将允许Workfront用户（或可能是自动工作流事件）在外部系统中执行操作。 /customAction端点接受“name”参数，该参数允许webhook提供程序实现多个自定义操作。

webhook提供程序通过在customActions下的/serviceInfo响应中包含操作来向Workfront注册自定义操作。 在设置>文档>自定义集成下设置或刷新webhook提供程序时，Workfront会加载此列表。

用户可以通过选择“文档操作”下的部分来触发自定义操作

URL

GET/customAction

查询参数

响应

指示成功或失败的JSON字符串，如下面的错误处理部分中所述。 出现故障时（即状态=“故障”），Workfront将向用户显示提供的错误消息。

示例： https://sample.com/webhooks/customName?name=archive&documentId=5502082c003a4f30 ddec2fb2b739cb7c&documentVersionId=54b598a700e2342d6971597a5df1a8d3

响应

{
"status": "success"
}

错误处理

处理API请求时可能会出现问题。 应当在所有API端点中以一致的方式处理此问题。 发生错误时，webhook提供程序将执行以下操作：

{
"status": "error"
"error": "Sample error message"
}

测试

要验证文档webhook实施是否正常工作，请运行以下测试。 这些是手动测试，通过Workfront Web界面间接点击webhook实施的端点。

先决条件

要运行这些测试，您需要满足以下条件：

这些测试还假定您已经在Workfront中的“设置”>“文档”>“自定义集成”下注册了Document Webhook实例。

测试1：为用户预配Document Webhook服务

测试基于OAuth的Webhook提供程序的身份验证URL和令牌端点URL。

测试2：将文档链接到Workfront测试以下端点： /files、/metadata

测试3：导航到内容管理系统中的文档

测试以下端点： /metadata （尤其是viewLink）

测试4：导航到内容管理系统中的文档（登录）

测试以下端点： /metadata （尤其是viewLink）

测试5：从内容管理系统下载文档

测试以下端点： /metadata（尤其是downloadLink）

测试6：搜索内容

测试以下端点： /search

测试7：将文档从Workfront发送到内容管理系统

测试以下端点： /files、/uploadInit、/upload

测试8：在Workfront中查看缩略图

测试以下端点： /thumbnail

测试9：获取内容字节

测试以下端点： /download

测试10：刷新访问令牌（仅限OAuth2 Webhook提供程序）

测试以下端点：令牌端点URL

版本