檔案Webhooks API

Adobe Workfront Document Webhooks定義了一組API端點，Workfront會透過這些端點向外部檔案提供者發出授權的API呼叫。 這可讓任何人為任何檔案儲存提供者建立中介外掛程式。

webhook型整合的使用者體驗將與現有檔案整合類似，例如Google Drive、Box和Dropbox。 例如，Workfront使用者將能夠執行下列動作：

參考實作

為協助快速開始開發新的Webhook實作，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 Token或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 Token （僅需要OAuth2驗證）

傳回已驗證使用者的OAuth2重新整理權杖和存取權杖。 當使用者布建檔案提供者時，就會叫用一次。 進行後續呼叫以取得更新的存取Token。

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=[檔案或資料夾識別碼]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。 根據基礎檔案儲存系統，可能需要建立長度為零的檔案，然後稍後更新檔案的內容。

將檔案ID和檔案版本ID新增至本規格1.1版，可用來從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]包含檔案提供者使用的新檔案識別碼。

上傳檔案 — 第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/重新命名

查詢引數

回應

指示成功或失敗的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提供者會將actions包含在customActions下的/serviceInfo回應中，藉此向Workfront註冊自訂動作。 Workfront會在設定>檔案>自訂整合底下設定或重新整理webhook提供者時載入此清單。

使用者可以透過選擇「檔案動作」下的區段來觸發自訂動作

URL

GET/customAction

查詢引數

回應

指示成功或失敗的JSON字串，如以下錯誤處理區段中所指定。 失敗時（即狀態= "failure"），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網頁介面的手動測試，並間接點選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

版本