ドキュメントAPIの基本

LiferayのHeadless Deliveryアプリケーションは、 ドキュメントとメディア のRESTサービスを提供し、ドキュメントとフォルダの追加、情報の一覧表示、変更、削除などを行います。 ここでは、cURLコマンドとJavaクラスを使用してこれらのサービスを呼び出します。

サンプルのcURLコマンドとJavaクラスを使用してドキュメントをアップロードすることから始めます。

ドキュメントを投稿する

新しいLiferay インスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.112-ga112。

http://localhost:8080でLiferayへのサインインします。 メールアドレス [e-mail] とパスワード test を使用してください。 プロンプトが表示されたら、パスワードを learn に変更します。

ログインすると、 サイトのIDを取得します 。 このIDはいくつかのサービスコールで使用することになります。

次に、以下の手順に従います。

1. サンプルのプロジェクト をダウンロードして解凍します。

   curl https://resources.learn.liferay.com/dxp/latest/en/content-authoring-and-management/documents-and-media/developer-guide/liferay-g9i6.zip -O
   

   unzip liferay-g9i6.zip
   

cURLスクリプトを使用して、ファイルを ドキュメントとメディア にアップロードします。

1. コマンドラインで curl フォルダに移動します。

   cd liferay-g9i6.zip/curl
   

2. サイトIDをパラメータとしてDocument_POST_ToSite.shスクリプトを実行してファイルをアップロードする。 例えば、

   ./Document_POST_ToSite.sh 1234
   

   Note

   ユーザーとパスワードがそれぞれ [e-mail] と test でない場合は、Document_POST_ToSite.sh スクリプトを実行する前にこれらの値を置き換えてください。

スクリプトは、それ自体をサイトのドキュメントとメディアにアップロードします。

コマンド応答は、次のように、JSONで新しいドキュメントとメディアファイルを記述します。

{
  ...
  "description": "",
  ...
  "id": 38301,
  ...
  "title": "Document_POST_ToSite.sh"
}

応答には、ファイルの説明、新しく割り当てられたID、タイトルなどが含まれます。 後のコマンドのためにidの値に注意すること。

次に、Javaクラスを使用してファイルをアップロードします。

1. javaフォルダに移動し、Javaソースファイルをコンパイルする。

   cd ../java
   

   javac -classpath .:* *.java
   

2. 以下の Document_POST_ToSite クラスを実行し、siteId システムプロパティの値をサイトの ID に置き換えて、Documents and Media にファイルをアップロードします。

   java -classpath .:* -DsiteId=1234 Document_POST_ToSite
   

   Note

   ユーザーとパスワードがそれぞれ [e-mail] と test でない場合は、実行する前に Document_POST_ToSite.java ファイルでこれらの値を置き換えて、クラスを再コンパイルしてください。

このクラスはソースファイル Document_POST_ToSite.java を Documents and Media にアップロードする。

cURLコマンドとJavaクラスの仕組みをご覧ください。

cURLコマンドの検証

Document_POST_ToSite.shスクリプトは、cURLを使って headless-delivery アプリケーションのRESTサービスを呼び出してファイルをアップロードする。

ここでは、コマンドの引数を紹介します。

引数	説明
-F "file=@Document_POST_ToSite.sh"	投稿するファイル。
-H "Content-Type: multipart/form-data"	投稿されているメディアタイプ（ MIME 種別 ）。
-X POST	指定されたエンドポイントで呼び出すHTTPメソッド。
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents"	RESTサービスエンドポイント。 あなたのサイトIDパラメータは、${1}を置き換える。
-u "[e-mail]:learn"	基本認証の資格情報。

Note

ここでは、デモのために基本的な認証を使用しています。 本番環境では、 OAuth 2.0 を介してユーザーを認証する必要があります。 OAuth2 を使用する React アプリケーションのサンプルについては、 OAuth2によるユーザーの認証 を参照してください。

DocumentとDocumentFolder RESTサービス用の他のcURLコマンドも同様の引数を使用する。

次に、Javaの呼び出しがいかに似ているかを見てみましょう。

Javaクラスを調べる

Document_POST_ToSite.java クラスは、headless-delivery アプリケーション REST サービスを呼び出してファイルをアップロードする。

このクラスは、わずか3行のコードでRESTサービスを呼び出します。

行（省略形）	説明
DocumentResource.Builder builder = ...	DocumentResourceサービスインスタンスを生成するためのBuilder を取得する。
DocumentResource documentResource = builder.authentication(...).build();	基本認証を指定し、DocumentResource サービスインスタンスを生成する。
Document document = documentResource.postSiteDocument(...);	DocumentResource.postSiteDocumentメソッドを呼び出し、サイト ID、アップロードするファイルを表すDocumentオブジェクト、アップロードするファイルを指定するハッシュマップを渡す。 ファイルは任意である–この例では便宜上、ローカルのファイルDocument_POST_ToSite.java を使っている。

このプロジェクトには com.liferay.headless.delivery.client.jar ファイルが依存関係として含まれていることに注意してください。 すべての REST アプリケーションのクライアント JAR 依存情報は、インストー ルの API エクスプローラーの /o/api にある。

note

mainメソッドのコメントは、クラスの実行を示している。

他のJavaクラスの例もこれと似ているが、異なる DocumentResource メソッドを呼び出している。

Important

サービスの詳細については、 DocumentResource を参照のこと。

以下は、cURLとJavaを使って他のDocument RESTサービスを呼び出す例である。

サイトドキュメントを取得する

次のcURLまたはJavaコマンドを実行すると、サイトのドキュメントを一覧表示できます。 上記と同様に、1234をあなたのサイトのIDに置き換える。

Documents_GET_FromSite.sh

コマンド：

./Documents_GET_FromSite.sh 1234

コード：

Documents_GET_FromSite.java

コマンド：

java -classpath .:* -DsiteId=1234 Documents_GET_FromSite

コード：

サイトの Document オブジェクトはJSONでリストされている。

ドキュメントを取得する

以下のcURLまたはJavaコマンドを実行することで、Documentのフィールドを取得することができる。 1234をドキュメントのIDに置き換える。

Tip

サイトの Document ID を取得するには Documents_GET_FromSite.[java|sh] を使用する。

Document_GET_ById.sh

コマンド：

./Document_GET_ById.sh 1234

コード：

Document_GET_ById.java

コマンド：

java -classpath .:* -DdocumentId=1234 Document_GET_ById

コード：

DocumentフィールドはJSONでリストされている。

ドキュメントの内容を取得する

Document の内容は Base64 でエンコードされ、DocumentのnestedFields に埋め込まれる。 次のcURLまたはJavaコマンドを実行すると、コンテンツを取得できます。 1234をドキュメント`のIDに置き換える。

Document_GET_ById_ContentValue.sh

コマンド：

./Document_GET_ById_ContentValue.sh 1234

コード：

最初の引数行は、サービスエンドポイントと認証クレデンシャルをそれぞれ指定します。 URL の /o/headless-delivery/v1.0/documents/${1} の部分は、Document をその ID で取得するための REST サービスのエンドポイントである。 このURLはDocument_GET_ById.shスクリプトのURLと同じである。 nestedFields=contentValueの部分はDocumentのnestedFieldsに埋め込まれたcontentValue を要求します。 最後に、&fields=contentValueの部分は、contentValueフィールドをフィルタリングし、コンテンツフィールドだけを返すようにする。 しかし、サービスだけを呼び出すと、次のようにJSONでラップされたBase64エンコードされたコンテンツが返される：

{
  "contentValue" : "Y3VybCBcCgktRiAiZmlsZT1ARG9jdW1lbnRfUE9TVF9Ub1NpdGUuc2giIFwKCS1IICJDb250ZW50LVR5cGU6IG11bHRpcGFydC9mb3JtLWRhdGEiIFwKCS1YIFBPU1QgXAoJImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vL2hlYWRsZXNzLWRlbGl2ZXJ5L3YxLjAvc2l0ZXMvJHsxfS9kb2N1bWVudHMiIFwKCS11ICJ0ZXN0QGxpZmVyYXkuY29tOnRlc3Qi"
}

サービス呼び出しに続くルーチンで、エンコードされたコンテンツが処理されます。 sedとawkルーチンはDocumentのコンテンツ値を分離し、trルーチンはそれをデコードする。 あなたがアップロードしたDocument_POST_ToSite.sh Document に対して返されたデコードされた内容です：

Document_GET_ById_ContentValue.java

ドキュメント`の内容を取得し、それをデコードするJavaのコードは、以前のcURLコマンドよりも単純になっている。

コマンド：

java -classpath .:* -DdocumentId=1234 Document_GET_ById_ContentValue

コード：

ほとんどのコードは Document_POST_ToSite.java のコードに似ている。 主な違いがいくつかあります。

次の行は contentValue ネストされたフィールドをリクエストパラメータとして追加する。

builder.parameter("nestedFields", "contentValue");

ID で Document を取得したら、Base64.Decoder が Document の内容をデコードする。

Base64.Decoder decoder = Base64.getDecoder();

ドキュメントにパッチを適用する

Documentの PATCH サービスはDocument とそのフィールドを更新する。 以下のcURLまたはJavaコマンドを実行することで、Documentを更新することができる。 1234をドキュメントのIDに置き換える。

Document_PATCH_ById.sh

コマンド：

./Document_PATCH_ById.sh 1234

コード：

最初のフォームデータ部（-Fに続く）は Document の description フィールドの新しい値を指定します。 2番目のフォームデータ部分は、アップロードする更新されたファイルを指定します。 なお、両方が必要なわけではない。 ファイルのみ、またはドキュメントのメタデータのみにパッチを当てることができます。

Document_PATCH_ById.java

コマンド：

java -classpath .:* -DdocumentId=1234 Document_PATCH_ById

コード：

上の Java コードは DocumentResource の patchDocument メソッドを呼び出して、Document の ID、更新するフィールドを含む Document オブジェクト、アップロードする更新ファイルを渡している。

上記のコマンドは Document の説明を “Bar” に更新します。

ドキュメントを置き換える

DocumentのPUTサービスは、Documentとそのフィールドを完全に置き換える。 以下のcURLまたはJavaコマンドを実行することで、Documentを置き換えることができる。 1234をドキュメント`のIDに置き換える。

Document_PUT_ById.sh

コマンド：

./Document_PUT_ById.sh 1234

コード：

最初のフォームデータ部は、新しい description と title フィールド値を設定する。 2番目のフォームデータ部分は、アップロードする置換ファイルを指定します。

Document_PUT_ById.java

コマンド：

java -classpath .:* -DdocumentId=1234 Document_PUT_ById

コード：

上の Java コードは DocumentResource の putDocument メソッドを呼び出し、Document の ID、Document の description フィールドと title フィールドの値を含む Document オブジェクト、アップロードする置換ファイルを渡す。

上記のcURLコマンドとJavaクラスは、Documentのインスタンスを全く新しいものに置き換えるもので、それぞれ "Document_PUT_ById.sh "と "Document_PUT_ById.java "という新しいタイトルを持ち、"Goo. "という説明を持つ。

Warning

現在の Document のタイトルを使用したいのでなければ、置換する Document に必要な title の値を指定してください。

ドキュメントを削除する

以下のcURLまたはJavaコマンドを実行することで、Documentを削除することができる。 1234をドキュメント`のIDに置き換える。

Document_DELETE_ById.sh

コマンド：

./Document_DELETE_ById.sh 1234

コード：

Document_DELETE_ById.java

コマンド

java -classpath .:* -DdocumentId=1234 Document_DELETE_ById

コード：

ドキュメント」と「メディア」から「ドキュメント」が削除された。

その他のドキュメントおよびドキュメントフォルダサービス

以下のcURLコマンドとJavaクラスは、より多くの Document サービスと DocumentFolder サービスを示している。

ファイル	説明
Document_POST_ToDocumentFolder.[java\|sh]	ドキュメントをフォルダに投稿します。
DocumentFolder_GET_ById.[java\|sh]	フォルダのフィールドを一覧表示します。
DocumentFolder_PATCH_ById.[java\|sh]	フォルダとそのフィールドを更新します。
DocumentFolder_POST_ToSite.[java\|sh]	ドキュメントフォルダをサイトに投稿します。
DocumentFolder_PUT_ById.[java\|sh]	フォルダとそのフィールドを完全に置き換えます。
DocumentFolders_GET_FromSite.[java\|sh]	サイトのフォルダを一覧表示します。

API Explorer には Document と DocumentFolder のすべてのサービスとスキーマがリストアップされており、各サービスを試すためのインターフェイスが用意されている。

DocumentResource と DocumentFolderResource のJavaインターフェースも参照してください。

関連トピック

• ドキュメントとメディア
• RESTサービスの消費
• APIヘッダリファレンス
• GraphQL APIを消費する