문서 웹후크 API

Adobe Workfront Document Webhooks는 Workfront이 외부 문서 공급자에 대해 승인된 API 호출을 수행하는 API 엔드포인트 세트를 정의합니다. 이를 통해 모든 문서 스토리지 공급자에 대한 미들웨어 플러그인을 생성할 수 있습니다.

Webhook 기반 통합을 위한 사용자 경험은 Google Drive, Box 및 Dropbox과 같은 기존 문서 통합의 사용자 경험과 유사합니다. 예를 들어 Workfront 사용자는 다음 작업을 수행할 수 있습니다.

참조 구현

새 웹후크 구현의 개발을 바로 시작할 수 있도록 Workfront에서는 참조 구현을 제공합니다. 이에 대한 코드는 https://github.com/Workfront/webhooks-app에서 찾을 수 있습니다. 이 구현은 Java 기반이며 Workfront에서 네트워크 파일 시스템의 문서를 연결할 수 있도록 해 줍니다.

Webhook 통합 등록

Workfront 관리자는 Workfront 내의 설정 > 문서 > 사용자 정의 통합으로 이동하여 회사에 대해 사용자 정의 웹후크 통합을 추가할 수 있습니다. 관리자는 설정 내의 사용자 정의 통합 페이지에서 기존 문서 Webhook 통합 목록을 볼 수 있습니다. 이 페이지에서 통합을 추가, 편집, 활성화 및 비활성화할 수 있습니다. 통합을 추가하려면 "통합 추가" 버튼을 클릭합니다.

사용 가능한 필드

통합을 추가할 때 관리자는 다음 필드에 값을 입력합니다.

인증

Workfront document webhooks는 OAuth2와 ApiKey라는 두 가지 서로 다른 인증 형식을 지원합니다. 두 경우 모두, Workfront은 API 호출을 수행할 때 헤더에 인증 토큰을 전달합니다.

OAuth2

OAuth2를 통해 Workfront은 사용자를 대신하여 웹후크 공급자에 대해 승인된 API 호출을 수행할 수 있습니다. 이 작업을 수행하기 전에 사용자는 외부 문서 공급자 계정을 Workfront에 연결하고 Workfront에 권한을 부여해야 합니다

를 대신하여 행동할 수 있는 액세스 권한. 이 핸드셰이킹 프로세스는 각 사용자에 대해 한 번만 수행됩니다. 작동 방식은 다음과 같습니다.

API 키

ApiKey를 사용하여 웹후크 공급자에 대해 승인된 API 호출을 수행하는 것은 OAuth2보다 훨씬 간단합니다. API를 호출할 때 Workfront은 HTTP 요청 헤더에 ApiKey 및 Workfront 사용자 이름을 전달하기만 하면 됩니다.

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

apiKey: 12345

username: johndoe@foo.com

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

Webhook 공급자는 사용자 이름을 사용하여 사용자별 권한을 적용할 수 있습니다. 이 기능은 두 시스템이 SSO(Single Sign-On)를 사용하여 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 사양

다음은 문서 웹후크가 작동하기 위해 웹후크 공급자가 구현해야 하는 API 목록입니다.

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

GET /metadata?id=[문서 또는 폴더 ID]

쿼리 매개 변수

응답

예: 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

쿼리 매개 변수

Document 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

쿼리 매개 변수

Document Webhooks API는 현재 페이지 매김을 지원하지 않습니다.

응답

쿼리와 일치하는 파일 및 폴더에 대한 메타데이터 목록이 포함된 JSON입니다. "일치"를 구성하는 것은 웹후크 공급자에 의해 결정됩니다. 이상적으로는 전체 텍스트 검색을 수행해야 합니다. 파일 이름 기반 검색도 작동합니다.

예: 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

파일 업로드 - 2부 중 1부

문서 스토리지 공급자에 파일을 업로드하는 것은 두 개의 개별 API 엔드포인트가 필요한 두 단계 프로세스입니다. Workfront은 /uploadInit 를 호출하여 업로드 프로세스를 시작합니다. 이 끝점은 문서 ID를 반환하고 문서 바이트를 업로드할 때 /upload에 전달됩니다. 기본 문서 스토리지 시스템에 따라 길이가 0인 문서를 만든 다음 나중에 문서 내용을 업데이트해야 할 수 있습니다.

이 사양의 버전 1.1에 추가된 문서 ID 및 문서 버전 ID를 사용하여 Workfront에서 추가 정보를 검색할 수 있습니다. 예를 들어 문서 관리 시스템에서 문서에 대한 추가 정보를 원하는 경우 웹후크 구현 코드는 문서 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부

문서의 바이트를 웹후크 공급자에 업로드합니다.

URL

PUT /업로드

쿼리 매개 변수

요청 본문

문서에 대한 원시 콘텐츠 바이트입니다.

응답

{
"result": "success"
}

또는

{
"result": "fail"
}

예: https://www.acme.com/api/upload?id=1234 [업데이트 스트림에 포함된 문서 바이트]

응답

{
"result":"success"
}

서비스에 대한 정보 가져오기

(릴리스 날짜 - TBD) 기능 등 서비스에 대한 정보를 반환합니다. 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": ""
 }

문서 또는 폴더 삭제

(릴리스 날짜 - TBD) 외부 시스템에서 해당 ID가 있는 문서 또는 폴더를 삭제합니다. 폴더를 삭제하면 해당 컨텐츠도 삭제됩니다.

URL

PUT /삭제

쿼리 매개 변수

응답 아래 오류 처리 섹션에 지정된 대로 성공 또는 실패를 나타내는 JSON 문자열입니다.

예: PUT https://www.acme.com/api/delete id=1234

반환

{
"status": "success"
}

반환

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

문서 또는 폴더 이름 바꾸기

(릴리스 날짜 - TBD) 외부 시스템에서 특정 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."
}

사용자 지정 작업 수행

(릴리스 날짜 - TBD) 이 끝점을 사용하면 Workfront 사용자(또는 자동화된 워크플로 이벤트)가 외부 시스템에서 작업을 수행할 수 있습니다. /customAction 끝점이 "name" 매개 변수를 허용하므로 웹후크 공급자가 여러 사용자 지정 작업을 구현할 수 있습니다.

웹후크 공급자는 customActions 아래의 /serviceInfo 응답에 작업을 포함하여 사용자 지정 작업을 Workfront에 등록합니다. Workfront은 설정 > 문서 > 사용자 정의 통합에서 웹후크 공급자를 설정하거나 새로 고칠 때 이 목록을 로드합니다.

사용자는 "문서 작업" 아래의 섹션을 선택하여 사용자 지정 작업을 트리거할 수 있습니다.

URL

GET /customAction

쿼리 매개 변수

응답

아래 오류 처리 섹션에 지정된 대로 성공 또는 실패를 나타내는 JSON 문자열입니다. 실패 시(예: 상태 = "failure") Workfront은 사용자에게 제공된 오류 메시지를 표시합니다.

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

응답

{
"status": "success"
}

오류 처리

API 요청을 처리할 때 문제가 발생할 수 있습니다. 이 작업은 모든 API 종단점에서 일관된 방식으로 처리되어야 합니다. 오류가 발생하면 웹후크 공급자는 다음 작업을 수행합니다.

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

테스트

문서 Webhook 구현이 올바르게 작동하는지 확인하려면 다음 테스트를 실행합니다. Workfront 웹 인터페이스를 거치고 Webhook 구현의 끝점을 간접적으로 히트하는 수동 테스트입니다.

전제 조건

이러한 테스트를 실행하려면 다음이 필요합니다.

또한 이러한 테스트에서는 설정 > 문서 > 사용자 정의 통합 아래의 Workfront에서 문서 Webhook 인스턴스를 이미 등록했다고 가정합니다.

테스트 1: 사용자를 위한 Document Webhook 서비스 제공

OAuth 기반 웹후크 공급자에 대한 인증 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 웹후크 공급자만 해당)

다음 끝점을 테스트합니다. 토큰 끝점 URL

버전