ドキュメントCommerceCommerce on Cloud

シナリオベースの展開

最終更新日： 2026年6月2日

作成対象：

  • {"id":"c66ffd68-0f65-42bb-aa23-b4020f12e0bd"},{"id":"ff6a42d2-313e-452e-93a6-792e4fad9ff8"}

ece-tools 2002.1.0以降では、シナリオベースのデプロイメント機能を使用して、デフォルトのデプロイメント動作をカスタマイズできます。
この機能は、設定で​ シナリオ ​と​ ステップ ​を使用します。

  • シナリオ設定 – 各デプロイメントフックは​ シナリオ ​であり、デプロイメントタスクを完了するためのシーケンスと設定パラメーターを記述するXML設定ファイルです。 シナリオは、.magento.app.yaml ファイルのhooks セクションで設定します。

  • 手順の設定 – 各シナリオでは、デプロイメントタスクを完了するために必要な操作をプログラムによって記述する​ 手順 ​のシーケンスを使用します。 XML ベースのシナリオ設定ファイルで手順を設定します。

クラウド インフラストラクチャ上のAdobe Commerceでは、ece-tools パッケージに既定のシナリオ ​と既定の手順のセットが用意されています。 カスタム XML設定ファイルを作成してデフォルト設定を上書きまたはカスタマイズすることで、デプロイメントの動作をカスタマイズできます。 また、シナリオと手順を使用して、カスタムモジュールからコードを実行することもできます。

ビルドフックとデプロイフックを使用したシナリオの追加

Adobe Commerceの構築とデプロイのシナリオを.magento.app.yaml ファイルのhooks セクションに追加します。 各フックは、各フェーズで実行するシナリオを指定します。 次の例は、デフォルトのシナリオ設定を示しています。

magento.app.yaml フック

hooks:
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml
NOTE
ece-tools 2002.1.xのリリースには、新しい​ フック設定形式があります。 2002.0.x リリース ece-toolsの従来の形式は、引き続きサポートされます。 ただし、シナリオベースのデプロイメント機能を使用するには、新しい形式に更新する必要があります。

シナリオステップの確認

フック設定では、各シナリオは、ビルド、デプロイ、デプロイ後のタスクを実行する手順を含むXML ファイルです。 例えば、scenario/transfer ファイルには、compress-static-content、clear-init-directory、backup-dataの3つの手順が含まれています

scenario/transfer.xml

<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
    <step name="compress-static-content" type="Magento\MagentoCloud\Step\Build\CompressStaticContent" priority="100"/>
    <step name="clear-init-directory" type="Magento\MagentoCloud\Step\Build\ClearInitDirectory" priority="200"/>
    <step name="backup-data" type="Magento\MagentoCloud\Step\Build\BackupData" priority="300">
        <arguments>
            <argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
            <argument name="steps" xsi:type="array">
                <item name="static-content" xsi:type="object" priority="100">Magento\MagentoCloud\Step\Build\BackupData\StaticContent</item>
                <item name="writable-dirs" xsi:type="object"  priority="200">Magento\MagentoCloud\Step\Build\BackupData\WritableDirectories</item>
            </argument>
        </arguments>
    </step>
</scenario>

デフォルトシナリオの拡張

次の例では、デプロイ設定ファイルを追加してフック設定に追加することで、デフォルトのデプロイシナリオを拡張します。

hooks:
  deploy: |
    php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/<vendor-name>/<module-name>/deploy.xml vendor/<vendor-name>/<module-name>/deploy2.xml

デプロイメント時に、カスタムシナリオは、次のルールに基づいてデフォルトのシナリオベースと結合されます。

  • シナリオは、フック定義のシーケンスに基づいて優先順位付けされ、最後のシナリオが最も優先度が高い状態でリストされます。

    この例では、シナリオには次の優先度があります。

    1. vendor/vendor-name/module-name/deploy2.xml
    2. vendor/vendor-name/module-name/deploy.xml
    3. scenario/deploy.xml （既定またはベースライン シナリオ）

  • 優先度の高いシナリオのステップは、他のシナリオの同じ名前のステップを上書きします。 設定に新しい手順が追加されます。 例えば（C → B → A）のように、各シナリオが右から左に優先順位付けされる2つ以上のシナリオに対しても同じルールが適用されます。

デフォルトの手順の削除

skip パラメーターを使用して、既定のシナリオからステップを削除します。

例えば、デフォルトのデプロイシナリオでenable-maintenance-modeとset-production-modeの手順をスキップするには、次の設定を含む設定ファイルを作成します。

vendor/vendor-name/module-name/deploy-custom-mode-config.xml

<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
    <step name="enable-maintenance-mode" skip="true" />
    <step name="set-production-mode"  skip="true" />
</scenario>

カスタム設定ファイルを使用するには、デフォルトの.magento.app.yaml ファイルを更新します。

カスタムデプロイシナリオ付きの.magento.app.yaml

hooks:
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/vendor-name/module-name/deploy-custom-mode-config.xml
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml

デフォルトの手順を置き換える

カスタムシナリオは、デフォルトの手順を置き換えて、カスタム実装を提供できます。 これには、カスタムステップの名前としてデフォルトのステップ名を使用します。

例えば、[ デフォルトのデプロイシナリオ ]では、enable-maintenance-mode手順によってデフォルトのEnableMaintenanceMode PHP スクリプトが実行されます。

<step name="enable-maintenance-mode" type="Magento\MagentoCloud\Step\EnableMaintenanceMode" priority="300"/>

この手順を上書きするには、enable-maintenance-mode ステップの実行時に別のスクリプトを実行するカスタムシナリオ設定ファイルを作成します。

<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<scenario>
    <step name="enable-maintenance-mode" type="VendorName\VendorModule\Step\CustomEnableMaintenanceMode" priority="300"/>
</scenario>

ステップの優先順位を変更する

カスタムシナリオでは、デフォルトの手順の優先順位を変更できます。 次の手順では、enable-maintenance-mode ステップの優先度が300から10に変更され、デプロイシナリオの前にステップが実行されます。

<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
<scenario>
    <step name="enable-maintenance-mode" type="Magento\MagentoCloud\Step\EnableMaintenanceMode" priority="10"/>
</scenario>

この例では、enable-maintenance-mode ステップは、デフォルトのデプロイシナリオの他のすべてのステップよりも優先度が低いため、シナリオの先頭に移動します。

例：デプロイシナリオの拡張

次の例では、次の変更を加えて[ デフォルトのデプロイシナリオ ]をカスタマイズします。

  • remove-deploy-failed-flag ステップをカスタムステップに置き換えます
  • デプロイ前の手順でclean-redis-cache サブステップをスキップします
  • unlock-cron-jobs ステップをスキップします
  • クリティカルバリデータを無効にするには、validate-config ステップをスキップします
  • デプロイ前の新しい手順を追加

vendor/vendor-name/module-name/deploy-extended.xml

<?xml version="1.0"?>
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:ece-tools:config/scenario.xsd">
    <!-- Replace "remove-deploy-failed-flag" step with custom step -->
    <step name="remove-deploy-failed-flag" type="Vendor\ModuleName\Step\Deploy\RemoveDeployFailedFlag" priority="100"/>

    <!-- Skip "clean-redis-cache" sub-step in pre-deploy step -->
    <step name="pre-deploy" type="Magento\MagentoCloud\Step\Deploy\PreDeploy" priority="200">
        <arguments>
            <argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
            <argument name="steps" xsi:type="array">
                <item name="clean-redis-cache" xsi:type="object" skip="true"/>
            </argument>
        </arguments>
    </step>

    <!-- Skip step "unlock-cron-jobs" -->
    <step name="unlock-cron-jobs" skip="true"/>

    <!-- Skip critical validators -->
    <step name="validate-config" type="Magento\MagentoCloud\Step\ValidateConfiguration" priority="300">
        <arguments>
            <argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
            <argument name="validators" xsi:type="array">
                <item name="critical" xsi:type="array">
                    <item name="database-configuration" xsi:type="object" skip="true"/>
                    <item name="search-configuration" xsi:type="object" skip="true"/>
                </item>
            </argument>
        </arguments>
    </step>

    <!-- Add new step into the beginning of the deploy scenario -->
    <step name="new-pre-deploy-step" type="Vendor\ModuleName\Step\Deploy\PreDeploy" priority="10"/>
</scenario>

このスクリプトをプロジェクトで使用するには、Adobe Commerce on cloud infrastructure プロジェクトの.magento.app.yaml ファイルに次の設定を追加します。

hooks:
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml vendor/vendor-name/module-name/deploy-extended.xml
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml
TIP
ece-tools GitHub リポジトリの​ デフォルトのシナリオ ​と​ デフォルトのステップ設定を確認して、プロジェクトのビルド、デプロイ、デプロイ後のタスクに合わせてカスタマイズするシナリオとステップを決定できます。

カスタムモジュールを追加してece-toolsを拡張

ece-tools パッケージには、セマンティック バージョン標準に準拠する既定のAPI インターフェイスが用意されています。 すべてのAPI インターフェイスには​ @api ​注釈が付いています。 カスタムモジュールを作成し、必要に応じてデフォルトコードを変更することで、デフォルトのAPI実装を独自の実装に置き換えることができます。

クラウドインフラストラクチャ上のAdobe Commerceでカスタムモジュールを使用するには、ece-tools パッケージの拡張機能リストにモジュールを登録する必要があります。 登録プロセスは、Adobe Commerceでモジュールを登録する際に使用するプロセスと似ています。

モジュールをece-tools パッケージ​に登録するには：

  1. モジュールのルートでregistration.php ファイルを作成または拡張します。

    code language-php?start_inline=1 
    \Magento\MagentoCloud\ExtensionRegistrar::register('module-name', __DIR__);

  2. モジュール設定ファイルのautoload セクションを更新して、registration.php ファイルを含め、composer.jsonにモジュールファイルを自動ロードします。

    code language-json 
    {
  "name": "vendor/ece-tools-extend",
  "description": "Extension for ece-tools",
  "type": "magento2-component",
  "version": "1.0.0",
  "license": "OSL-3.0",
  "autoload": {
    "files": [ "registration.php" ],
    "psr-4": {
      "Vendor\\EceToolExtend\\": "src/"
    }
  }
}

  3. モジュールにconfig/services.xml ファイルを追加します。 この設定は、ece-tools パッケージからconfig/services.xmlを超えてマージされます。

    code language-xml 
    <?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
    <services>
        <defaults autowire="true" autoconfigure="true" public="true"/>

        <prototype namespace="Vendor\EceToolExtend\" resource="../src/*" exclude="../src/{Test}"/>

        <!-- Use your own implementation of EnvironmentDataInterface -->
        <service id="Magento\MagentoCloud\Config\EnvironmentDataInterface" alias="Vendor\EceToolExtend\Config\CustomEnvironmentData" />
    </services>
</container>

依存関係インジェクションについて詳しくは、Symfony依存関係インジェクション ​を参照してください。

recommendation-more-help
commerce-on-cloud-help-cloud-guide