ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

API ビルダー

Liferay DXP 2023.Q4+/Portal GA102+ ベータ機能

重要

この機能は現在、ベータ機能フラグ (LPS-178642) でサポートされています。 API エンドポイントは現在、エンティティのコレクションの取得と作成をサポートしています。

API ビルダーを使用すると、Liferay でカスタム API アプリケーションを簡単に作成できます。ニーズにぴったり合う API スキーマとエンドポイントを作成します。

API ビルダーの使用

各 API アプリケーションは複数のエンドポイントとスキーマを格納できます。これは、Liferay のすぐに使用できる API アプリケーションに似ています。たとえば、 headless-admin-user API アプリケーションには、 アカウント、 組織、 ロール、 ユーザーアカウントなどのエンドポイントが格納されています。

注

API ビルダーはインスタンスレベルのスコープで構成されます。各仮想インスタンスに固有の異なる API アプリケーションを作成します。別のインスタンスで API アプリケーションを再作成するには、データ移行センターを使用します。

API Builderアプリケーションにアクセスするには、

グローバルメニュー () を開き、 コントロールパネル タブを選択して、オブジェクトの下の API ビルダー をクリックします。
カスタム API アプリケーションのリストが表示されます。

各 API アプリケーションのタイトル、URL、説明、最終更新、ステータスが表示されます。

API ビルダーからは、カスタム API アプリケーションを作成および管理することもできます。

カスタム API アプリケーションの作成

API ビルダーで、追加 () をクリックし、要求された情報を入力します。
API のタイトル、URL、および (オプションで) 説明を追加します。

URL には 255 文字の制限があり、数字、文字、ダッシュのみを含めることができます。
作成をクリックします。

カスタム API アプリケーションの管理

API ビルダーで、API アプリケーションの横にある [アクション] メニュー () を使用して、API アプリケーションを管理します。利用可能なオプションを選択してください:

編集: API アプリケーションを編集します。

API アプリケーションの名前をクリックして編集することもできます。

API アプリケーションを編集するときに、Liferay のすぐに使用できる API アプリケーションのように機能する新しいエンドポイントとスキーマを作成できます。

削除: API アプリケーションを削除します。

公開ステータスの変更: 公開ステータスを公開済みから未公開に、またはその逆に変更します。

API アプリケーションは使用する前に公開する必要があります。公開されると、生成された API には、Liferay のすぐに使用できる API と同じ機能セット (ページ区切り、フィルタリング、並べ替えなど) が備わります。

エンドポイントの作成と管理

Liferay DXP 2024.Q1+/ポータル GA112+

API エンドポイントは、リクエストを受け入れる特定の URL の場所です。

エンドポイントを表示、管理、作成するには、

API アプリケーションの編集を開始し、 エンドポイント タブを選択して、カスタムエンドポイントの一覧を表示します。

各エンドポイントのメソッド、URL パス、説明、最終更新が表示されます。

新しいエンドポイントを作成するには、

追加 () をクリックし、詳細を入力します。
作成をクリックします。

エンドポイントを作成したら、[構成] タブを使用して構成できます。

選択した方法に応じてさまざまな構成があります。詳細については、 GET メソッドエンドポイントの作成および POST メソッドエンドポイントの作成を参照してください。

エンドポイントを管理するには、エンドポイントの横にある [アクション] メニュー () を使用して、利用可能なオプションを選択します。

編集: エンドポイントを編集します。

エンドポイントのパスをクリックして編集することもできます。

URL をコピー: エンドポイントの URL をコピーします。

削除: エンドポイントを削除します。

GETメソッドエンドポイントの作成

GET メソッドは、指定されたソースからデータを要求して取得します。 GET メソッドを使用すると、コレクションまたは単一の要素から情報を取得できます (つまり、製品のリストを取得したり、単一の製品から情報を取得したりできます)。

GETメソッドを使用してエンドポイントを作成するには、

エンドポイントを作成中、GET メソッドを選択します。
Liferay DXP 2024.Q1+/Portal GA112+ 取得タイプを選択します。コレクションまたは単一の要素を取得します。

選択したタイプに応じて、パスと構成タブには異なる構成があります。
オブジェクトのスコープに基づいて、エンドポイントの スコープ を選択します。エンドポイントは、インスタンス (会社) またはサイトを対象に設定できます。
エンドポイントで使用するパスを入力します。

Liferay DXP 2024.Q1+/Portal GA112+ 取得タイプとして「単一要素」を選択した場合は、パスにパラメータを追加する必要があります。 (たとえば、単一の製品の情報を取得したい場合は、製品 ID をパラメータとして指定する必要があります)。
(オプション) エンドポイントに説明を追加します。
作成をクリックします。

エンドポイントが作成されたら、追加の設定を行うために構成タブを選択します。 Liferay DXP 2024.Q1+/Portal GA112+ 選択した取得タイプに応じて、異なる設定が表示されます。設定タブで、

レスポンス本文スキーマを選択します。スキーマを作成し、それをエンドポイントに適用して、クライアントの要求に応じて API によって返されるデータの構造と形式を定義します。

Liferay DXP 2024.Q1+/Portal GA112+ 取得タイプとしてコレクションを選択した場合、

エンドポイントに フィルター を適用します。

JSON フィルタリングをエンドポイントに組み込むことができます。たとえば、 filter=lastName eq 'Smith' を使用すると、エンドポイントで姓 Smith を含むエントリをフィルターできます。
エンドポイントに ソート パラメータを適用します。

JSON ソートを組み込むことができます。たとえば、 sort=firstName:asc を使用すると、エントリを名前のアルファベット順に並べ替えることができます。

フィルタリングと並べ替えの詳細については、 API クエリパラメータを参照してください。
公開をクリックします。

GET メソッドと、取得タイプとしてのコレクションを使用してエンドポイントを構成します。

Liferay DXP 2024.Q1+/Portal GA112+ 取得タイプとして「単一要素」を選択した場合、

パスパラメータプロパティを選択します。これは、エンドポイントのパス内の指定されたパラメータにマップされるオブジェクトフィールドです。システムフィールドまたはカスタムフィールドになります (例: id と externalReferenceCode はシステムフィールドであり、 employeeId はカスタムフィールドです)。
(オプション) パスパラメータの説明を追加します。
公開をクリックします。

GET メソッドと、取得タイプとしての単一要素を使用してエンドポイントを構成します。

エンドポイントが作成されると、API エクスプローラーページ http://localhost:8080/o/apiで確認できます。

POSTメソッドエンドポイントの作成

API ビルダーでは、POST メソッドを使用してオブジェクトエントリを作成します。

POSTメソッドを使用してエンドポイントを作成するには、

エンドポイントを作成中、POST メソッドを選択します。
オブジェクトのスコープに基づいて、エンドポイントの スコープ を選択します。エンドポイントは、インスタンス (会社) またはサイトを対象に設定できます。
エンドポイントで使用するパスを入力します。
(オプション) エンドポイントに説明を追加します。
作成をクリックします。

エンドポイントが作成されたら、追加の設定を行うために構成タブを選択します。設定タブで、

リクエストボディスキーマを選択します。スキーマを作成し、それをエンドポイントに適用して、サーバー上でリソースを作成するときにクライアントがリクエスト本文に含める必要があるデータの構造と形式を定義します。

リクエスト本体には、メインオブジェクトのすべての必須プロパティが含まれている必要があり、メインオブジェクトのプロパティのみを含めることができます。

スキーマが選択されていない場合、API エンドポイントは機能せず、API アプリケーションエクスプローラーページには表示されません。

警告

スキーマ内のリレーションシップタイプのプロパティを使用して、エンティティ間のリレーションシップを定義できます。作成されたエンティティは、ID を通じて既存のオブジェクトエントリに関連付けることができます。

関連エンティティをプロパティとして定義することはできますが、POST 要求でこれらの関連エンティティに指定された値は無視されます。したがって、POST メソッドを使用して新しいエントリを作成するときに、関連エンティティを作成することはできません。
(オプション) レスポンス本文スキーマを選択します。スキーマを作成し、それをエンドポイントに適用して、POST 要求に応答してサーバーがクライアントに送り返すデータの構造と形式を定義します。

レスポンス本文スキーマを選択しない場合、API が正常に実行されたときに空のレスポンスが返されます。

エンドポイントが作成されると、API エクスプローラーページ http://localhost:8080/o/apiで確認できます。

API呼び出しによるPOSTメソッドエンドポイントの作成

API 呼び出しを通じて POST エンドポイントを作成する場合は、次の点に注意してください。

Liferay DXP 2024.Q1+/Portal GA112+POSTエンドポイントは、取得タイプとしてsingleElement を持つ必要があります。これにより、投稿されたエントリに関連する情報のみが要求されるようになります。
API 呼び出し中に (` はパスパラメーター) を実行して、POST エンドポイントを作成します。
リクエスト本文スキーマのない POST エンドポイントは機能しません。

POST エンドポイントを作成するために使用できる CURL コマンドの例を次に示します。

curl -X 'POST' \
  'http://localhost:8080/o/headless-builder/endpoints/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'test@liferay.com:learn' \
  -d '{
  "externalReferenceCode": "post-boss-endpoint-erc",
  "description": "This is an endpoint to post a Boss entry",
  "httpMethod": "post",
  "name": "Post Boss",
  "path": "/boss",
  "r_apiApplicationToAPIEndpoints_c_apiApplicationERC": "companies-manager-erc",
  "r_requestAPISchemaToAPIEndpoints_c_apiSchemaERC": "boss-schema-erc",
  "r_responseAPISchemaToAPIEndpoints_c_apiSchemaERC": "boss-schema-erc",
  "retrieveType": "singleElement",
  "scope": "company"
}'

仕組みは以下のとおりです。

curl -X 'POST' \
  'http://localhost:8080/o/headless-builder/endpoints/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'test@liferay.com:learn' \

このコマンドのセクションでは、HTTP リクエストメソッドを POST として指定し、POST リクエストの送信先の URL (http://localhost:8080/o/headless-builder/endpoints/) を定義し、リクエストの Accept および Content-Type ヘッダーを JSON 形式に設定し、指定されたユーザーとパスワードによる基本認証 (-u ‘test@liferay.com:learn') を含めます。

  -d '{
  "externalReferenceCode": "post-boss-endpoint-erc",
  "description": "This is an endpoint to post a Boss entry",
  "httpMethod": "post",
  "name": "Post Boss",
  "path": "/boss",
  "r_apiApplicationToAPIEndpoints_c_apiApplicationERC": "company-manager-erc",
  "r_requestAPISchemaToAPIEndpoints_c_apiSchemaERC": "boss-schema-erc",
  "r_responseAPISchemaToAPIEndpoints_c_apiSchemaERC": "boss-schema-erc",
  "retrieveType": "singleElement",
  "scope": "company"
}'

このセクションでは、リクエスト本体で送信されるデータを指定します。この場合、JSON ペイロードにはさまざまなプロパティが含まれます。

"externalReferenceCode": エンドポイントの外部参照コード (ERC) を定義します。

"説明": エンドポイントの説明を定義します。

"httpMethod": エンドポイントのメソッドを定義します。

"name": エンドポイントの名前を定義します。

"パス": エンドポイントのパスを定義します。

"r_apiApplicationToAPIEndpoints_c_apiApplicationERC": エンドポイントが追加される API アプリケーションを指定するための ERC を指します。

"r_requestAPISchemaToAPIEndpoints_c_apiSchemaERC": エンドポイントのリクエスト本体に使用されるスキーマを指定するための ERC を指します。

"r_responseAPISchemaToAPIEndpoints_c_apiSchemaERC": エンドポイントのレスポンス本文に使用されるスキーマを指定するための ERC を指します。

Liferay DXP 2024.Q1+/Portal GA112+"retrieveType": エンドポイントの取得タイプを定義します。

"スコープ": エンドポイントのスコープを定義します。

スキーマの作成と管理

API スキーマは、API によって返される (または受信される) エンティティを指定します。

スキーマを表示、管理、作成するには、

API アプリケーションの編集を開始し、 スキーマ タブを選択して、スキーマのリストを表示します。

各スキーマの名前、説明、最終更新が表示されます。

新しいスキーマを作成するには、

追加 () をクリックし、詳細を入力します。

名前を選択し、説明を追加し (オプション)、スキーマに関連付けられたオブジェクト定義を選択します。
作成をクリックします。

スキーマが作成されると、[プロパティ] タブを使用してスキーマのプロパティを構成できます。

スキーマを管理するには、スキーマの横にある [アクション] メニュー () を使用して、利用可能なオプションを選択します。

編集: スキーマを編集します。

スキーマの名前をクリックして編集することもできます。

削除: スキーマを削除します。

スキーマプロパティの構成と管理

スキーマのプロパティを構成するには、スキーマの編集を開始し、 [プロパティ] タブを選択します。
スキーマに含めるエンティティを選択します。

スキーマにエンティティを追加するには、エンティティの名前またはその横にある追加アイコン () をクリックします。

Liferay オブジェクトから利用可能なエンティティを選択します。オブジェクトにオブジェクト関係がある場合、それらのオブジェクトのエンティティも選択できます。

検索バーを使用してエンティティを検索できます。
エンティティを管理します。並べ替え、名前変更、除外することができます。

プロパティ名の隣にある移動ハンドルを使用して、プロパティを並べ替えます。

プロパティ名の上にマウスを置くと、編集 () アクションと削除 () アクションが表示されます。

オブジェクトのプロパティ名と説明を編集できます。たとえば、スクリーンショットの Boss オブジェクトの場合、マップされたプロパティと一致するように、 Boss Name を bossNameに変更します。
公開をクリックします。

今後の流れ

サンプル API アプリケーションの構築

Building a Sample API Application