Dispatcher ツールを使用した検証とデバッグ

最終更新日： 2024年7月15日
  • 適用対象：
  • Experience Manager as a Cloud Service

作成対象：

  • 管理者

はじめに

メモ
クラウドの Dispatcher と Dispatcher ツールのダウンロード方法について詳しくは、クラウドの Dispatcher ページを参照してください。Dispatcher 設定がレガシーモードの場合は、レガシーモードのドキュメントを参照してください。

以降の節では、フレキシブルモードのファイル構造、ローカル検証、デバッグ、レガシーモードからフレキシブルモードへの移行について説明します。

この記事では、プロジェクトの Dispatcher 設定にファイル opt-in/USE_SOURCES_DIRECTLY が含まれていることを前提としています。このファイルは、ファイルの数とサイズに関する制限がなくなり、SDK とランタイムによる設定の検証とデプロイが、レガシーモードと比べて改善されます。

Dispatcher 設定に前述のファイルが含まれていない場合は、レガシーモードからフレキシブルモードへの移行の節で説明されるように、アドビではレガシーモードからフレキシブルモードへ移行することを強くお勧めします。

ファイル構造

プロジェクトの Dispatcher サブフォルダーの構造は次のとおりです。

./
├── conf.d
│   ├── available_vhosts
│   │   ├── my_site.vhost # Created by customer
│   │   └── default.vhost
│   ├── dispatcher_vhost.conf
│   ├── enabled_vhosts
│   │   ├── README
│   │   └── my_site.vhost -> ../available_vhosts/my_site.vhost  # Created by customer
│   └── rewrites
│   │   ├── default_rewrite.rules
│   │   └── rewrite.rules
│   └── variables
|       ├── custom.vars
│       └── global.vars
│── opt-in
│   └── USE_SOURCES_DIRECTLY
└── conf.dispatcher.d
    ├── available_farms
    │   ├── my_farm.farm # Created by customer
    │   └── default.farm
    ├── cache
    │   ├── default_invalidate.any
    │   ├── default_rules.any
    │   ├── marketing_query_parameters.any
    │   └── rules.any
    ├── clientheaders
    │   ├── clientheaders.any
    │   └── default_clientheaders.any
    ├── dispatcher.any
    ├── enabled_farms
    │   ├── README
    │   └── my_farm.farm -> ../available_farms/my_farm.farm  # Created by customer
    ├── filters
    │   ├── default_filters.any
    │   └── filters.any
    ├── renders
    │   └── default_renders.any
    └── virtualhosts
    │   ├── default_virtualhosts.any
    │   └── virtualhosts.any

以下に、変更可能な注目すべきファイルを示します。

カスタマイズ可能なファイル

次のファイルはカスタマイズ可能で、デプロイ時にクラウドインスタンスに転送されます。

  • conf.d/available_vhosts/<CUSTOMER_CHOICE>.vhost

これらのファイルは 1 つ以上持つことができます。ファイルには、ホスト名に一致する <VirtualHost> エントリが含まれ、Apache が異なるルールで各ドメイントラフィックを扱うことができます。ファイルは available_vhosts ディレクトリ内に作成され、enabled_vhosts ディレクトリ内のシンボリックリンクで有効になります。.vhost ファイルから、書き換えや変数などその他のファイルが含まれます。

メモ
フレキシブルモードでは、絶対パスの代わりに相対パスを使用する必要があります。

Dispatcher の無効化に必要な ServerAlias \*.local、localhost および 127.0.0.1 に一致する仮想ホストの少なくとも 1 つが常に使用可能であることを確認してください。サーバーのエイリアス *.adobeaemcloud.net および *.adobeaemcloud.com は、少なくとも 1 つの vhost 設定でも必要であり、アドビの内部プロセスで必要です。

複数の vhost ファイルがあり、正確なホストを一致させたい場合は、次の例に従います。

<VirtualHost *:80>
    ServerName    "example.com"
    # Put names of which domains are used for your published site/content here
    ServerAlias     "*example.com" "\*.local" "localhost" "127.0.0.1" "*.adobeaemcloud.net" "*.adobeaemcloud.com"
    # Use a document root that matches the one in conf.dispatcher.d/default.farm
    DocumentRoot "${DOCROOT}"
    # URI dereferencing algorithm is applied at Sling's level, do not decode parameters here
    AllowEncodedSlashes NoDecode
    # Add header breadcrumbs for help in troubleshooting which vhost file is chosen
    <IfModule mod_headers.c>
        Header add X-Vhost "publish-example-com"
    </IfModule>
  ...
</VirtualHost>
  • conf.d/enabled_vhosts/<CUSTOMER_CHOICE>.vhost

このフォルダーには、conf.dispatcher.d/available_vhosts の下にあるファイルへの相対シンボリックリンクが含まれています。

これらのシンボリックリンクの作成に必要なコマンドの例：

Apple macOS、Linux および WSL

ln -s ../available_vhosts/wknd.vhost wknd.vhost

Microsoft Windows

mklink wknd.vhost ..\available_vhosts\wknd.vhost
メモ
Windows の下でシンボリックリンクを使用する場合は、管理者権限のコマンドプロンプトを Windows Subsystem for Linux で実行するか、シンボリックリンクを作成する権限を割り当てます。
  • conf.d/rewrites/rewrite.rules

ファイルは、.vhost ファイル内からインクルードされます。mod_rewrite には一連の書き換えルールがあります。

  • conf.d/variables/custom.vars

ファイルは、.vhost ファイル内からインクルードされます。Apache 変数用の定義をこの場所に追加できます。

  • conf.d/variables/global.vars

ファイルは、dispatcher_vhost.conf ファイル内からインクルードされます。このファイルで Dispatcher の変更とログレベルの書き換えができます。

  • conf.dispatcher.d/available_farms/<CUSTOMER_CHOICE>.farm

これらのファイルは 1 つ以上持つことができます。ファイルにはホスト名と一致するファームが含まれ、Dispatcher モジュールに異なるルールで各ファームを処理することを可能にします。ファイルは available_farms ディレクトリ内に作成され、enabled_farms ディレクトリ内のシンボリックリンクで有効になります。.farm ファイルから、フィルター、キャッシュルールなどその他のファイルがインクルードされます。

  • conf.dispatcher.d/enabled_farms/<CUSTOMER_CHOICE>.farm

このフォルダーには、conf.dispatcher.d/available_farms の下にあるファイルへの相対シンボリックリンクが含まれています。

これらのシンボリックリンクの作成に必要なコマンドの例：

Apple macOS、Linux および WSL

ln -s ../available_farms/wknd.farm wknd.farm

Microsoft Windows

mklink wknd.farm ..\available_farms\wknd.farm
メモ
Windows の下でシンボリックリンクを使用する場合は、管理者権限のコマンドプロンプトを Windows Subsystem for Linux で実行するか、シンボリックリンクを作成する権限を割り当てます。
  • conf.dispatcher.d/cache/rules.any

ファイルは、.farm ファイル内からインクルードされます。キャッシュの環境設定を指定します。

  • conf.dispatcher.d/clientheaders/clientheaders.any

ファイルは、.farm ファイル内からインクルードされます。バックエンドに転送する必要があるリクエストヘッダーを指定します。

  • conf.dispatcher.d/filters/filters.any

ファイルは、.farm ファイル内からインクルードされます。このルールには、トラフィックを除去してバックエンドに送らないように変更する一連のルールが含まれています。

  • conf.dispatcher.d/virtualhosts/virtualhosts.any

ファイルは、.farm ファイル内からインクルードされます。グロブマッチングで一致するホスト名または URI パスのリストが含まれます。このマッチングにより、リクエストの処理に使用するバックエンドが決まります。

  • opt-in/USE_SOURCES_DIRECTLY

このファイルにより、より柔軟な Dispatcher 設定が可能になり、ファイルの数とサイズに関する以前の制限がなくなります。また、SDK とランタイムによる設定の検証とデプロイも改善されます。

上記のファイルは、以下に示す不変設定ファイルを参照します。クラウド環境では、不変ファイルに対する変更は Dispatcher によって処理されません。

不変設定ファイル

これらのファイルは基本フレームワークの一部であり、標準とベストプラクティスを補強します。ファイルをローカルで変更または削除しても、クラウドインスタンスに転送されず、デプロイメントに影響を与えないので、これらのファイルは不変と見なされます。

上記のファイルは、以下に示す不変ファイルを参照し、その後に追加のステートメントまたはオーバーライドを参照することをお勧めします。Dispatcher 設定をクラウド環境にデプロイすると、ローカル開発で使用されたバージョンに関係なく、不変ファイルの最新バージョンが使用されます。

  • conf.d/available_vhosts/default.vhost

仮想ホストのサンプルが含まれています。お使いの仮想ホストに対して、このファイルのコピーを作成し、カスタマイズしてから conf.d/enabled_vhosts に移動し、カスタマイズしたコピーのシンボリックリンクを作成します。conf.d/enabled_vhosts に default.vhost ファイルを直接コピーしないでください。

Dispatcher の無効化に必要な ServerAlias \*.local、localhost および 127.0.0.1 に一致する仮想ホストの 1 つが常に使用可能であることを確認してください。サーバーのエイリアス *.adobeaemcloud.net および *.adobeaemcloud.com はアドビの内部プロセスで必要です。

  • conf.d/dispatcher_vhost.conf

基本フレームワークの一部です。仮想ホストとグローバル変数のインクルード方法を説明するために使用します。

  • conf.d/rewrites/default_rewrite.rules

デフォルトの書き換えルールは、標準プロジェクトに適しています。カスタマイズが必要な場合は、rewrite.rules を変更します。必要に応じて、カスタマイズの最初にデフォルトのルールを含めることができます。

  • conf.dispatcher.d/available_farms/default.farm

サンプルの Dispatcher ファームが含まれています。ユーザー自身のファームの場合は、このファイルのコピーを作成してカスタマイズし、conf.d/enabled_farms に移動して、カスタマイズしたコピーのシンボリックリンクを作成します。

  • conf.dispatcher.d/cache/default_invalidate.any

基本フレームワークの一部です。起動時に生成されます。このファイルは、定義したすべてのファームの cache/allowedClients セクションにインクルードする​ 必要があります。

  • conf.dispatcher.d/cache/default_rules.any

デフォルトのキャッシュルールです。標準プロジェクトに適しています。カスタマイズが必要な場合は、conf.dispatcher.d/cache/rules.any を変更します。必要に応じて、カスタマイズの最初にデフォルトのルールをインクルードすることができます。

  • conf.dispatcher.d/clientheaders/default_clientheaders.any

バックエンドに転送するデフォルトの要求ヘッダーです。標準プロジェクトに適しています。カスタマイズが必要な場合は、clientheaders.any を変更します。カスタマイズでは、必要に応じて、デフォルトのリクエストヘッダーを最初にインクルードすることができます。

  • conf.dispatcher.d/dispatcher.any

基本フレームワークの一部です。Dispatcher ファームのインクルード方法を説明するために使用します。

  • conf.dispatcher.d/filters/default_filters.any

デフォルトのフィルターです。標準プロジェクトに適しています。カスタマイズが必要な場合は、filters.any を変更します。必要に応じて、カスタマイズの最初にデフォルトのフィルターをインクルードすることができます。

  • conf.dispatcher.d/renders/default_renders.any

基本フレームワークの一部です。このファイルは起動時に生成されます。このファイルは、定義したすべてのファームの renders セクションにインクルードする​ 必要があります。

  • conf.dispatcher.d/virtualhosts/default_virtualhosts.any

デフォルトのホストグロビングです。標準プロジェクトに適しています。カスタマイズが必要な場合は、virtualhosts.any を変更します。すべての ​受信リクエストに一致することから、カスタマイズには、デフォルトのホストグロビングをインクルードしないでください。

サポートされている Apache モジュール

サポートされている Apache モジュールを参照してください。

ローカル検証

メモ
以下の節では、Mac バージョンまたは Linux® バージョンの SDK を使用した場合のコマンドについて説明しますが、Windows バージョンの SDK の場合でも同様の方法で使用できます。

validate.sh スクリプトを次のように使用します。

$ validate.sh src/dispatcher
opt-in USE_SOURCES_DIRECTLY marker file detected
Phase 1: Dispatcher validator
Cloud manager validator 2.0.32
Phase 1 finished
Phase 2: httpd -t validation in docker image
values.csv not found in deployment folder: /Users/foo/src - using files in 'conf.d' and 'conf.dispatcher.d' subfolders directly
processing configuration subfolder: conf.d
processing configuration subfolder: conf.dispatcher.d
Running script /docker_entrypoint.d/10-check-environment.sh
Running script /docker_entrypoint.d/20-create-docroots.sh
Running script /docker_entrypoint.d/30-wait-for-backend.sh
Waiting until localhost is available
localhost resolves to ::1
Running script /docker_entrypoint.d/40-generate-allowed-clients.sh
Running script /docker_entrypoint.d/50-check-expiration.sh
Running script /docker_entrypoint.d/60-check-loglevel.sh
Running script /docker_entrypoint.d/70-check-forwarded-host-secret.sh
# Dispatcher configuration: (/etc/httpd/conf.dispatcher.d/dispatcher.any)
/farms {

...

}
Syntax OK
Phase 2 finished
Phase 3: Immutability check
reading immutable file list from /etc/httpd/immutable.files.txt

...

no immutable file has been changed - check is SUCCESSFUL
Phase 3 finished

スクリプトには次の 3 つのフェーズがあります。

  1. バリデーターを実行します。設定が有効でない場合、スクリプトは失敗します。
  2. Apache httpd を起動できるように、httpd -t コマンドを実行して、構文が正しいかどうかをテストします。テストが成功した場合は、設定をデプロイする準備が整っています。
  3. Dispatcher SDK 設定ファイルのサブセットが変更されておらず（ファイル構造セクションで説明されているように不変であることが前提）、SDK の現在のバージョンと一致していることを確認します。

Cloud Manager によるデプロイ中に、httpd -t の構文チェックも実行され、エラーは Cloud Manager の Build Images step failure ログに記録されます。

メモ
各設定を変更後に validate.sh を実行する代わりの効率的な方法については、自動読み込みと検証のセクションを参照してください。