WebコンテンツAPIの詳細設定

WebコンテンツAPIの詳細設定

Liferay DXP RESTサービスを使用すると、サイトの構造化コンテンツを作成・管理することができます。 構造化コンテンツとは、 Webコンテンツストラクチャーを使用するWebコンテンツ です。 ストラクチャーは、Webコンテンツの記事に含まれる作成者、概要、内容などの情報を定義します。 ストラクチャーにより、必要な情報がコンテンツにすべて含まれるようになります。 ストラクチャーの詳細については、 Webコンテンツストラクチャーを理解するをご覧ください。

ここでは、いくつかの cURL コードサンプルとともに、ビルド済みのLiferay DXP Dockerイメージを使って、ストラクチャーと構造化コンテンツについて学習していきます。 Liferay DXPでのREST APIの使用については、 RESTサービスの使用をご覧ください。

note

WebコンテンツAPI の概要については、WebコンテンツAPIの基本 をご覧ください。

環境のセットアップ

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

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u55。

メールアドレス_tes[email protected]liferay.com_とパスワード_test_を使用して、http://localhost:8080でLiferayにサインインしてください。 プロンプトが表示されたら、パスワードを _learn_に変更します。

次に、 サンプルプロジェクト をダウンロードし、解凍します:

curl https://resources.learn.liferay.com/dxp/latest/ja/content-authoring-and-management/web-content/developer-guide/liferay-m7b2.zip -O
unzip liferay-m7b2.zip
note

これらのスクリプトは基本認証を使用し、テスト用に設計されています。 本番のLiferay DXP環境では、基本認証を使用しないでください。

サイトIDを特定します。

  1. サイトメニュー(Site menu)を開き、 [Configuration] → [Site Settings] に移動します。

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

  3. [Site ID]の下でサイト識別子を見つけます。

    [サイト設定]と[Site Configuration]オプションでサイトIDを特定します。

Liferay DXPに画像を追加する

ここでは、画像を含むさまざまなコンテンツフィールドを含むWebコンテンツの記事を扱います。 サンプルのWebコンテンツ記事にこれらの画像を追加するには、次の手順に従います。

  1. サイトメニュー(Site menu)を開き、 [コンテンツ & データ] → [ドキュメントとメディア] に移動します。
  2. 追加 ボタン(Add)をクリックし、 [複数ファイルのアップロード] を選択します。
  3. foo.pngbar.pnggoo.pngイメージを サンプルプロジェクトフォルダー からドロップエリアにドラッグ&ドロップします。
  4. Publish] をクリックします。

また、 Document_POST_ToSite.shスクリプトを使って、REST APIドキュメントサービスにより、それぞれの画像を別々にポストすることも可能です。

curl \
    -F "[email protected]${1}" \
    -H "Content-Type: multipart/form-data" \
    -X POST \
    "http://localhost:8080/o/headless-delivery/v1.0/sites/${2}/documents" \
    -u "[email protected]:learn"

この例では、 相対画像ファイルパスとサイトIDをパラメーターとして使用して、foo.png の画像を投稿しています。

メソッド サービス エンドポイント
GET ドキュメント /v1.0/sites/${2}/documents
./Document_POST_ImageToSite.sh "../images/foo.png" 20125
パラメーター # 説明
$1 ファイルへの相対パス
$2 siteId

JSON出力には、idフィールドに画像識別子が含まれます。

{
  ...
  "encodingFormat" : "image/png",
  "externalReferenceCode" : "44339",
  "fileExtension" : "png",
  "id" : 44339,
  ...
  "title" : "foo.png"
}

REST APIを使ったドキュメントの操作については、 ドキュメントAPIの基本を参照してください。

サンプルストラクチャーの作成

note

REST APIを使用してプログラム的にWebコンテンツストラクチャーを作成することはできません。

  1. サイトメニュー(Site menu)を開き、 [コンテンツ & データ] → [Webコンテンツ] に移動します。

  2. ストラクチャー] タブを選択し、 追加 ボタン(Add)をクリックします。

  3. 以下の内容で、新しいWebコンテンツストラクチャーを作成します。

    • 名前: Foo
    • フィールド(この順で):TextImageDateSingle Selection
  4. [Single Selection]フィールドには、これらの値を使用します。

    • 第一のオプション値:Foo
    • 第二のオプション値:Goo

    ユーザーインターフェースで新しいWebコンテンツストラクチャーを作成します。

  5. 各ストラクチャー項目をクリックし、そのフィールド参照値を更新します(下表参照)。 フィールド参照値は、サイドバーの[Advanced]セクションにあります。

  6. 保存] をクリックします。

項目 新規フィールド参照値
テキスト TextReference
Image (Automatic Copy) ImageReference
Date (Automatic Copy) DateReference
選択 SingleSelectionReference

ストラクチャー項目フィールド参照値を更新する。

詳細は、ストラクチャーの作成を参照してください。

サンプルテンプレートの作成

note

REST APIを使用してプログラム的にWeb コンテンツ テンプレートを作成することはできません。

ストラクチャーの imageフィールドを含むWebコンテンツテンプレートを作成します。

  1. サイトメニュー(Site menu)を開き、 [コンテンツ & データ] → [Webコンテンツ] に移動します。

  2. Templates] タブを選択し、 追加 ボタン(Add)をクリックします。

  3. テンプレート名として Foo をタイプします。

  4. [Properties]サイドパネルから、[Structure]フィールドの横にある 追加 ボタン(Add)をクリックします。

    ストラクチャー項目の横にある追加ボタンをクリックすると、テンプレートがストラクチャーにリンクされます。

  5. Foo Webコンテンツストラクチャーを 前のセクション から選択します。

  6. FreeMarkerエディターに含まれるデフォルトの<#-- -->ブロックコメントを削除します。

  7. サイドバーで、 Elements(Elements)をクリックします。

  8. [Fields]グループで、 [Text] 、 [Image] 、 [Date] 、 [Single Selection] フィールドをクリックし、自分のテンプレートに追加します。 FreeMarkerエディターで、各フィールドが新しい行で始まることを確認します。

    FreeMarkerエディターでWebコンテンツテンプレートのフィールドを編集します。

  9. 保存] をクリックします。

ストラクチャーのimageフィールドを含まない第二のWebコンテンツテンプレートを作成します。

  1. [Templates]タブで、 アクション ボタン(Actions)をクリックし、 [Copy] を選択します。

    Actions メニューを使用して、最初のテンプレートをコピーします。

  2. テンプレートの名前を Goo に更新し、 [Copy] をクリックします。

    テンプレートの名前を"Goo"に更新します。

  3. [テンプレート]タブで、新規の [Goo] テンプレートをクリックします。

  4. テンプレートエディターで、FreeMarkerスクリプトから画像情報 <#if (ImageReference.getData())></#if>を削除します。

    テンプレートから画像情報を削除します。

  5. 保存] をクリックします。

詳しくは、 Webコンテンツテンプレートの作成を参照してください。

WebコンテンツストラクチャーIDの取得

既存のすべてのサイト構造を返すには、 ContentStructures_GET_FromSite.shスクリプトを使用します。 このスクリプトでは、ContentStructureサービスがGET HTTPメソッドおよび サイトID パラメーターと共に使用されています。

メソッド サービス エンドポイント
GET ContentStructure /v1.0/sites/${1}/content-structures
./ContentStructures_GET_FromSite.sh 20125
パラメーター # 説明
$1 siteId

このコードはスクリプトのJSON出力を示しており、Webコンテンツストラクチャーid ("id" : 43563) と name ("name" : "Foo")が確認できることを示しています。 contentStructureFieldsセクションでは、ストラクチャー項目について説明しています。 このストラクチャーは、TextReferenceImageReferenceDateReferenceSingleSelectionReferenceという4種類のフィールドを含んでいます。

{
  "actions" : { },
  "facets" : [ ],
  "items" : [ {
    "availableLanguages" : [ "en-US" ],
    "contentStructureFields" : [ {
      "dataType" : "string",
      "inputControl" : "text",
      "label" : "Text",
      "localizable" : true,
      "multiple" : false,
      "name" : "TextReference",
      "nestedContentStructureFields" : [ ],
      "options" : [ ],
      "predefinedValue" : "",
      "repeatable" : false,
      "required" : false,
      "showLabel" : true
    }, {
      "dataType" : "image",
      "label" : "Image",
      "localizable" : true,
      "multiple" : false,
      "name" : "ImageReference",
      "nestedContentStructureFields" : [ ],
      "options" : [ ],
      "predefinedValue" : "{}",
      "repeatable" : false,
      "required" : false,
      "showLabel" : true
    }, {
      "dataType" : "date",
      "label" : "Date",
      "localizable" : true,
      "multiple" : false,
      "name" : "DateReference",
      "nestedContentStructureFields" : [ ],
      "options" : [ ],
      "predefinedValue" : "",
      "repeatable" : false,
      "required" : false,
      "showLabel" : true
    }, {
      "dataType" : "string",
      "inputControl" : "radio",
      "label" : "Single Selection",
      "localizable" : true,
      "multiple" : false,
      "name" : "SingleSelectionReference",
      "nestedContentStructureFields" : [ ],
      "options" : [ {
        "label" : "Foo",
        "value" : "Option13142925"
      }, {
        "label" : "Goo",
        "value" : "Option50805674"
      } ],
      "predefinedValue" : "[]",
      "repeatable" : false,
      "required" : false,
      "showLabel" : true
    } ],
    "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Bowman",
      "givenName" : "David",
      "id" : 20129,
      "name" : "David Bowman"
    },
    "dateCreated" : "2021-08-25T07:52:46Z",
    "dateModified" : "2021-08-25T08:01:58Z",
    "description" : "",
    "id" : 43563,
    "name" : "Foo",
    "siteId" : 20125
  } ],
  "lastPage" : 1,
  "page" : 1,
  "pageSize" : 20,
  "totalCount" : 1
}

画像IDの取得

以前投稿した 画像のIDを取得するには、Documents_GET_FromSite.shスクリプトを使用します。 このスクリプトでは、 Documentサービスが、 GET HTTPメソッドおよび サイトID パラメーターと共に使用されています。

メソッド サービス エンドポイント
GET ドキュメント /v1.0/sites/${1}/documents
./Documents_GET_FromSite.sh 20125
パラメーター # 説明
$1 siteId

Webコンテンツテンプレートの取得

ContentTemplates_GET_FromSiteスクリプトを使用して、サイトのすべてのテンプレートを取得します。 このスクリプトでは、ContentTemplate サービスが、 GET HTTPメソッドと サイトID パラメーターと共に使用されています。

メソッド サービス エンドポイント
GET ContentTemplate /v1.0/sites/${1}/content-templates
./ContentTemplates_GET_FromSite.sh 20125
パラメーター # 説明
$1 siteId

以下は、このスクリプトからのJSON出力です。 以下の情報を参照してください:

  • このJSON出力には、2種類のテンプレートがあります。 "name": "Foo""name": "Goo".
  • contentStructureIdフィールドは、テンプレートにリンクされているWebコンテンツストラクチャーを示します。
  • templateScriptには、programmingLanguageで指定された言語のスクリプトが含まれていません。 この例では、FreeMarkerが言語となります。
  • FooテンプレートのtemplateScriptフィールドには、<#if (ImageReference.getData())></#if>で参照される画像フィールドが含まれています。 GooテンプレートのtemplateScriptフィールドには、この参照は含まれていません。
{
  "actions" : {
    "get" : {
      "method" : "GET",
      "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/20125/content-templates"
    }
  },
  "facets" : [ ],
  "items" : [ {
    "actions" : {
      "get" : {
        "method" : "GET",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/20125/content-templates/{contentTemplateId}"
      }
    },
    "availableLanguages" : [ "en-US" ],
    "contentStructureId" : 43563,
    "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Bowman",
      "givenName" : "David",
      "id" : 20129,
      "name" : "David Bowman"
    },
    "dateCreated" : "2021-08-25T13:39:20Z",
    "dateModified" : "2021-08-25T13:39:20Z",
    "description" : "",
    "id" : "43823",
    "name" : "Foo",
    "programmingLanguage" : "ftl",
    "siteId" : 20125,
    "templateScript" : "<#if (TextReference.getData())??>\n\t${TextReference.getData()}\n</#if>\n<#if (ImageReference.getData())?? && ImageReference.getData() != \"\">\n\t<img alt=\"${ImageReference.getAttribute(\"alt\")}\" data-fileentryid=\"${ImageReference.getAttribute(\"fileEntryId\")}\" src=\"${ImageReference.getData()}\" />\n</#if>\n<#assign DateReference_Data = getterUtil.getString(DateReference.getData())>\n\n<#if validator.isNotNull(DateReference_Data)>\n\t<#assign DateReference_DateObj = dateUtil.parseDate(\"yyyy-MM-dd\", DateReference_Data, locale)>\n\n\t${dateUtil.getDate(DateReference_DateObj, \"dd MMM yyyy - HH:mm:ss\", locale)}\n</#if>\n<#if (SingleSelectionReference.getData())??>\n\t${SingleSelectionReference.getData()}\n</#if>"
  }, {
    "actions" : {
      "get" : {
        "method" : "GET",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/20125/content-templates/{contentTemplateId}"
      }
    },
    "availableLanguages" : [ "en-US" ],
    "contentStructureId" : 43563,
    "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Bowman",
      "givenName" : "David",
      "id" : 20129,
      "name" : "David Bowman"
    },
    "dateCreated" : "2021-08-26T10:10:22Z",
    "dateModified" : "2021-08-26T14:08:53Z",
    "description" : "",
    "id" : "44177",
    "name" : "Goo",
    "programmingLanguage" : "ftl",
    "siteId" : 20125,
    "templateScript" : "<#if (TextReference.getData())??>\n\t${TextReference.getData()}\n</#if>\n<#assign DateReference_Data = getterUtil.getString(DateReference.getData())>\n\n<#if validator.isNotNull(DateReference_Data)>\n\t<#assign DateReference_DateObj = dateUtil.parseDate(\"yyyy-MM-dd\", DateReference_Data, locale)>\n\n\t${dateUtil.getDate(DateReference_DateObj, \"dd MMM yyyy - HH:mm:ss\", locale)}\n</#if>\n<#if (SingleSelectionReference.getData())??>\n\t${SingleSelectionReference.getData()}\n</#if>"
  } ],
  "lastPage" : 1,
  "page" : 1,
  "pageSize" : 20,
  "totalCount" : 2
}

IDによるWebコンテンツテンプレートの取得

上記の スクリプトは、サイトのすべてのWebコンテンツテンプレートを収集しますが、そのIDを参照することで特定のテンプレートに関する情報を取得することができます。 このためには、 ContentTemplate_GET_ById.shcURLスクリプトを使用してください。 このスクリプトは、サイトIDとテンプレートIDのパラメーターを使用します。

メソッド サービス エンドポイント
GET ContentTemplate /v1.0/sites/${1}/content-templates/${2}
./ContentTemplate_GET_ById.sh 20125 43823
パラメーター # 説明
$1 siteId
$2 テンプレートid

Webコンテンツの記事を投稿する

StructuredContent_POST_ToSite.shcURLスクリプトは、POSTHTTPメソッドと 以前に作成した サンプルストラクチャーを使って新規Webコンテンツの記事を作成します。 このスクリプトでは、 サイトID 、ストラクチャーID、 foo.pngの 画像ID をパラメーターとして使用しています。

メソッド サービス エンドポイント
PUT StructuredContent /v1.0/sites/{siteId}/structured-contents
./StructuredContent_POST_ToSite.sh 20125 43563 43795

cURLスクリプトのパラメーター:

パラメーター # 説明
$1 siteId
$2 contentStructureId
$3 画像id

Liferay DXPで新規Webコンテンツの記事を見つけるには、 サイトメニュー(Site menu)を開いて、 [コンテンツ & データ] → [Webコンテンツ] に移動します。

POST HTTPメソッドによるWebコンテンツ記事。

以下は、このスクリプトからのJSON出力です。 スクリプトは以下を投稿します。

  • "title" : "Able"という名前の新規Webコンテンツの記事
  • 記事の本文を定義している下記4つのcontentFieldsの値
    • TextReference内の文字列。
    • ImageReference内の画像。
    • DateReference内の日付情報。
    • SingleSelectionReference内のラジオボタンコントロール。
{
  "actions" : {
    ...
  },
  "availableLanguages" : [ "en-US" ],
  "contentFields" : [ {
    "contentFieldValue" : {
      "data" : "This text describes Foo."
    },
    "dataType" : "string",
    "inputControl" : "text",
    "label" : "Text",
    "name" : "TextReference",
    "nestedContentFields" : [ ],
    "repeatable" : false
  }, {
    "contentFieldValue" : {
      "image" : {
        "contentType" : "Document",
        "contentUrl" : "/documents/20125/0/foo.png/50956e56-9571-8f73-ae6e-9fca20fe0e3a?t=1629897455431",
        "description" : "This text describes Foo's image.",
        "encodingFormat" : "image/png",
        "fileExtension" : "png",
        "id" : 43795,
        "sizeInBytes" : 6232,
        "title" : "Foo"
      }
    },
    "dataType" : "image",
    "label" : "Image",
    "name" : "ImageReference",
    "nestedContentFields" : [ ],
    "repeatable" : false
  }, {
    "contentFieldValue" : {
      "data" : "2021-08-30T00:00:00Z"
    },
    "dataType" : "date",
    "label" : "Date",
    "name" : "DateReference",
    "nestedContentFields" : [ ],
    "repeatable" : false
  }, {
    "contentFieldValue" : {
      "data" : "Foo"
    },
    "dataType" : "string",
    "inputControl" : "radio",
    "label" : "Single Selection",
    "name" : "SingleSelectionReference",
    "nestedContentFields" : [ ],
    "repeatable" : false
  } ],
  "contentStructureId" : 43563,
  "creator" : {
    "additionalName" : "",
    "contentType" : "UserAccount",
    "familyName" : "Bowman",
    "givenName" : "David",
    "id" : 20129,
    "name" : "David Bowman"
  },
  "customFields" : [ ],
  "dateCreated" : "2021-08-26T06:14:06Z",
  "dateModified" : "2021-08-26T06:14:06Z",
  "datePublished" : "2021-08-26T06:14:00Z",
  "description" : "",
  "externalReferenceCode" : "43847",
  "friendlyUrlPath" : "able",
  "id" : 43849,
  "key" : "43847",
  "keywords" : [ ],
  "numberOfComments" : 0,
  "relatedContents" : [ ],
  "renderedContents" : [ {
    "contentTemplateId" : "43823",
    "contentTemplateName" : "Foo",
    "markedAsDefault" : true,
    "renderedContentURL" : "http://localhost:8080/o/headless-delivery/v1.0/structured-contents/43849/rendered-content/43823"
  }, {
    "contentTemplateId" : "43868",
    "contentTemplateName" : "Goo",
    "markedAsDefault" : false,
    "renderedContentURL" : "http://localhost:8080/o/headless-delivery/v1.0/structured-contents/44060/rendered-content/43868"
  } ],
  "siteId" : 20125,
  "subscribed" : false,
  "taxonomyCategoryBriefs" : [ ],
  "title" : "Able",
  "uuid" : "01ace059-814a-132d-d46d-21737ef2ec53"
}

特定のテンプレートでレンダリングされたWebコンテンツの記事を取得する

Webコンテンツの記事は、特定のテンプレートにリンクされているわけではありません。 テンプレートは、Webコンテンツのレンダリング方法を定義するもので、同じWebコンテンツに異なるテンプレートを使用することができます。 詳細については、 Webコンテンツストラクチャーを理解するをご覧ください。

tip

Webコンテンツの記事は特定のテンプレートにリンクされているわけではないので、新しい記事をPOSTするときにテンプレートを指定することはできません(HTTPのPOSTメソッドはテンプレートを記述したrenderedContentsセクションを無視します)。

スクリプト./StructuredContentRendered_GET_ById.shは、選択したWebコンテンツとテンプレートを使ってWebコンテンツをレンダリングします。 このスクリプトでは、GETHTTPメソッドを StructuredContentサービスで使用します。

メソッド サービス エンドポイント
PUT StructuredContent /v1.0/structured-contents/${1}/rendered-content/${2}
./StructuredContentRendered_GET_ById.sh 43849 43868

以下は、 imageフィールドを持つテンプレートを使用したスクリプトの出力です。

Foo<picture data-fileentryid="43795"><source media="(max-width:300px)" srcset="http://localhost:8080/o/adaptive-media/image/43795/Thumbnail-300x300/foo.png?t=1629897455431, /o/adaptive-media/image/43795/Preview-1000x0/foo.png?t=1629897455431 2x" /><source media="(max-width:600px) and (min-width:300px)" srcset="http://localhost:8080/o/adaptive-media/image/43795/Preview-1000x0/foo.png?t=1629897455431" /><img alt="Foo alt-image description" data-fileentryid="43795" src="http://localhost:8080/documents/20125/0/foo.png/50956e56-9571-8f73-ae6e-9fca20fe0e3a?t=1629897455431" /></picture>30 Aug 2021 - 00:00:00Option1314292

代わりに画像フィールドを含まないWebコンテンツテンプレートを指定した場合、<picture></picture>情報は出力でレンダリングされません。 以下は、 imageフィールドを含まないテンプレートを使用したスクリプトの出力です。

./StructuredContentRendered_GET_ById.sh 43849 43823
Foo30 Aug 2021 - 00:00:00Option13142925

cURLスクリプトのパラメーター:

パラメーター # 説明
$1 構造化コンテンツid
$2 contentTemplateId

Webコンテンツの記事を配置する

PUTHTTPメソッドで、 StructuredContentサービスを使って、オリジナルのWebコンテンツ情報を置き換えることができます。 StructuredContent_PUT_ByIdスクリプトはWebコンテンツとストラクチャー識別子を使って、記事の名前をBakerと置き換え、さらに記事の内容をBarからGooに置き換えます。

メソッド サービス エンドポイント
PUT StructuredContent /v1.0/structured-contents/{structuredContentId}
./StructuredContent_PUT_ById.sh 43849 43563 43805

cURLスクリプトのパラメーター:

パラメーター # 説明
$1 構造化コンテンツid
$2 contentStructureId
$3 画像id

追加情報