AlfrescoのREST APIについて - AlfrescoのREST APIについて

AlfrescoのREST APIについて - AlfrescoのREST APIについて - aegif Labo Blog Alfresco

null AlfrescoのREST APIについて

機能 2023.07.14

こんにちは。今回はAlfrescoのREST APIと、APIの機能を簡単に試すことができるツールであるAPI Explorerについて紹介します。

REST APIについて

概要

Alfrescoではファイルの作成や属性の更新などといったリポジトリに対する操作をREST APIを介して行うことができます。このAPIにアクセスする際のURIは以下の形式で構成されています。

https://[host:port]/alfresco/api/[tenant]/[scope]/[api name]/versions/1/[entity]/[relationship or operation]

各構成要素について、以下に解説します

host:port: Alfrescoがデプロイされているホストとポートです。例えばローカル環境にリポジトリを作成している場合localhost:8080などになります。
tenant: 基本的には-default-が入ります。Alfrescoには1つのインスタンスで複数の独立したECM環境を持つことができるマルチテナントという仕組みがあり、それを使用している場合は対象としたいテナント名を入力します。
scope: APIへアクセス可能な範囲を表します。例えばpublicの場合は外部から利用ができますが、privateの場合はAlfresco内部での使用に限られます。スコープは変更可能であり、新たに独自のスコープを作成することも可能です。
api name: APIの分類を表す名称が入ります。例えば、コア機能に関するAPIの場合はalfresco、検索に関するAPIの場合はsearchとなります。
entity: リポジトリの操作する対象を表します。例えばノードに関するAPIの場合はnodes、ユーザに関するAPIの場合はpeopleが入ります
relationship or operation: 対象リポジトリに対する関係性や操作の内容を表します。例えば、あるノードの子ノード一覧を取得する場合は、entity(nodes)と合わせて/nodes/{nodeId}/childrenのようになり、ノードを過去のバージョンに戻す操作の場合は/nodes/{nodeId}/versions/{versionId}/revertのようになります。

認証について

APIの多くは使用する際に認証が必要です。HTTPのBasic認証によって行うことも可能ですが、これはBase64でのエンコードのみのため、機密性を保つためにはHTTPSを使用し通信を暗号化する必要があります。また、Alfresco REST APIでは、チケットにより認証を行うこともできます。チケットを用いる場合でも機密性を保つために通信の暗号化は必要ですが、IDとパスワードを送る処理がチケット取得の際のみとなり、チケット利用時には機密情報を通信しなくなるため、安全性が向上します。チケットを取得するためにはhttp://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/ticketsに、以下のようにuserIdとpasswordを値として持つJSONをパラメータとしてPOSTリクエストを送ります。

curl -X POST "http://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/tickets" \
-H  "accept: application/json" \
-H  "Content-Type: application/json" \
-d "{  \"userId\": \"admin\",  \"password\": \"xxxxx\"}"

正しいID,パスワードを入力すると、以下のようにチケット情報が含まれるレスポンスが得られます。

{
  "entry": {
    "id": "TICKET_ef669d887698ed65fde549795328a873e15e5ba7",
    "userId": "admin"
  }
}

このチケットをリクエストのヘッダにBase64にエンコードした状態で加えることで、APIを認証した状態で実行できます。各OSでのBase64へのエンコード方法の一例を以下に記載します。

Mac、Linuxの場合

echo -n "TICKET_ef669d887698ed65fde549795328a873e15e5ba7" | base64

Windowsの場合

powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"TICKET_ef669d887698ed65fde549795328a873e15e5ba7\"))"

エンコードしたチケットを用いて、認証が必要なAPIを実行できます。例えばAlfresco上のユーザ一覧を取得する/peopleの場合、以下のcurlコマンドで実行できます。なお、チケットには有効期限があるため、期限が切れた後に実行するとエラーとなります。その場合は再度チケットの取得を行ってください。

curl -X GET "http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people" \
-H  "accept: application/json" \
-H  "authorization: Basic VElDS0VUX2VmNjY5ZDg4NzY5OGVkNjVmZGU1NDk3OTUzMjhhODczZTE1ZTViYTc="

API Explorerについて

AlfrescoのREST APIには多くのAPIが用意されており、それぞれについてソート方法の指定など実行時の挙動を調整するためのオプションがあります。各APIの用途や実際の挙動の確認を簡単に行うため、API Explorerというツールが用意されています。

導入方法

alfresco-docker-installerや、Docker Composeを使って環境を用意した場合、API Explorerはデフォルトで導入されており、http://[host:port]/api-explorer/から使用できます。他の方法で環境を用意した場合などで未導入の場合は、使用するACSのバージョンに最も近いバージョンのapi-explorer.warをAlfresco's Nexus repositoryからダウンロードし、 ACSを実行しているtomcatのtomcat/webapps/に配備することで導入できます。

使い方

API ExplorerはOpenAPI(旧Swagger)のフォーマットで記載されており、以下の手順で各APIの挙動を試すことができます。

画面右上のセレクトボックスから、使いたいAPIが含まれるdefinitionを選択します。このdefinitionはAPIを機能毎にグループ分けしたもので、同じdefinitionに属するAPIは共通するBase URLを持ちます。
Authorizeボタンか各APIの右側に表示されている鍵のアイコンをクリックすると、ユーザ名、パスワードの入力画面が表示されます。ここにAPIを実行するユーザのIDとパスワードを入力することで、そのユーザをAPIの実行者として認証が行えます。
使いたいAPIの箇所をクリックすると、そのAPIの機能や各パラメータに関する説明と、正常実行時とエラー時のレスポンス内容に関する情報が表示されます。パラメータ情報の箇所にはテキストボックスが表示されていますが、パラメータ欄の右上の「Try it out」ボタンを押すまでは入力ができないようになっています。
「Try it out」ボタンを押すことで、パラメータが入力できるようになり「Execute」ボタンが表示されます。
必要なパラメータを入力後、「Execute」ボタンをクリックするとそのAPIが実行され、以下の画像のように、対応するCurlコマンド、リクエストURL、サーバからのレスポンス内容が表示されます。