ドキュメントAPIの基本

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

注

Liferay DXP 2024.Q4+/Portal GA129+ Documents API は、外部参照コード (ERC) を使用してドキュメントエントリ、フォルダー、タイプ、メタデータセット、ショートカットを参照するようになりました。これにより、インスタンス間で一貫した識別が可能になり、バッチエクスポート/インポートがサポートされ、コンテンツ管理と移植性が向上します。

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

ドキュメントを投稿する

新しいLiferay インスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

http://localhost:8080 で Liferay にサインインしてください。 メールアドレス [e-mail] とパスワード test を使用してください。 プロンプトが表示されたら、パスワードを learnに変更します。

ログインすると、 はサイトの ID を取得します。 このIDを複数のサービス呼び出しで使用してください。

次に、以下の手順に従います。

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

   curl https://resources.learn.liferay.com/examples/liferay-g9i6.zip -O
   

   unzip liferay-g9i6.zip
   

cURLスクリプトを使用して、ファイルを ドキュメントとメディアにアップロードします。

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

   	cd liferay-g9i6.zip/curl
   

2. サイトIDをパラメータとして指定して、 Documents_POST_ToSites.sh スクリプトを実行してファイルをアップロードします。 例えば、

   ./Documents_POST_ToSites.sh 1234
   

   注

   ユーザー名とパスワードがそれぞれ [e-mail] と learnでない場合は、実行する前に Documents_POST_ToSites.sh スクリプト内のこれらの値を置き換えてください。

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

コマンド応答は、次のように、JSONで新しいドキュメントとメディアファイルを記述します。

{
  ...
  "description": "",
  ...
  "id": 38301,
  ...
  "title": "Documents_POST_ToSites.sh"
}

応答には、ファイルの説明、新しく割り当てられたID、タイトルなどが含まれます。 idの値を後のコマンドのためにメモしておきます。

次に、Javaクラスを使用してファイルをアップロードします。

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

   cd ../java
   

   javac -classpath .:* *.java
   

2. 以下の Documents_POST_ToSites クラスを実行して、 siteId システム プロパティ値をサイトの ID に置き換えて、ファイルを Documents and Media にアップロードします。

   java -classpath .:* -DsiteId=1234 Documents_POST_ToSites
   

   注

   ユーザー名とパスワードがそれぞれ [e-mail] および learnでない場合は、 Documents_POST_ToSites.java ファイル内のこれらの値を置き換えて、実行する前にクラスを再コンパイルしてください。

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

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

cURLコマンドの検証

Documents_POST_ToSites.sh スクリプトは、cURL を使用して ヘッドレス配信 アプリケーション REST サービスを呼び出すことによりファイルをアップロードします。

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
	--form "file=@Documents_POST_ToSites.sh" \
	--header "Content-Type: multipart/form-data" \
	--request "POST" \
	--user "[e-mail]:learn"

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

引数	説明
-F "file=@Documents_POST_ToSites.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 "[e-mail]:learn"	基本認証の資格情報。

注

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

ヒント

サイトではなく特定のフォルダにドキュメントを投稿するには、REST サービス エンドポイントとして http://localhost:8080/o/headless-delivery/v1.0/document-folders/{documentFolderId}/documents を使用し、 {documentFolderId} をフォルダ ID に置き換えます。

DocumentおよびDocumentFolder RESTサービスの他のcURLコマンドは、同様の引数を使用します。

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

Javaクラスを調べる

Documents_POST_ToSites.java クラスは、 ヘッドレス配信 アプリケーション REST サービスを呼び出すことでファイルをアップロードします。

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		documentResource.postSiteDocument(
			Long.valueOf(System.getProperty("siteId")), new Document(),
			new HashMap<String, File>() {
				{
					put("file", new File("Documents_POST_ToSites.java"));
				}
			}));
}

このクラスは、わずか3行のコードでRESTサービスを呼び出します。

行（省略形）	説明
DocumentResource.Builder builder = ...	Builderを取得し、DocumentResourceサービスインスタンスを生成します。
DocumentResource documentResource = builder.authentication(...).build();	基本認証を指定し、DocumentResourceサービスインスタンスを生成します。
Document document = documentResource.postSiteDocument(...);	DocumentResource.postSiteDocumentメソッドを呼び出し、サイトID、アップロードされたファイルを表すDocumentオブジェクト、およびアップロードするファイルを指定するハッシュマップを渡します。 ファイルは任意です–この例では、便宜上ローカル ファイル Documents_POST_ToSites.java を使用します。

ヒント

サイトではなく特定のフォルダーにドキュメントを投稿するには、 postDocumentFolderDocument の代わりに postSiteDocument を使用します。 最初の引数としてフォルダIDを渡してください。その他の引数は変更する必要はありません。

プロジェクトには、依存関係として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_FromSites.sh

コマンド：

./Documents_GET_FromSites.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/documents" \
	--user "[e-mail]:learn"

Documents_GET_FromSites.java

コマンド：

java -classpath .:* -DsiteId=1234 Documents_GET_FromSites

コード：

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		documentResource.getSiteDocumentsPage(
			Long.valueOf(System.getProperty("siteId")), null, null, null,
			null, Pagination.of(1, 2), null));
}

サイトの Document オブジェクトが JSON レスポンスに含まれています。

{
  "actions": {
    "updateBatch": {
      "method": "PUT",
      "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/batch"
    },
    "get": {
      "method": "GET",
      "href": "http://localhost:8080/o/headless-delivery/v1.0/sites/1234/documents"
    },
    "create": {
      "method": "POST",
      "href": "http://localhost:8080/o/headless-delivery/v1.0/sites/1234/documents"
    },
    "createBatch": {
      "method": "POST",
      "href": "http://localhost:8080/o/headless-delivery/v1.0/sites/1234/documents/batch"
    },
    "deleteBatch": {
      "method": "DELETE",
      "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/batch"
    }
  },
  "facets": [],
  "items": [
    {
      "actions": {
        "get-rendered-content-by-display-page": {
          "method": "GET",
          "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/32131/rendered-content-by-display-page/{displayPageKey}"
        },
        "get": {
          "method": "GET",
          "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/32131"
        },
        "replace": {
          "method": "PUT",
          "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/32131"
        },
        "update": {
          "method": "PATCH",
          "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/32131"
        },
        "delete": {
          "method": "DELETE",
          "href": "http://localhost:8080/o/headless-delivery/v1.0/documents/32131"
        }
      },
      "adaptedImages": [
        {
          "contentUrl": "/o/adaptive-media/image/32131/Preview-1000x0/seahorse.jpg?t=1715340699885",
          "height": 1510,
          "resolutionName": "Preview-1000x0",
          "sizeInBytes": 127254,
          "width": 1000
        },
        {
          "contentUrl": "/o/adaptive-media/image/32131/Thumbnail-300x300/seahorse.jpg?t=1715340699885",
          "height": 300,
          "resolutionName": "Thumbnail-300x300",
          "sizeInBytes": 10927,
          "width": 199
        }
      ],
      "contentUrl": "/documents/1234/0/seahorse.jpg/4be7d2ff-b9ac-a7ab-1081-537536ece7d9?version=1.0&t=1715340699885&download=true",
      "creator": {
        "additionalName": "",
        "contentType": "UserAccount",
        "familyName": "Test",
        "givenName": "Test",
        "id": 20122,
        "name": "Test Test"
      },
      "customFields": [],
      "dateCreated": "2024-05-10T11:29:14Z",
      "dateModified": "2024-05-10T11:31:39Z",
      "description": "",
      "documentFolderId": 0,
      "documentType": {
        "availableLanguages": [],
        "contentFields": [],
        "description": "",
        "name": "Basic Document"
      },
      "encodingFormat": "image/jpeg",
      "externalReferenceCode": "4be7d2ff-b9ac-a7ab-1081-537536ece7d9",
      "fileExtension": "jpg",
      "fileName": "seahorse.jpg",
      "friendlyUrlPath": "seahorse-friendly-url",
      "id": 32131,
      "keywords": [],
      "numberOfComments": 0,
      "relatedContents": [],
      "renderedContents": [],
      "siteId": 1234,
      "sizeInBytes": 792227,
      "taxonomyCategoryBriefs": [],
      "title": "seahorse"
    }
  ],
  "lastPage": 1,
  "page": 1,
  "pageSize": 20,
  "totalCount": 1
}

応答から、次のようないくつかの情報を抽出できます。

• 文書に対して実行できる操作の一覧。取得、更新、置換、削除などが含まれます。

• ドキュメントの内容にアクセスするためのドキュメントの コンテンツURL。

• 文書の作成者 に関する情報。名前と ID が含まれます。

• dateCreated および dateModified のタイムスタンプは、それぞれドキュメントが作成された日時と最後に変更された日時を示します。

• Liferay DXP 2024.Q2+/Portal GA120+ドキュメントの [friendlyUrlPath](../../../digital-asset-management/uploading-and-managing/configuring-document-urls.md) は、ファイル名またはユーザーが設定したカスタム値になります。

ドキュメントを取得する

次のcURLまたはJavaコマンドを実行すると、Documentのフィールドを取得できます。 1234をDocumentのIDに置き換えてください。

ヒント

Documents_GET_FromSites.[java|sh] を使用して、サイト のドキュメント ID を取得します。

Documents_GET_ById.sh

コマンド：

./Documents_GET_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--user "[e-mail]:learn"

Documents_GET_ById.java

コマンド:

java -classpath .:* -DdocumentId=1234 Documents_GET_ById

コード：

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

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

ドキュメント フィールドは JSON レスポンスに含まれています。

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

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

Documents_GET_ContentValue_ById.sh

コマンド:

./Documents_GET_ContentValue_ById.sh 1234

コード:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}?nestedFields=contentValue&fields=contentValue" \
	--user "[e-mail]: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 は Documents_GET_ById.sh スクリプトの URL と同じです。 ?nestedFields=contentValue部分は、DocumentのnestedFieldsに埋め込まれたcontentValueを要求します。 最後に、&fields=contentValue部分がcontentValueフィールドで絞り込みを行い、コンテンツフィールドのみが返されます。 ただし、サービスのみを呼び出すと、次のようなJSONでラップされたBase64エンコードされたコンテンツが返されます。

{
  "contentValue" : "Y3VybCBcCgktRiAiZmlsZT1ARG9jdW1lbnRfUE9TVF9Ub1NpdGUuc2giIFwKCS1IICJDb250ZW50LVR5cGU6IG11bHRpcGFydC9mb3JtLWRhdGEiIFwKCS1YIFBPU1QgXAoJImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vL2hlYWRsZXNzLWRlbGl2ZXJ5L3YxLjAvc2l0ZXMvJHsxfS9kb2N1bWVudHMiIFwKCS11ICJ0ZXN0QGxpZmVyYXkuY29tOnRlc3Qi"
}

サービス呼び出しに続くルーチンで、エンコードされたコンテンツが処理されます。 sedルーチンとawkルーチンは、Documentコンテンツ値を分離し、trルーチンはそれをデコードします。 アップロードした Documents_POST_ToSites.sh Document に対して返されたデコードされたコンテンツは次のとおりです。

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

Documents_GET_ContentValue_ById.java

Documentコンテンツを取得してデコードするJavaコードは、前のcURLコマンドよりも簡単です。

コマンド：

java -classpath .:* -DdocumentId=1234 Documents_GET_ContentValue_ById

コード：

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

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		new String(
			Base64.getDecoder(
			).decode(
				documentResource.getDocument(
					Long.valueOf(System.getProperty("documentId"))
				).getContentValue()
			)));
}

コードの大部分は Documents_POST_ToSites.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に置き換えてください。

Documents_PATCH_ById.sh

コマンド：

./Documents_PATCH_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--form "document={\"description\": \"Bar\"}" \
	--form "file=@Documents_POST_ToSites.sh" \
	--header "Content-Type: multipart/form-data; boundary=ARBITRARY" \
	--request "PATCH" \
	--user "[e-mail]:learn"

最初のフォームデータ部分（-Fに続く）は、Documentのdescriptionフィールドに新しい値を指定します。 2番目のフォームデータ部分は、アップロードする更新されたファイルを指定します。 なお、どちらも必須ではありません。 ファイルのみ、またはドキュメントのメタデータのみをパッチすることができます。

Documents_PATCH_ById.java

コマンド：

java -classpath .:* -DdocumentId=1234 Documents_PATCH_ById

コード：

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		documentResource.patchDocument(
			Long.valueOf(System.getProperty("documentId")),
			new Document() {
				{
					description = "Bar";
				}
			},
			new HashMap<String, File>() {
				{
					put("file", new File("Document_POST_ToSite.java"));
				}
			}));
}

上記のJavaコードは、DocumentResourceのpatchDocumentメソッドを呼び出し、Document'のID、更新するフィールドを含むDocumentオブジェクト、およびアップロードする更新されたファイルを渡します。

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

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

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

Documents_PUT_ById.sh

コマンド：

./Documents_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=@Documents_PUT_ById.sh" \
	--header "Content-Type: multipart/form-data; boundary=ARBITRARY" \
	--request "PUT" \
	--user "[e-mail]:learn"

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

Documents_PUT_ById.java

コマンド：

java -classpath .:* -DdocumentId=1234 Documents_PUT_ById

コード：

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		documentResource.putDocument(
			Long.valueOf(System.getProperty("documentId")),
			new Document() {
				{
					description = "Goo";
					title = "Documents_PUT_ById.java";
				}
			},
			new HashMap<String, File>() {
				{
					put("file", new File("Documents_PUT_ById.java"));
				}
			}));
}

上記の Java コードは、 DocumentResourceの putDocument メソッドを呼び出し、 Documentの ID、 Document オブジェクト（ Documentの description の値を含む）を渡します。 タイトル フィールド、およびアップロードする代替ファイル。

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

警告

現在の ドキュメントのタイトルを使用しない限り、置換後の ドキュメント に使用する タイトル の値を指定してください。

ドキュメントを削除する

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

Documents_DELETE_ById.sh

コマンド：

./Documents_DELETE_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/documents/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

Documents_DELETE_ById.java

コマンド

java -classpath .:* -DdocumentId=1234 Documents_DELETE_ById

コード：

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

	DocumentResource documentResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

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

Documentは、ドキュメントとメディアから削除されます。

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

次のcURLコマンドとJavaクラスは、その他のDocumentサービスとDocumentFolderサービスの詳細を示しています。

ファイル	説明
Documents_POST_ToDocumentFolders.[java\|sh]	ドキュメントをフォルダに投稿します。
DocumentFolders_GET_ById.[java\|sh]	フォルダのフィールドを一覧表示します。
DocumentFolders_PATCH_ById.[java\|sh]	フォルダとそのフィールドを更新します。
DocumentFolders_POST_ToSites.[java\|sh]	ドキュメントフォルダをサイトに投稿します。
DocumentFolders_PUT_ById.[java\|sh]	フォルダとそのフィールドを完全に置き換えます。
DocumentFolders_DELETE_ById.[java\|sh]	ドキュメントフォルダを削除します。
DocumentFolders_GET_FromSites.[java\|sh]	サイトのフォルダを一覧表示します。

API Explorer には、すべての Document および DocumentFolder サービスとスキーマが一覧表示され、各サービスを試すためのインターフェースがあります。

DocumentResource および DocumentFolderResource Java インターフェイスも参照してください。

関連トピック

• ドキュメントとメディア
• RESTサービスの使用
• APIヘッダーリファレンス
• GraphQL APIの使用