RESTサービスの使用

Liferay DXPには、ほとんどのアプリケーションでRESTサービスが含まれています。 これらのサービスは完全に OpenAPI に準拠しています。 ここで、それらの消費方法を学びます。 必要なステップはわずか3つです。

1. 使用するサービスを特定します。

2. 必要なデータを含むサイトを特定します。

3. データにアクセスできる資格情報を使用してサービス呼び出しを行います。

この例では、Liferay DXPの新規インストールでDockerイメージを使用しています。

使用するサービスを特定する

RESTサービスを呼び出すには、実行中のLiferay DXPが必要です。

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

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

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

さまざまな API エンドポイントを表示するには、ブラウザを使用して、 [server]:[port]/o/apiにある Liferay の API Explorer にアクセスします。 たとえば、Docker インスタンスでは、次の場所にあります。

http://localhost:8080/o/api

APIはいくつかのカテゴリに分類されます。 この例では、BlogPostingサービスを使用して［Blogs］ウィジェットからブログ投稿を取得していますが、この手順は公開されているどのサービスでも使用できます。

1. ヘッドレス配信 カテゴリを選択します。 このカテゴリには BlogPosting サービスが含まれています。 フィルターを使用してサービスを検索できます。

2. ［ スキーマ表示］ボタンをクリックすると、画面の右側に、このカテゴリのすべてのスキーマのリストが表示されます。

3. スキーマ ブラウザーのブラウザー タブを開いたままにします。 BlogPostingを PUT する場合は、そのスキーマを使用します。

APIスキーマを取得する

オプションとして、 openapi.json 仕様を使用して API のスキーマを確認できます。 [server]:[port]/o/[schema]/v1.0/openapi.json にある特定のスキーマの情報を JSON 応答として取得できます。

たとえば、次の curl コマンドは、 headless-admin-user スキーマの openapi.json を取得し、生の OpenAPI JSON をファイルに保存します。

curl -X GET --user "test@liferay.com:learn" http://localhost:8080/o/headless-admin-user/v1.0/openapi.json > openapi.json

ファイル内の JSON 構造を調べたり解析したりして、必要なスキーマをより深く理解します。

フィルタ可能なフィールドインジケーター

ライフレイ 2025年第2四半期以降

また、 openapi.json 仕様を使用して、エンティティのフィールド (またはオブジェクトの場合はネストされたフィールド) のどれが フィルター パラメーターをサポートしているかを確認することもできます。 スキーマ内の各エンティティには、キー x-filterableを持つ JSON 配列が含まれており、これは、どのフィールド (存在する場合) がフィルタリングをサポートしているかを示します。

たとえば、この x フィルター可能な 配列は、関連付けられているエンティティを dateCreated、 dateModified、 id、または nameでフィルターできることを示します。

"x-filterable" : [ "dateCreated", "dateModified", "id", "name" ]

ヘッドレスアクションキー

各ヘッドレス エンドポイントのメソッドには、URL とは独立してメソッドを識別する ヘッドレス アクション キー があります。 これらのアクション キーは、 データ セット アクションなど、他のアプリケーションのアクションに接続するのに役立ちます。

特定のエンドポイントのアクション キーは、 API エクスプローラーから見つけることができます。 選択したエンドポイント (例: ユーザー アカウント) に対して、GET アクションを実行します。 サーバー応答 JSON には、各アクション キーを含む アクション ブロックが本体に含まれています。

たとえば、 /o/headless-admin-user/ エンドポイント ( /v1.0/user-accounts/{userAccountId} GET メソッドを使用) のアクション キーを示す応答を次に示します。 表示されるアクション キーには、 get-user-account-by-external-reference-code、 put-user-accountなどがあります。

ルートモデルのRESTコンテキストパス

Liferay DXP 2024.Q3+/ポータル GA125+

変更可能なシステム オブジェクトに関連するオブジェクト定義を操作する場合、REST コンテキスト パスにはルート モデルのパスが含まれます。 これはモデル間の階層関係を反映し、API エンドポイントを効率的に整理するのに役立ちます。

一部のルート モデルは共通の名前空間にグループ化されており、その名前空間を表すプレフィックスが前に付く必要があることに注意してください。 このプレフィックスは通常、システムのモジュールまたは機能領域を反映します。

たとえば、 APIApplication ルート モデルは、 API Builder コンポーネントの一部です。 すべてのエンドポイントは、 headless-builder プレフィックスの下にあります。 同様に、コマース関連の機能は headless-commerce-admin プレフィックスの下にあります。

この情報は、 Liferay の API エクスプローラーを使用して見つけることができます。 右上隅の Restアプリケーション （1）をクリックします。 RESTアプリケーションは、対応するパス（該当する場合はプレフィックスを含む）とともに表示されます（2）。 パスは「サーバー」（3）で確認できます。

コンテキストパスの例:

• 接頭辞付き:

  APIApplication はルートモデルであり、 APIEndpoint はその子孫であり、RESTエンドポイントを構成します。

  APIApplicationの場合: /headless-builder/application。

  APIEndpointの場合: /headless-builder/applications/endpoints。

• 接頭辞なし:

  一部の REST API エンドポイントは名前空間にグループ化されていないため、プレフィックスを使用しません。

  例えば、 CommerceReturn はルートモデルで、 CommerceReturnItem はその子孫であり、RESTエンドポイントは

  CommerceReturnの場合: /commerce-returns。

  CommerceReturnItemの場合: /commerce-returns/commerce-return/items。

以下の表は、変更可能なシステム オブジェクトとそれに対応する REST コンテキスト パスを示しています。 この情報を使用して、変更可能なシステム オブジェクトを操作するときに REST コンテキスト パスを構築する方法を理解します。

データを含むサイトを特定する

次に、デフォルトのサイト ID を見つける必要があります。

1. サイト メニュー () を開き、 構成 → サイト設定に移動します。

2. プラットフォームセクションで、［Site Configuration］をクリックします。 Liferay DXPバージョン7.3以前の場合は、一般タブをクリックします。

3. サイト ID の下にあるサイト識別子を見つけます。

   

Liferay DXP 2025.Q1+/Portal GA132+ では、ここでサイトの外部参照コードも見つけることができ、これを使用して REST エンドポイントのサイトを識別することもできます。

データにアクセスできる資格情報を使用してサービス呼び出しを行う

これで、電話をかけるのに必要なものがすべて揃いました。 すべての Web サービスには、要求しているデータへのアクセスを許可する資格情報を使用してアクセスする必要があります。 最も簡単な方法は、資格情報データを URL で渡す Basic 認証です。 この方法は安全ではないため、開発中にのみ使用してください。 本番環境では、アプリケーションは OAuth2経由でユーザーを認証する必要があります。

以下の例では cURLを使用しています。

基本認証を使用してサービスを呼び出す（開発中のみ）

基本認証を使用してサービスを呼び出すには、URLに資格情報を指定します。

curl "http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings/" -u 'test@liferay.com:learn'

OAuth2を使用してサービスを呼び出す

本番環境では、 OAuth2 アプリケーション を作成し、OAuth2 プロセスを使用して認証トークンを取得します。 トークンを取得したら、それをHTTPヘッダーに指定します。

curl -H "Authorization: Bearer d5571ff781dc555415c478872f0755c773fa159" http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings

データの取得と投稿

上記のクエリを実行してすべてのブログ投稿を取得すると、次の投稿がないことがわかります。

{
   "actions" : {
      "subscribe" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/subscribe"
      },
      "unsubscribe" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/unsubscribe"
      },
      "create" : {
         "method" : "POST",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings"
      }
   },
   "items" : [ ],
   "lastPage" : 1,
   "page" : 1,
   "pageSize" : 20,
   "totalCount" : 0
}

まず、ブログ記事を投稿します。

ブログエントリーの投稿

スキーマブラウザーを使用して、ブログエントリを投稿する方法を学ぶことができます。

1. スキーマブラウザを含むブラウザタブに戻ります。 右側にある BlogPosting エントリーをクリックして、そのスキーマを表示します（上記を参照）。 これは BlogPostingデータ構造全体を示していますが、必須フィールドは2つだけです。

   • articleBody
   • headline

2. ブログエントリを投稿する単純なJSONドキュメントを作成します。

   {
      "headline": "Test Blog Entry from REST Services",
      "articleBody": "This article was posted via REST services provided by Liferay DXP."
   }
   

3. リクエストを行います。

   curl --header "Content-Type: application/json" --request POST --data '{ "headline": "Test Blog Entry from REST Services", "articleBody": "This article was posted via REST services provided by Liferay DXP." }' http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings -u test@liferay.com:learn
   

Liferay DXPは、ブログエントリーの完全なJSON表現を返します。

{
   "actions" : {
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
      },
      "replace" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
      }
   },
   "alternativeHeadline" : "",
   "articleBody" : "This article was posted via REST services provided by Liferay DXP.",
   "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Test",
      "givenName" : "Test",
      "id" : 20125,
      "name" : "Test Test",
      "profileURL" : "/web/test"
   },
   "customFields" : [ ],
   "dateCreated" : "2020-03-06T18:02:26Z",
   "dateModified" : "2020-03-06T18:02:27Z",
   "datePublished" : "2020-03-06T18:02:00Z",
   "description" : "",
   "encodingFormat" : "text/html",
   "friendlyUrlPath" : "test-blog-entry-from-rest-services",
   "headline" : "Test Blog Entry from REST Services",
   "id" : 35215,
   "keywords" : [ ],
   "numberOfComments" : 0,
   "relatedContents" : [ ],
   "siteId" : 20122,
   "taxonomyCategories" : [ ]
}

すべてのブログエントリーを取得する

ここで、最初のクエリを繰り返して、投稿したブログエントリが表示されることを確認できます。

curl "http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings/" -u 'test@liferay.com:learn'

ブログエントリのリストが返されます。 追加したエントリは、リスト内の唯一のエントリです。

{
   "actions" : {
      "subscribe" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/subscribe"
      },
      "unsubscribe" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/unsubscribe"
      },
      "create" : {
         "method" : "POST",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings"
      }
   },
   "items" : [ {
      "actions" : {
         "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
         },
         "replace" : {
         "method" : "PUT",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
         },
         "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
         },
         "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
         }
      },
      "alternativeHeadline" : "",
      "articleBody" : "This article was posted via REST services provided by Liferay DXP.",
      "creator" : {
         "additionalName" : "",
         "contentType" : "UserAccount",
         "familyName" : "Test",
         "givenName" : "Test",
         "id" : 20125,
         "name" : "Test Test",
         "profileURL" : "/web/test"
      },
      "customFields" : [ ],
      "dateCreated" : "2020-03-06T18:02:26Z",
      "dateModified" : "2020-03-06T18:02:27Z",
      "datePublished" : "2020-03-06T18:02:00Z",
      "description" : "",
      "encodingFormat" : "text/html",
      "friendlyUrlPath" : "test-blog-entry-from-rest-services",
      "headline" : "Test Blog Entry from REST Services",
      "id" : 35215,
      "keywords" : [ ],
      "numberOfComments" : 0,
      "relatedContents" : [ ],
      "siteId" : 20122,
      "taxonomyCategories" : [ ]
   } ],
   "lastPage" : 1,
   "page" : 1,
   "pageSize" : 20,
   "totalCount" : 1
}

単一のブログエントリーを取得する

リクエストを行うたびに、Liferay DXPは他の考えられるエンドポイントを返します。 そのうちの1つは、IDによって単一のブログエントリを取得することです。 エントリーのIDがわかっている場合は、それを取得できます。

curl "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u test@liferay.com:learn

同じブログエントリーを返します。

ブログエントリーを削除する

IDがわかっている場合は、ブログエントリーを削除することもできます。

curl -X DELETE "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u test@liferay.com:learn

この場合、何も返されませんが、上記のようにリクエストすることで、エントリーが削除されたことを確認できます。

curl "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u test@liferay.com:learn

次に、Liferay DXPは、応答として次のJSONドキュメントを返します。

{
  "status" : "NOT_FOUND",
  "title" : "No BlogsEntry exists with the primary key 35215"
}

　 Liferay DXPのRESTサービスを呼び出す方法を学びました。 上記の例では基本認証を使用していることに注意してください。本番環境では、OAuth2を使用して安全な方法でサービスを呼び出します。

関連トピック

• GraphQL APIの使用
• APIヘッダーリファレンス