Transform API

ルートとエンティティを包括的なAPIでJSONに変換して公開するDrupalモジュールです。Drupal開発者がエンティティ、表示モード、テンプレートに関する既存の知識を活用して、HTMLの代わりにJSONを生成できるようにします。

transform_api
29 sites
43
drupal.org
api gui
json API rest web services headless decoupled entity transformation field transformation
Drupal 10 Drupal 11

インストール

Drupal 11, 10 v2.1.4
composer require 'drupal/transform_api:^2.1'

概要

Transform APIは、Drupal開発者がエンティティ、表示モード、テンプレートの知識をHTMLではなくJSON出力に変換するための親しみやすい方法を提供します。Drupalの任意のルートにformat=jsonGETパラメータを付けてアクセスすると、リクエストはTransform APIを経由してルーティングされ、キャッシュ可能性と権限要件を維持しながらJSON出力を生成します。

このモジュールはDrupalコアに類似した主要な概念を導入します：Transforms（テーマテンプレートに相当）、Transformer（rendererサービスに相当）、Transform arrays（render arraysに相当）、Transform modes（表示モードに相当）、Transform blocks（ブロックに相当）。これらは設定可能なリージョンに分割されたグローバルJSON出力を提供します。

このモジュールは、テキスト、ブーリアン、整数、浮動小数点、日時、画像、ファイル、リンク、エンティティ参照など、すべての一般的なDrupalフィールドタイプをサポートするフィールド変換のための広範なプラグインサポートを提供します。Layout Builderと統合し、サブモジュールを通じてレスポンシブ画像をサポートします。

Features

  • URLにformat=jsonパラメータを追加することで、任意のDrupalルートを自動的にJSON変換
  • エンティティをJSONに変換する方法を設定するためのTransform modes（HTMLの表示モードに類似）
  • 設定可能なリージョンに整理された、レスポンスにグローバルJSONデータを追加するためのTransform blocksシステム
  • すべての一般的なDrupalフィールドタイプ（テキスト、ブーリアン、数値、日時、画像、ファイル、リンク、エンティティ参照など）をサポートする包括的なフィールド変換プラグイン
  • 最適なパフォーマンスのためのDrupalのCacheableMetadataを使用した完全なキャッシュサポート
  • Basic Auth、Cookie、OAuth2を含む複数の認証方法
  • さまざまなレベルで変換出力をカスタマイズするためのalter hooks
  • セクションコンポーネントを変換するためのLayout Builder統合
  • 複雑なJSON構造を構成するためのネストされた変換サポート
  • 動的なキャッシュ不可コンテンツを処理するための遅延transformerコールバック

Use Cases

Headless/デカップルドDrupalのセットアップ

Transform APIを使用してJavaScriptフロントエンドフレームワーク（React、Vue、Angular）にJSONコンテンツを提供します。異なる表示コンテキスト（full、teaser、card）用にTransform modesを設定し、Drupalのコンテンツ管理機能を維持しながらフロントエンドが構造化されたJSONデータを消費できるようにします。

モバイルアプリケーションバックエンド

ネイティブモバイルアプリケーション向けにDrupalコンテンツをJSON APIとして公開します。APIはBasic Auth、Cookie、OAuth2認証方法をサポートします。Entity transformsは構造化されたデータを提供し、Transform blocksはナビゲーションメニューやサイト設定などのグローバルデータを追加します。

コンテンツシンジケーション

他のシステムへのシンジケーション用にJSON形式でコンテンツをエクスポートします。Transform modesを使用して、どのフィールドが公開され、どのようにフォーマットされるかを制御します。キャッシュシステムにより、高負荷時でも効率的な配信を保証します。

プログレッシブウェブアプリケーション（PWA）

Transform APIエンドポイントからJSONをフェッチするPWAを構築します。リージョンベースのTransform blocksを使用して、アプリシェルデータ（メニュー、ユーザー情報）をメインコンテンツとは別に提供し、効率的なキャッシュ戦略を可能にします。

APIファーストコンテンツモデリング

API消費を念頭に置いてコンテンツタイプを設計します。バンドルごとにTransform modesを設定して、異なるコンシューマーに対して異なるフィールドセットを公開します。alter hooksを使用して、コンテンツモデルを変更せずに計算フィールドを追加したり出力構造を変更したりします。

Tips

  • 任意のDrupal URLにformat=jsonを追加すると、HTMLの代わりにJSON出力を取得できます
  • 表示モードのようにTransform modesを使用します - 異なるコンテキスト用に'card'、'teaser'、'full'のtransformを作成します
  • Transform blocksは一度評価されてキャッシュされます - 動的なキャッシュ不可コンテンツには#lazy_transformerを使用します
  • より良いキャッシュのために、transform()を直接呼び出すのではなく、transform arrays内でEntityTransformオブジェクトをネストします
  • 汎用のhook_transform_alterの代わりにhook_ENTITYTYPE_transform_alterを使用してエンティティ固有のカスタマイズを行います
  • #collapseコントロールキーは、配列に1つのメンバーしかない場合にネストを減らします - 単一値フィールドに便利です
  • Transform blockリージョンはRequestPathTransformのregionパラメータを使用して個別にクエリできます

Technical Details

Admin Pages 7
Transform modes /admin/structure/display-modes/transform

システムで利用可能なすべてのTransform modesを一覧表示します。Transform modesは、表示モードがHTMLレンダリングを定義するのと同様に、エンティティがJSONに変換される方法を定義します。ユーザーは異なるエンティティタイプのTransform modesを追加、編集、削除できます。

Transform modeを追加 /admin/structure/display-modes/transform/add/{entity_type_id}

特定のエンティティタイプ用の新しいTransform modeを作成します。Transform modeは、このタイプのエンティティがJSONに変換される方法を定義します。

Transform blocks /admin/structure/block/transform

すべての変換されたルートにグローバルJSONデータを提供するTransform blocksを管理します。ブロックは、通常のDrupalブロックと同様に、リージョンに割り当てられ、表示条件を設定できます。

リージョン /admin/structure/block/transform/region

Transform blockリージョンを管理します。リージョンはTransform blocksを整理し、JSONレスポンスで個別にクエリできます。デフォルトリージョンと単一ブロックリージョンを折りたたむかどうかの設定が含まれます。

リージョンを追加 /admin/structure/block/transform/region/add

JSON出力でTransform blocksを整理するための新しいTransform blockリージョンを作成します。

ブロックを設定 /admin/structure/block/transform/add/{plugin_id}

設定、リージョン配置、表示条件を含むTransform blockインスタンスを設定します。

Transformを管理 /admin/structure/types/manage/{bundle}/transform

各Transform modeに対してコンテンツタイプのフィールドがJSONに変換される方法を設定します。各フィールドに使用するフィールド変換プラグインを選択するか、JSON出力からフィールドを非表示にします。

権限 4
Transform blocksを管理

Transform blockの配置、リージョン、設定を管理できます

表示モードを管理

Transform modesの作成と管理を許可（コア権限）

コンテンツにアクセス

Transform APIエンドポイントにアクセスするために必要な権限

[エンティティタイプ]: Transformを管理

エンティティタイプごとに生成される動的権限で、そのエンティティタイプのTransform設定を管理できます

Hooks 5
hook_transform_alter

変換されるすべての変換配列を変更します。transformerによって処理されるすべてのtransformに対して呼び出されます。

hook_HOOK_transform_alter

特定のHOOK識別子を持つ変換配列を変更します。HOOKはtransformのgetAlterIdentifiers()メソッドによって提供され、通常はtransformタイプとエンティティタイプです。

hook_blocks_transform_config_alter

Transform blocksの設定を変更します。プログラムでTransform blocksを追加または変更できます。

hook_field_transform_third_party_settings_form

フィールド変換設定フォームにサードパーティ設定を追加します。

hook_field_transform_settings_summary_alter

UIでフィールドtransformに表示される設定サマリーを変更します。