Services
設定可能なエンドポイント、Entity CRUD操作、ユーザー認証を備えたRESTful APIフレームワークを提供することで、外部アプリケーションとDrupalを統合するための標準化されたソリューションです。
services
概要
Servicesモジュールは、DrupalのコンテンツとFunctionalityを外部アプリケーションに公開するための標準化された方法を提供する、Drupal向けの包括的なAPIフレームワークです。Drupal CoreのREST機能を拡張し、RESTful Webサービスを構築するためのより柔軟で機能豊富なソリューションを提供します。
このモジュールでは、サイト管理者が複数のサービスエンドポイントを作成でき、それぞれに独自のURLプレフィックスと設定可能なリソースを持たせることができます。リソースはエンドポイントごとに有効・無効を切り替えることができ、各リソースには独自の認証要件とレスポンスフォーマット設定を持たせることができます。このモジュラーなアプローチにより、異なるAPIバージョンの作成や特定の機能へのアクセス制限が容易になります。
組み込みのサービス定義により、Node、ユーザー、Taxonomyターム、カスタムEntityを含むすべてのDrupal Entityタイプに対するCRUD操作（作成、読み取り、更新、削除）が自動的に提供されます。追加のサービス定義では、ユーザー認証（ログイン/ログアウト）、Taxonomy Vocabularyツリーの取得、Nodeエイリアスの解決が提供されます。このモジュールはAcceptヘッダーベースのコンテンツネゴシエーションもサポートし、安全なAPI操作のためのCSRFトークン保護も含まれています。
Features
- バージョニングやセグメンテーション用のカスタムURLプレフィックスを持つ複数のAPIエンドポイントを作成
- すべてのDrupal Entityタイプに対する自動RESTful CRUD操作（GET、POST、PUT、DELETE）
- ページネーションをサポートするEntityインデックスエンドポイント（start/limitパラメータ）
- 関連するCSSおよびJavaScriptアセットとともにHTMLを返すレンダリングされたEntityビューエンドポイント
- フラッド保護付きのログインとログアウト用ユーザー認証エンドポイント
- 階層的なタームデータ用のTaxonomy Vocabularyツリー取得
- SEOフレンドリーなURL対応のためのパスエイリアスによるNode取得
- Acceptヘッダーベースのコンテンツネゴシエーション（?format=jsonクエリパラメータをサポート）
- リソースごとに設定可能な認証プロバイダー（cookie、basic_auth、oauthなど）
- リソースごとに設定可能なレスポンスフォーマット（json、xml、hal_jsonなど）
- レスポンスキャッシュを無効にするオプション付きのリソースごとのキャッシュ制御
- 安全なクロスサイトリクエスト保護のためのCSRFトークンエンドポイント
- Acceptヘッダーからのフォーマット検出用HTTPミドルウェア
- ServiceDefinitionアノテーションによるカスタムサービス定義を可能にするプラグインベースのアーキテクチャ
Use Cases
ヘッドレスDrupalアプリケーションの構築
Servicesを使用して、React、Vue、Angularで構築されたデカップルドフロントエンド用にすべてのコンテンツをJSON APIとして公開します。'api/v1'にエンドポイントを作成し、必要なコンテンツタイプのEntityリソースを有効にし、保護された操作用にCookieまたはOAuth認証を設定します。
モバイルアプリケーションバックエンド
iOSまたはAndroidアプリケーション用のREST APIを提供します。コンテンツの読み取り用にentity_getとentity_index、認証用にuser_login/user_logout、ユーザー生成コンテンツ用にentity_post/entity_putを有効にします。安全なモバイル認証のためにbasic_authまたはOAuthを使用したJSONフォーマットを使用します。
サードパーティシステム統合
CRM、ERP、その他のビジネスアプリケーションなどの外部システムにDrupalコンテンツを公開します。各統合パートナー向けに特定のリソースと認証要件を持つ専用エンドポイントを作成します。リアルタイムデータ同期にはno_cacheオプションを使用します。
APIバージョニング戦略
'api/v1'と'api/v2'のような複数のエンドポイントを作成して、異なるAPIバージョンを同時にサポートします。バージョンごとに異なるリソースを有効にしたり、異なるフォーマットを設定したりして、APIを進化させながら後方互換性を維持します。
コンテンツシンジケーション
パートナーサイトがコンテンツを取得して表示できるようにします。entity_indexとentity_getリソースを持つ公開エンドポイントを作成し、JSONフォーマットを設定し、公開コンテンツのみへの匿名アクセス用にCookie認証を使用します。
Tips
- ブラウザやcurlなどのツールでのテストを容易にするために、Acceptヘッダーの代わりに?format=jsonクエリパラメータを使用してください
- 利用可能なリソースを視覚的に探索するために、ServicesとともにRESTful Web Services UI（restui）モジュールを有効にしてください
- 開発中はすべてのフォーマットと認証方法を有効にし、本番環境では制限することを検討してください
- entity_viewリソースはアセット付きのレンダリングされたHTMLを返すため、すべてのAPIコンシューマーに適しているとは限らないため、控えめに使用してください
- テスト中にログイン問題が発生した場合は、user.flood設定のフラッド保護設定を監視してください
- セキュリティ管理を簡素化するために、公開リソースと認証されたリソース用に別々のエンドポイントを作成してください
Technical Details
Admin Pages 6
/admin/structure/service_endpoint
設定されたすべてのサービスエンドポイントを一覧表示します。このページからエンドポイントの表示、編集、削除、およびリソース設定へのアクセスができます。各エンドポイント行にはラベル、マシン名、操作リンクが表示されます。
/admin/structure/service_endpoint/add
APIのベースURLとなる新しいサービスエンドポイントを作成します。エンドポイントパスは、このエンドポイントで有効なすべてのリソースのURLプレフィックスになります。
/admin/structure/service_endpoint/{service_endpoint}
既存のサービスエンドポイントのラベルとURLパスを変更します。マシン名は作成後に変更できません。
/admin/structure/service_endpoint/{service_endpoint}/resources
このエンドポイントで有効にするサービス定義（リソース）を設定します。リソースはカテゴリ（Entityタイプ、User、Taxonomyなど）ごとにグループ化されています。各リソースは個別に有効/無効を切り替え、特定の認証とフォーマット設定で構成できます。
/admin/structure/service_endpoint/{service_endpoint}/resource/{plugin_id}
エンドポイント上の特定のリソースの認証方法、レスポンスフォーマット、キャッシュオプションを設定します。
/admin/structure/service_endpoint/settings
すべての新しいリソースに適用されるグローバルデフォルト設定を構成します。個々のリソースはこれらのデフォルトを上書きできます。
権限 3
Hooks 2
hook_entity_form_display_access
Services経由のEntity Form Display操作のアクセス制御を実装します。現在のユーザーが適切な'services {operation} form display access'権限を持っているかチェックします。
hook_service_definition_info_alter
モジュールがサービス定義プラグイン情報を変更できるようにします。ServiceDefinitionPluginManagerがすべてのプラグインを検出した後に呼び出されます。
Troubleshooting 5
/services/session/tokenからCSRFトークンを取得し、すべての安全でないHTTPメソッドのX-CSRF-Tokenヘッダーに含めてください。トークンは認証されたリクエストでも必要です。
要求されたフォーマットがリソースで有効になっていることを確認してください。Acceptヘッダーが設定されたフォーマットと一致することを確認するか、?format=jsonクエリパラメータを使用してください。Serializationモジュールが有効になっていることを確認してください。
認証プロバイダーがDrupalでグローバルに、および特定のリソースで有効になっていることを確認してください。Cookie認証の場合は、セッションCookieを送信していることを確認してください。basic_authの場合は、Basic Authモジュールを有効にしてください。
認証されたユーザーがServices固有の権限に加えて、必要なEntity権限（表示、作成、更新、削除）を持っていることを確認してください。Entityアクセスはdrupalレベルで強制されます。
リソース設定を変更した後、Drupalキャッシュをクリアしてください。ルーティングシステムは変更を反映するために再構築する必要があります。drush crを使用するか、管理UIでキャッシュをクリアしてください。
Security Notes 7
- 認証資格情報とAPIデータを転送中に保護するために、本番環境では常にHTTPSを使用してください
- クロスサイトリクエストフォージェリ攻撃を防ぐために、POST、PUT、DELETE操作にはCSRFトークンが必要です
- Entityアクセス権限が強制されます - ユーザーは権限を持つEntityのみにアクセス/変更できます
- ブルートフォース攻撃を防ぐために、ログインエンドポイントにはフラッド保護が実装されています（user.floodで設定可能）
- セキュリティを向上させるために、公開APIにはCookie認証の代わりにOAuth2の使用を検討してください
- 認証プロバイダー設定を慎重に確認してください - すべてのプロバイダーを有効なままにすると、機密性の高い操作が公開される可能性があります
- manage services権限はAPI設定の完全な制御を付与します - 慎重に割り当ててください