ドキュメントAPIの基本
LiferayのHeadless Deliveryアプリケーションは、ドキュメントとメディアのRESTサービスを提供し、ドキュメントとフォルダの追加、情報の一覧表示、変更、削除などを行います。 ここでは、cURLコマンドとJavaクラスを使用してこれらのサービスを呼び出します。
サンプルのcURLコマンドとJavaクラスを使用してドキュメントをアップロードすることから始めます。
ドキュメントを投稿する
新しいLiferay インスタンスを起動し、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.55-ga55。
http://localhost:8080でLiferayへのサインインします。 メールアドレス[email protected]_とパスワード_test_を使用してください。 プロンプトが表示されたら、パスワードを _learn_に変更します。
サインインしたら、 サイトのIDを取得 してください。このIDは、いくつかのサービスコールで使うことになります。
次に、以下の手順を実行します。
サンプルプロジェクトをダウンロードし、解凍する。
curl https://resources.learn.liferay.com/dxp/latest/ja/content-authoring-and-management/documents-and-media/developer-guide/liferay-g9i6.zip -O
unzip liferay-g9i6.zip
cURLスクリプトを使用して、ファイルをドキュメントとメディアにアップロードします。
コマンドラインで、
curl
フォルダに移動します。cd liferay-g9i6.zip/curl
サイトIDをパラメーターとして使用して
Document_POST_ToSite.sh
スクリプトを実行し、ファイルをアップロードします。 例:./Document_POST_ToSite.sh 1234
noteもし、ユーザーとパスワードがそれぞれ
[email protected]
とtest
でない場合は、Document_POST_ToSite.sh
スクリプトを実行する前に、これらの値を置き換えてください。
スクリプトは、それ自体をサイトのドキュメントとメディアにアップロードします。
コマンド応答は、次のように、JSONで新しいドキュメントとメディアファイルを記述します。
{
...
"description" : "",
...
"id" : 38301,
...
"title" : "Document_POST_ToSite.sh"
}
応答には、ファイルの説明、新しく割り当てられたID、タイトルなどが含まれます。 id
の値を後のコマンドのためにメモしておきます。
次に、Javaクラスを使用してファイルをアップロードします。
java
フォルダに移動し、Javaソースファイルをコンパイルします。cd ../java
javac -classpath .:* *.java
以下の
Document_POST_ToSite
クラスを実行し、siteId
システムプロパティ値をサイトのIDに置き換えて、ファイルをドキュメントとメディアにアップロードします。java -classpath .:* -DsiteId=1234 Document_POST_ToSite
noteもし、ユーザーとパスワードがそれぞれ
[email protected]
とtest
でない場合は、Document_POST_ToSite.java
ファイルでそれらの値を置き換え、実行する前にクラスを再コンパイルしてください。
クラスは、ソースファイルDocument_POST_ToSite.java
を Documents and Mediaにアップロードします。
cURLコマンドとJavaクラスの仕組みをご覧ください。
cURLコマンドの検証
Document_POST_ToSite.sh
スクリプトは、cURLを使用してheadless-delivery
アプリケーションのRESTサービスを呼び出すことにより、ファイルをアップロードします。
curl \
-F "[email protected]_POST_ToSite.sh" \
-H "Content-Type: multipart/form-data" \
-X POST \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
-u "[email protected]:learn"
コマンドの引数は次のとおりです。
引数 | 説明 |
---|---|
-F "[email protected]_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 "[email protected]:learn" |
基本認証の資格情報。 |
ここでは、デモのためにベーシック認証を使用しています。 本番環境の場合は、OAuth 2.0経由でユーザーを認証する必要があります。 OAuth2を使用したReactアプリケーションのサンプルは、OAuth2によるユーザーの認証をご覧ください。
Document
およびDocumentFolder
RESTサービスの他のcURLコマンドは、同様の引数を使用します。
次に、Javaの呼び出しがいかに似ているかを見てみましょう。
Javaクラスを調べる
Document_POST_ToSite.java
クラスは、headless-delivery
アプリケーションのRESTサービスを呼び出してファイルをアップロードします。
/**
* java -classpath .:* -DsiteId=1234 Document_POST_ToSite
*/
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
Document document = documentResource.postSiteDocument(
Long.valueOf(System.getProperty("siteId")), new Document(),
new HashMap<String, File>() {
{
put("file", new File("Document_POST_ToSite.java"));
}
});
System.out.println(document);
}
このクラスは、次の3行のコードのみを使用してRESTサービスを呼び出します。
行(省略形) | 説明 |
---|---|
DocumentResource.Builder builder = ... |
Builder を取得し、DocumentResource サービスインスタンスを生成します。 |
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依存関係情報は、/o/api
でインストール先のAPIエクスプローラーで確認できます。
main
メソッドのコメントでは、クラスの実行を実演しています。
他の例のJavaクラスはこれと類似していますが、異なるDocumentResource
メソッドを呼び出します。
サービスの詳細は DocumentResource を参照ください。
以下は、cURLとJavaを使って、他のDocument
RESTサービスを呼び出す例です。
サイトドキュメントを取得する
次のcURLまたはJavaコマンドを実行すると、サイトのドキュメントを一覧表示できます。 上記のように、1234
をサイトのIDに置き換えてください。
Documents_GET_FromSite.sh
コマンド:
./Documents_GET_FromSite.sh 1234
コード:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
-u "[email protected]:learn"
Documents_GET_FromSite.java
コマンド:
java -classpath .:* -DsiteId=1234 Documents_GET_FromSite
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
Page<Document> page = documentResource.getSiteDocumentsPage(
Long.valueOf(System.getProperty("siteId")), null, null, null, null,
Pagination.of(1, 2), null);
System.out.println(page);
}
サイトのDocument
オブジェクトがJSONに一覧表示されます。
ドキュメントを取得する
次のcURLまたはJavaコマンドを実行すると、Document
のフィールドを取得できます。 1234
をDocument
のIDに置き換えてください。
サイトの Document
ID を取得するには、 Documents_GET_FromSite.[java|sh]
を使用してください。
Document_GET_ById.sh
コマンド:
./Document_GET_ById.sh 1234
コード:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
-u "[email protected]:learn"
Document_GET_ById.java
コマンド:
java -classpath .:* -DdocumentId=1234 Document_GET_ById
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
System.out.println(
documentResource.getDocument(
Long.valueOf(System.getProperty("documentId"))));
}
Document
フィールドがJSONに一覧表示されます。
ドキュメントの内容を取得する
Document
コンテンツはBase64でエンコードされ、Document
のnestedFields
に埋め込まれます。 次のcURLまたはJavaコマンドを実行すると、コンテンツを取得できます。 1234
をDocument
のIDに置き換えてください。
Document_GET_ById_ContentValue.sh
コマンド:
./Document_GET_ById_ContentValue.sh 1234
コード:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}?nestedFields=contentValue&fields=contentValue" \
-u "[email protected]:learn" \
| sed -n "2 p" \
| awk -F ":" '{print $2}' \
| tr -d " \"" \
| base64 -d
最初の引数行は、サービスエンドポイントと認証クレデンシャルをそれぞれ指定します。 URLの/o/headless-delivery/v1.0/documents/${1}
部分は、IDでDocument
を取得するための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
に対して返されるデコードされたコンテンツは次のとおりです。
curl \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}?nestedFields=contentValue&fields=contentValue" \
-u "[email protected]:learn" \
| sed -n "2 p" \
| awk -F ":" '{print $2}' \
| tr -d " \"" \
| base64 -d
Document_GET_ById_ContentValue.java
Document
コンテンツを取得してデコードするJavaコードは、前のcURLコマンドよりも簡単です。
コマンド:
java -classpath .:* -DdocumentId=1234 Document_GET_ById_ContentValue
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
builder.parameter("nestedFields", "contentValue");
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
Document document = documentResource.getDocument(
Long.valueOf(System.getProperty("documentId")));
Base64.Decoder decoder = Base64.getDecoder();
System.out.println(
new String(decoder.decode(document.getContentValue())));
}
ほとんどのコードは、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
をDocument
のIDに置き換えてください。
Document_PATCH_ById.sh
コマンド:
./Document_PATCH_ById.sh 1234
コード:
curl \
-F "document={\"description\": \"Bar\"}" \
-F "[email protected]_POST_ToSite.sh" \
-H "Content-Type: multipart/form-data; boundary=ARBITRARY" \
-X PATCH \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
-u "[email protected]:learn"
最初のフォームデータ部分(-Fに続く)は、Document
のdescription
フィールドに新しい値を指定します。 2番目のフォームデータ部分は、アップロードする更新されたファイルを指定します。
Document_PATCH_ById.java
コマンド:
java -classpath .:* -DdocumentId=1234 Document_PATCH_ById
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
Document document = documentResource.patchDocument(
Long.valueOf(System.getProperty("documentId")),
new Document() {
{
description = "Bar";
}
},
new HashMap<String, File>() {
{
put("file", new File("Document_POST_ToSite.java"));
}
});
System.out.println(document);
}
上記のJavaコードは、DocumentResource
のpatchDocument
メソッドを呼び出し、Document
’のID、更新するフィールドを含むDocument
オブジェクト、およびアップロードする更新されたファイルを渡します。
上記のコマンドは、Document
の説明を"Bar"に更新します。
ドキュメントを置き換える
Document
のPUTサービスは、Document
とそのフィールドを完全に置き換えます。 次のcURLまたはJavaコマンドを実行して、Document
を置き換えることができます。 1234
をDocument
のIDに置き換えてください。
Document_PUT_ById.sh
コマンド:
./Document_PUT_ById.sh 1234
コード:
curl \
-F "document={\"description\": \"Goo\", \"title\": \"Document_PUT_ById.sh\"}" \
-F "[email protected]_PUT_ById.sh" \
-H "Content-Type: multipart/form-data; boundary=ARBITRARY" \
-X PUT \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
-u "[email protected]:learn"
最初のフォームデータ部分は、新しいdescription
とtitle
フィールドの値を設定します。 2番目のフォームデータ部分は、アップロードする置換ファイルを指定します。
Document_PUT_ById.java
コマンド:
java -classpath .:* -DdocumentId=1234 Document_PUT_ById
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
Document document = documentResource.putDocument(
Long.valueOf(System.getProperty("documentId")),
new Document() {
{
description = "Goo";
title = "Document_PUT_ById.java";
}
},
new HashMap<String, File>() {
{
put("file", new File("Document_PUT_ById.java"));
}
});
System.out.println(document);
}
上記のJavaコードは、DocumentResource
のputDocument
メソッドを呼び出し、Document
のID、Document
のdescription
フィールドとtitle
フィールドの値を含むDocument
オブジェクト、およびアップロードする置換ファイルを渡します。
上記のcURLコマンドとJavaクラスは、Document
インスタンスを、それぞれ新しいタイトル"Document_PUT_ById.sh"と"Document_PUT_ById.java"を持ち、説明が"Goo"である完全に新しいインスタンスに置き換えます。
現在の Document
のタイトルを使用する場合を除いて、代わりの Document
に使用するtitle
の値を必ず指定してください。
ドキュメントを削除する
次のcURLまたはJavaコマンドを実行して、Document
を削除できます。 1234
をDocument
のIDに置き換えてください。
Document_DELETE_ById.sh
コマンド:
./Document_DELETE_ById.sh 1234
コード:
curl \
-X DELETE \
"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
-u "[email protected]:learn"
Document_DELETE_ById.java
コマンド
java -classpath .:* -DdocumentId=1234 Document_DELETE_ById
コード:
public static void main(String[] args) throws Exception {
DocumentResource.Builder builder = DocumentResource.builder();
DocumentResource documentResource = builder.authentication(
"[email protected]", "learn"
).build();
documentResource.deleteDocument(
Long.valueOf(System.getProperty("documentId")));
}
Document
は、ドキュメントとメディアから削除されます。
その他のドキュメントおよびドキュメントフォルダサービス
次の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インターフェースも参照してください。