ドキュメントAPIの基本

ドキュメント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のフィールドを取得できます。 1234Documentの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でエンコードされ、DocumentnestedFieldsに埋め込まれます。 次のcURLまたはJavaコマンドを実行すると、コンテンツを取得できます。 1234Documentの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部分は、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]: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.DecoderDocumentのコンテンツをデコードします。

Base64.Decoder decoder = Base64.getDecoder();

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

DocumentのPATCHサービスは、Documentとそのフィールドを更新します。 次のcURLまたはJavaコマンドを実行して、Documentを更新できます。 1234Documentの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に続く)は、Documentdescriptionフィールドに新しい値を指定します。 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コードは、DocumentResourcepatchDocumentメソッドを呼び出し、Document’のID、更新するフィールドを含むDocumentオブジェクト、およびアップロードする更新されたファイルを渡します。

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

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

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

DocumentのPUTサービスは、Documentとそのフィールドを完全に置き換えます。 次のcURLまたはJavaコマンドを実行して、Documentを置き換えることができます。 1234Documentの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"

最初のフォームデータ部分は、新しいdescriptiontitleフィールドの値を設定します。 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コードは、DocumentResourceputDocumentメソッドを呼び出し、DocumentのID、Documentdescriptionフィールドとtitleフィールドの値を含むDocumentオブジェクト、およびアップロードする置換ファイルを渡します。

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

warning

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

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

ドキュメントを削除する

次のcURLまたはJavaコマンドを実行して、Documentを削除できます。 1234Documentの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インターフェースも参照してください。

追加情報