Documentation

ドキュメントAPIの基本

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

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

ドキュメントを投稿する

  1. Liferay Dockerイメージを起動します。

    docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.22-ga22
    
  2. Liferayの初期化後、ブラウザでhttp://localhost:8080にアクセスします。

  3. デフォルトの認証情報を使用してサインインします。

    ユーザー名 : test@liferay.com

    パスワード: test

  4. サイトのIDを検索します 。 このIDは、いくつかのサービス呼び出しで使用します。

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

    curl https://learn.liferay.com/dxp/latest/ja/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
    

    注釈

    ユーザーとパスワードがそれぞれtest@liferay.comtestでない場合は、実行する前に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に置き換えて、ファイルをドキュメントとメディアにアップロードします。

    java -classpath .: **-DsiteId=1234 Document****POST** ToSite
    

    注釈

    ユーザーとパスワードがそれぞれtest@liferay.comtestでない場合は、実行する前にDocument **POST** ToSite.java ファイル内のこれらの値を置き換えて、クラスを再コンパイルしてください。

クラスは、ソースファイルDocument_POST_ToSite.javaをドキュメントとメディアにアップロードします。

JavaクラスはJavaソースファイルをアップロードしました。

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]:test"

コマンドの引数は次のとおりです。

引数

説明

-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 "test@liferay.com:test"

基本認証の資格情報。

注釈

ここでは、デモンストレーションの目的で基本認証を使用しています。 本番環境の場合は、 OAuth 2.0 経由でユーザーを認証する必要があります。

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]", "test"
	).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を使用しています。

注釈

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

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

重要

サービスの詳細は、 DocumentResource を参照してください。

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

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

次のcURLまたはJavaコマンドを実行すると、サイトのドキュメントを一覧表示できます。 上記のように、1234をサイトのIDに置き換えてください。

Documents GET FromSite.sh

コマンド:

./Documents_GET_FromSite.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
	-u "[email protected]:test"

Documents GET FromSite.java

コマンド:

java -classpath .:* -DsiteId=1234 Documents_GET_FromSite

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).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のフィールドを取得できます。 1234DocumentのIDに置き換えてください。

ちなみに

Documents_GET_FromSite.[java|sh]を使用して、サイトのDocument IDを取得します。

Document GET ById.sh

コマンド:

./Document_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	-u "[email protected]:test"

Document GET ById.java

コマンド:

java -classpath .:* -DdocumentId=1234 Document_GET_ById

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).build();

	Document document = documentResource.getDocument(
		Long.valueOf(System.getProperty("documentId")));

	System.out.println(document);
}

DocumentフィールドがJSONに一覧表示されます。

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

DocumentコンテンツはBase64でエンコードされ、DocumentnestedFieldsに埋め込まれます。 次のcURLまたはJavaコマンドを実行すると、コンテンツを取得できます。 1234DocumentのIDに置き換えてください。

Document GET ById_ContentValue.sh

コマンド:

./Document_GET_ById_ContentValue.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}?nestedFields=contentValue&fields=contentValue" \
	-u "[email protected]:test" \
	| 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部分は、DocumentnestedFieldsに埋め込まれた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]:test" \
	| 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

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

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

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).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.DecoderDocumentのコンテンツをデコードします。

Base64.Decoder decoder = Base64.getDecoder();

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

DocumentのPATCHサービスは、Documentとそのフィールドを更新します。 次のcURLまたはJavaコマンドを実行して、Documentを更新できます。 1234DocumentのIDに置き換えてください。

Document PATCH ById.sh

コマンド:

./Document_PATCH_ById.sh 1234

Code:

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]:test"

最初のフォームデータ部分(-Fに続く)は、Documentdescriptionフィールドに新しい値を指定します。 2番目のフォームデータ部分は、アップロードする更新されたファイルを指定します。

Document PATCH ById.java

コマンド:

java -classpath .:* -DdocumentId=1234 Document_PATCH_ById

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).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コードは、DocumentResourcepatchDocumentメソッドを呼び出し、Document'のID、更新するフィールドを含むDocumentオブジェクト、およびアップロードする更新されたファイルを渡します。

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

cURLコマンドは、ドキュメントの説明を変更しました。

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

DocumentのPUTサービスは、Documentとそのフィールドを完全に置き換えます。 次のcURLまたはJavaコマンドを実行して、Documentを置き換えることができます。 1234DocumentのIDに置き換えてください。

Document PUT ById.sh

コマンド:

./Document_PUT_ById.sh 1234

Code:

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]:test"

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

Document PUT ById.java

コマンド:

java -classpath .:* -DdocumentId=1234 Document_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).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コードは、DocumentResourceputDocumentメソッドを呼び出し、DocumentのID、Documentdescriptionフィールドとtitleフィールドの値を含むDocumentオブジェクト、およびアップロードする置換ファイルを渡します。

上記のcURLコマンドとJavaクラスは、Documentインスタンスを、それぞれ新しいタイトル"Document PUT ById.sh"と"Document PUT ById.java"を持ち、説明が"Goo"である完全に新しいインスタンスに置き換えます。

警告

現在のDocumentのタイトルを使用する場合を除いて、置換するDocumentに使用する titleの値を必ず指定してください。

cURLコマンドがドキュメントを置き換えました。

ドキュメントを削除する

次のcURLまたはJavaコマンドを実行して、Documentを削除できます。 1234DocumentのIDに置き換えてください。

Document DELETE ById.sh

コマンド:

./Document_DELETE_ById.sh 1234

Code:

curl \
	-X DELETE \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	-u "[email protected]:test"

Document DELETE ById.java

コマンド

java -classpath .:* -DdocumentId=1234 Document_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	DocumentResource.Builder builder = DocumentResource.builder();

	DocumentResource documentResource = builder.authentication(
		"[email protected]", "test"
	).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](https://github.com/liferay/liferay-portal/blob/7.4.3.22-ga22/modules/apps/headless/headless-delivery/headless-delivery-client/src/main/java/com/liferay/headless/delivery/client/resource/v1 0/DocumentResource.java) および [DocumentFolderResource](https://github.com/liferay/liferay-portal/blob/[$LIFERAY LEARN_PORTAL_GIT_TAG$]/modules/apps/headless/headless-delivery/headless-delivery-client/src/main/java/com/liferay/headless/delivery/client/resource/v1_0/DocumentFolderResource.java) のJavaインターフェイスも参照してください。