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

APIビルダー

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

重要

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

APIビルダーを使用すると、LiferayでカスタムAPIアプリケーションを簡単に作成できます。 お客様のニーズに完全に合致するAPIスキーマとエンドポイントを作成します。

API Builderの使用

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

注記

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

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

  1. グローバルメニュー (Global Menu) を開き、オブジェクトの下にある コントロールパネル → API ビルダー に移動します。

  2. 作成したカスタムAPIアプリケーションの一覧が表示されます。

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

    お客様のカスタムAPIアプリケーションの一覧をご覧ください。

API Builder からは、カスタム API アプリケーションを作成・管理することもできます。

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

  1. API ビルダーで、 追加 (Add button) をクリックし、要求された情報を入力します。

  2. APIのタイトル、URL、そして(任意で)説明を追加してください。

    URLは255文字以内とし、数字、英字、ハイフンのみを含める必要があります。

  3. をクリックしてを作成します。

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

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

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

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

API アプリケーションを編集している間、Liferay の既製の API アプリケーションと同様に機能する新しい エンドポイント と スキーマ を作成できます。

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

公開ステータスの変更: 公開ステータスを公開済みから未公開に変更するか、その逆を行います。

APIアプリケーションは、使用前に公開する必要があります。 公開されたAPIは、Liferayの標準APIと同じ機能セット(ページネーション、フィルタリング、ソートなど)を備えています。

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

Liferay DXP 2024.Q1+/Portal GA112+

APIエンドポイントとは、リクエストを受け付ける特定のURLのことです。

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

  1. APIアプリケーションの編集を開始し、「エンドポイント」タブを選択すると、カスタムエンドポイントの一覧が表示されます。

    各エンドポイントについて、メソッド、URLパス、説明、および最終更新日時が表示されます。

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

  1. をクリックして (Add icon)を追加し、詳細を入力してください。

    「エンドポイント」タブから、GETまたはPOSTメソッドのエンドポイントを作成します。

  2. をクリックしてを作成します。

    エンドポイントが作成されたら、「設定」タブを使用して設定できます。

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

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

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

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

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

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

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

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

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

  1. エンドポイントを作成する際は、GETメソッドを選択してください。

  2. Liferay DXP 2024.Q1+/Portal GA112+「取得タイプ」を選択してください。 コレクションまたは単一の要素を取得します。

    選択したタイプに応じて、パスと構成タブの設定が異なります。

  3. オブジェクトのスコープに基づいて、エンドポイントのスコープ を選択してください。 エンドポイントは、インスタンス(会社)またはサイトに対してスコープを設定できます。

  4. エンドポイントで使用するパス と を入力してください。

    Liferay DXP 2024.Q1+/Portal GA112+ 取得タイプとして「単一要素」を選択した場合は、パスにパラメーターを追加する必要があります。 (例えば、特定の製品の情報が必要な場合は、製品IDをパラメータとして指定する必要があります。)

  5. (オプション)エンドポイントに 説明 を追加します。

  6. をクリックしてを作成します。

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

  1. レスポンスボディスキーマ を選択します。 スキーマ を作成し、それをエンドポイントに適用して、クライアントのリクエストに応じて API から返されるデータの構造と形式を定義します。

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

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

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

  2. エンドポイントに ソート パラメータを適用します。

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

    フィルタリングとソートの詳細については、 APIクエリパラメータ を参照してください。

  3. をクリックして公開 します。

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

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

  1. パス パラメーター プロパティ を選択します。 これは、エンドポイントのパスで指定されたパラメータにマッピングされるオブジェクトフィールドです。 システムフィールドまたはカスタムフィールドのいずれかです(例: id と externalReferenceCode はシステムフィールドで、 employeeId はカスタムフィールドです)。

  2. (任意)パスパラメータの説明を追加します。

  3. をクリックして公開 します。

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

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

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

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

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

  1. エンドポイントを作成する際は、POSTメソッドを選択してください。

  2. オブジェクトのスコープに基づいて、エンドポイントのスコープ を選択してください。 エンドポイントは、インスタンス(会社)またはサイト単位でスコープを設定できます。

  3. エンドポイントで使用するパスを入力してください。

  4. (オプション)エンドポイントに 説明 を追加します。

  5. をクリックしてを作成します。

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

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

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

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

    警告

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

    関連エンティティをプロパティとして定義することは可能ですが、POSTリクエストでこれらの関連エンティティに対して指定された値は無視されます。 したがって、POSTメソッドを使用して新規エントリを作成する場合、関連エンティティを作成することはできません。

  2. (オプション) レスポンスボディスキーマを選択します。 スキーマ を作成し、エンドポイントに適用して、POST リクエストに応答してサーバーがクライアントに送信するデータの構造と形式を定義します。

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

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

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

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

  • Liferay DXP 2024.Q1+/Portal GA112+POST エンドポイントは、取得タイプとしてsingleElement を指定する必要があります。 これにより、投稿されたエントリーに関連する情報のみが要求されることが保証されます。

  • ここで ` は、POST エンドポイントを作成するための API 呼び出し時のパス パラメータです。

  • リクエストボディのスキーマがない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"、
  "説明": "これはボスエントリを投稿するためのエンドポイントです"、
  "httpMethod": "post"、
  "名前": "ボス後"、
  "パス": "/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": "会社"
}'

仕組みを段階的に説明します。

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": "これはボスエントリを投稿するためのエンドポイントです",
  "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"、
  "範囲": "会社"
}'

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

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

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

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

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

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

"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が返す(または受け取る)エンティティを指定します。

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

  1. APIアプリケーションの編集を開始し、「スキーマ」タブを選択すると、スキーマの一覧が表示されます。

    各スキーマについて、名前、説明、および最終更新日が表示されます。

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

  1. をクリックして (Add icon)を追加し、詳細を入力してください。

    名前を選択し、説明を追加(任意)し、スキーマに関連付けられたオブジェクト定義を選択します。

    新しいスキーマを作成するために、オブジェクト定義を選択してください。

  2. をクリックしてを作成します。

    スキーマの作成が完了したら、「プロパティ」タブを使用してそのプロパティを設定できます。

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

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

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

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

スキーマプロパティの設定と管理

  1. スキーマのプロパティを設定するには、スキーマの編集を開始し、「プロパティ」タブを選択します。

  2. スキーマに含めるエンティティを選択してください。

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

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

    検索バーを使ってエンティティを検索できます。

  3. エンティティを管理する。 それらを並べ替えたり、名前を変更したり、除外したりできます。

    プロパティ名の横にある移動ハンドルを使用して、プロパティの順序を変更します。

    プロパティ名にマウスカーソルを合わせると、編集(Edit icon)と削除(Delete icon)のアクションが表示されます。

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

    スキーマに含めるエンティティを選択してください。

  4. をクリックして公開 します。

次のステップ