ドキュメント Webhooks API

Adobe Workfront のドキュメント Web フックは、Workfront が外部ドキュメントプロバイダーに対して認可された API 呼び出しを行う API エンドポイントのセットを定義します。これにより、誰でも任意のドキュメントストレージプロバイダー用のミドルウェアプラグインを作成できます。

Web フックベースの統合のユーザーエクスペリエンスは、Google Drive、Box、Dropboxなどの既存のドキュメント統合のユーザーエクスペリエンスに似ています。例えば、Workfront ユーザーは以下のアクションを実行できます。

参照の実装

新しい web フック実装の開発をすぐに開始できるように、Workfront では参照の実装を提供しています。このためのコードは https://github.com/Workfront/webhooks-app にあります。この実装は Java ベースで、Workfront がネットワークファイルシステム上でドキュメントに接続できるようにします。

Web フック統合の登録

Workfrontの 管理者は、Workfront 内で設定／ドキュメント／カスタム統合に移動して、会社のカスタム web フック統合を追加することができます。設定内のカスタム統合ページから、管理者は既存のドキュメント web フック統合のリストを表示することができます。このページから、統合を追加、編集、有効化、無効化することができます。統合を追加するには、「統合を追加」ボタンをクリックします。

使用可能なフィールド

統合を追加する際、管理者は以下のフィールドに値を入力します。

認証

Workfront ドキュメント web フックでは、OAuth2 および ApiKey の 2 種類の認証形式をサポートしています。どちらの場合も、Workfront は API を呼び出す際に、認証トークンをヘッダーに入れて渡します。

OAuth2

OAuth2 を使用すると、Workfront は、承認済み API 呼び出しをユーザーの代わりに web フックプロバイダーに対して行うことができます。その前に、ユーザーは外部ドキュメントプロバイダーアカウントを Workfront に接続し、Workfront への

アクセス権を付与して、ユーザーの代わりに操作できるようにする必要があります。このハンドシェイクプロセスは、ユーザーごとに 1 回だけ行われます。仕組みは次のとおりです。

ApiKey

ApiKey を使用して web フックプロバイダーへの承認済み API 呼び出しを行う方が、OAuth2 よりもはるかに簡単です。API 呼び出しを行う際に、Workfront は ApiKey と Workfront ユーザー名を HTTP リクエストヘッダーに入れて渡すだけです。

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

apiKey: 12345

username: johndoe@foo.com

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

Web フックプロバイダーは、このユーザー名を使用して、ユーザー固有の権限を適用できます。この仕組みが最も効果を発揮するのは、両方のシステムがシングルサインオン（SSO）を使用して LDAP に接続している場合です。

リクエストヘッダーの追加（オプション）

Workfront では、認証に OAuth2 トークンまたは ApiKey を使用する以外に、あらかじめ定義された一連のヘッダーを API 呼び出しごとに web フックプロバイダーに送信できます。前の節で説明したように、Workfront 管理者は web フック統合の登録または編集時にこれを設定できます。「Web フック統合の登録」を参照してください。

例えば、これは基本認証に使用できます。それには、Workfront 管理者がカスタム統合ダイアログで次のリクエストヘッダー情報を追加します。

Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

この QWxhZGRpbjpvcGVuIHNlc2FtZQ== は、「username:password」を Base64 でエンコードした文字列です。「基本認証」を参照してください。これが追加された場合、Workfront はこれを次のように、他のリクエストヘッダーに加えて、HTTP リクエストヘッダーに入れて渡します。

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

apiKey: 12345

username: johndoe@foo.com

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

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

API 仕様

ドキュメント web フックを機能させるために web フックプロバイダーが実装する必要がある API のリストを以下に示します。

OAuth2 トークンの取得（OAuth2 認証のみ必要）

認証済みユーザーの OAuth2 更新トークンとアクセストークンを返します。この呼び出しは、ユーザーがドキュメント提供者をプロビジョニングするときに 1 回だけ実行されます。その後の呼び出しは、更新されたアクセストークンを取得するために行われます。

HTTP リクエスト POST [任意の 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=[document or folder 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

クエリパラメーター

ドキュメント web フック 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

クエリパラメーター

ドキュメント web フック API では、現在、ページネーションをサポートしていません。

応答

クエリに一致するファイルやフォルダーのメタデータのリストを含んだ JSON。何をもって「一致」とするかは、web フックプロバイダーによって決まります。全文検索を行うのが理想です。ファイル名ベースの検索も有効です。

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

応答

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

ドキュメントのコンテンツの取得

ドキュメントの未加工のバイトデータを返します

URL

GET /download

クエリパラメーター

応答

ドキュメントの未加工のバイトデータ。

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

ドキュメントのサムネールの取得

ドキュメントのサムネールの未加工バイトデータを返します。

URL

GET /thumbnail

クエリパラメーター

応答

サムネールの未加工のバイトデータです。

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

ファイルのアップロード（前半）

ドキュメントストレージプロバイダーへのファイルのアップロードは、2 つの異なる API エンドポイントを必要とする 2 段階プロセスです。Workfront は、/uploadInit を呼び出して、アップロードプロセスを開始します。このエンドポイントはドキュメント ID を返します。この ID は、ドキュメントのバイトデータをアップロードする際に /upload に渡されます。基盤となるドキュメントストレージシステムによっては、長さ 0 のドキュメントを作成した後でドキュメントの内容を更新する必要がある場合があります。

ドキュメント ID とドキュメントバージョン ID を使用して、Workfront から追加の情報を取得できる機能が、この仕様のバージョン 1.1 に追加されました。例えば、ドキュメント管理システムがドキュメントに関する追加情報を必要とする場合に、web フックの実装コードでドキュメント 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 が含まれます。

ファイルのアップロード（後半）

Web フックプロバイダーにドキュメントのバイトデータをアップロードします。

URL

PUT /upload

クエリパラメーター

リクエスト本文

ドキュメントの Raw コンテンツのバイトデータです。

応答

{
"result": "success"
}

または

{
"result": "fail"
}

例：https://www.acme.com/api/upload?id=1234 [更新ストリームに含まれるドキュメントのバイトデータ]

応答

{
"result":"success"
}

サービスに関する情報の取得

（リリース日 - 未定）特長や機能など、サービスに関する情報を返します。Workfront では、この情報を使用して Workfront のユーザーインターフェイスをカスタマイズします。例えば、web フックの実装にいくつかのカスタムアクションが含まれている場合、それらの操作は 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 文字列（この後の「エラー処理」の節を参照）。

例： PUT https://www.acme.com/api/delete?documentId=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」パラメーターを受け取ります。これにより、web フックプロバイダーは複数のカスタム操作を実装できます。

Web フックプロバイダーでは、カスタムアクションを /serviceInfo 応答の customActions 下に含めることで、Workfront に登録します。設定／ドキュメント／カスタム統合で web フックプロバイダーを設定または更新すると、Workfront がこのリストを読み込みます。

ユーザーは、「ドキュメントアクション」の下のセクションを選択することで、カスタムアクションをトリガーできます。

URL

GET /customAction

クエリパラメーター

応答

成功または失敗を示す JSON 文字列（この後の「エラー処理」の節を参照）。失敗（status = "failure"）の場合、Workfront は、用意されているエラーメッセージをユーザーに表示します。

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

応答

{
"status": "success"
}

エラー処理

API リクエストを処理する際に問題が発生する場合があります。その対応は、すべての API エンドポイントで一貫した方法で行う必要があります。エラーが発生した場合は、web フックプロバイダーが以下を行います。

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

テスト

ドキュメント web フックの実装が正しく動作することを確認するには、以下のテストを実行します。これらは、Workfront web インターフェイスを介して web フック実装のエンドポイントに間接的にヒットする手動のテストです。

前提条件

これらのテストを実行するには、以下が必要です。

またこれらのテストでは、Workfront の設定／ドキュメント／カスタム統合でドキュメント web フックインスタンスを既に登録していることも前提としています。

テスト 1：ユーザーへのドキュメント web フックサービスのプロビジョニング

OAuth ベースの web フックプロバイダーの認証 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 web フックプロバイダーの場合のみ）

トークンエンドポイント URL のエンドポイントをテストします。

バージョン