oo

ドキュメント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へのサインインします。 メールアドレス test@liferay.com とパスワード 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

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

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

The file uploaded to Documents and Media.

コマンド応答は、次のように、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

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

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

The Java class uploaded the Java source file.

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

cURLコマンドの検証

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

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
	--form "file=@Document_POST_ToSite.sh" \
	--header "Content-Type: multipart/form-data" \
	--request "POST" \
	--user "test@liferay.com:learn"

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

引数 説明
-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:learn" 基本認証の資格情報。
Note

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

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

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

Javaクラスを調べる

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

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

	DocumentResource documentResource = builder.authentication(
		"test@liferay.com", "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 = ... 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

コード:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
	--user "test@liferay.com: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(
		"test@liferay.com", "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ドキュメントの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}" \
	--user "test@liferay.com: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(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		documentResource.getDocument(
			Long.valueOf(System.getProperty("documentId"))));
}

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

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

Document の内容は Base64 でエンコードされ、DocumentnestedFields に埋め込まれる。 次のcURLまたはJavaコマンドを実行すると、コンテンツを取得できます。 1234ドキュメント`の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" \
	--user "test@liferay.com:learn" \
	| sed -n "2 p" \
	| awk -F ":" '{print $2}' \
	| tr -d " \"" \
	| base64 -d

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

{
  "contentValue" : "Y3VybCBcCgktRiAiZmlsZT1ARG9jdW1lbnRfUE9TVF9Ub1NpdGUuc2giIFwKCS1IICJDb250ZW50LVR5cGU6IG11bHRpcGFydC9mb3JtLWRhdGEiIFwKCS1YIFBPU1QgXAoJImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vL2hlYWRsZXNzLWRlbGl2ZXJ5L3YxLjAvc2l0ZXMvJHsxfS9kb2N1bWVudHMiIFwKCS11ICJ0ZXN0QGxpZmVyYXkuY29tOnRlc3Qi"
}

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

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}?nestedFields=contentValue&fields=contentValue" \
	--user "test@liferay.com:learn" \
	| sed -n "2 p" \
	| awk -F ":" '{print $2}' \
	| tr -d " \"" \
	| base64 -d

Document_GET_ById_ContentValue.java

ドキュメント`の内容を取得し、それをデコードする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(
		"test@liferay.com", "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を更新することができる。 1234ドキュメントのIDに置き換える。

Document_PATCH_ById.sh

コマンド:

./Document_PATCH_ById.sh 1234

コード:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--form "document={\"description\": \"Bar\"}" \
	--form "file=@Document_POST_ToSite.sh" \
	--header "Content-Type: multipart/form-data; boundary=ARBITRARY" \
	--request "PATCH" \
	--user "test@liferay.com: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(
		"test@liferay.com", "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” に更新します。

The cURL command changed the document's description.

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

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

Document_PUT_ById.sh

コマンド:

./Document_PUT_ById.sh 1234

コード:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--form "document={\"description\": \"Goo\", \"title\": \"Document_PUT_ById.sh\"}" \
	--form "file=@Document_PUT_ById.sh" \
	--header "Content-Type: multipart/form-data; boundary=ARBITRARY" \
	--request "PUT" \
	--user "test@liferay.com: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(
		"test@liferay.com", "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 の値を指定してください。

The cURL command replaced the document.

ドキュメントを削除する

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

Document_DELETE_ById.sh

コマンド:

./Document_DELETE_ById.sh 1234

コード:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--request "DELETE" \
	--user "test@liferay.com: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(
		"test@liferay.com", "learn"
	).build();

	documentResource.deleteDocument(
		Long.valueOf(System.getProperty("documentId")));
}

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

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

以下の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 には DocumentDocumentFolder のすべてのサービスとスキーマがリストアップされており、各サービスを試すためのインターフェイスが用意されている。

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

関連トピック