ドキュメントAPIの基本

Documentation Menu
戻る

ドキュメント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は、いくつかのサービスコールで使うことになります。

次に、以下の手順を実行します。

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

    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スクリプトを使用して、ファイルをドキュメントとメディアにアップロードします。

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

    cd liferay-g9i6.zip/curl

  2. サイト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クラスを使用してファイルをアップロードします。

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

    cd ../java

    javac -classpath .:* *.java

  2. 以下の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にアップロードします。

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]: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" 基本認証の資格情報。
note

ここでは、デモのためにベーシック認証を使用しています。 本番環境の場合は、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エクスプローラーで確認できます。

note

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

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

important

サービスの詳細は 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に置き換えてください。

tip

サイトの 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"に更新します。

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

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

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"である完全に新しいインスタンスに置き換えます。

warning

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

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

ドキュメントを削除する

次の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インターフェースも参照してください。

追加情報

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center