ドキュメント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] と testでない場合は、 Documents_POST_ToSites.java ファイルでそれらの値を置き換え、クラスを実行する前に再コンパイルします。

クラスは、ソース ファイル Documents_POST_ToSites.java を Documents and Media にアップロードします。

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

cURLコマンドの検証

Documents_POST_ToSites.sh スクリプトは、cURL を使用して ヘッドレス配信 アプリケーション 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 "[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 を使用します。

ヒント

サイトではなく特定のフォルダーにドキュメントを投稿するには、 postSiteDocumentの代わりに DocumentResource.postDocumentFolderDocument を使用します。 最初のパラメータとしてフォルダ ID を渡します。他の引数は同じままです。

プロジェクトには、依存関係としてcom.liferay.headless.delivery.client.jarファイルが含まれていることに注意してください。 すべてのRESTアプリケーションのクライアントJAR依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注

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

他の例の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
}

レスポンスから、次のようないくつかの情報を抽出できます。

• 取得、更新、置換、削除など、ドキュメントに対して実行できるアクションのリスト。

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

• ドキュメントの 作成者に関する情報（名前と 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に置き換えてください。

ドキュメント_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=@Document_POST_ToSite.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に置き換えてください。

ドキュメント_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=@Document_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の 説明 フィールドと タイトル フィールドの値を含む)、およびアップロードする置換ファイルを渡します。

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

警告

現在の ドキュメントのタイトルを使用しない場合は、置換後の ドキュメントに必要な タイトル 値を必ず指定してください。

ドキュメントを削除する

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

ドキュメント_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"

ドキュメント_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 エクスプローラー には、すべての Document および DocumentFolder サービスとスキーマが一覧表示され、各サービスを試すためのインターフェイスがあります。

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

関連トピック

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