この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

リリース前のコードの文字列の置換

ファイルを組織にリリースする直前に、メタデータソースファイルの文字列を特定の値に自動的に置き換えます。

以下の使用事例のサンプルでは、リリース前に文字列置換を使用する場合のシナリオを説明しています。

NamedCredential には、テストに使用するエンドポイントが含まれています。ただし、ソースを本番組織にリリースするときに、別のエンドポイントを指定したいと考えています。
ExternalDataSource にはリポジトリに保存したくないパスワードが含まれていますが、そのパスワードをメタデータと共にリリースする必要があります。
ほぼ同じコードを複数の組織にリリースします。リリース先の組織に応じて、一部の値を条件付きで置き換えたいと考えています。

ソース形式のファイルは force:source:deploy および force:source:push コマンドで組織にリリースされる直前に ZIP ファイルに変換されますが、このときに文字列が実際に置換されます。文字列置換によって生じた変更は、プロジェクトには書き込まれず、リリースされるファイルにのみ適用されます。

文字列置換の設定

文字列置換を設定するには、sfdx-project.json ファイルに replacements プロパティを追加します。このプロパティは、次を定義するキーから構成された複数のエントリを受け入れます。

置換される文字列を含む 1 つ以上のソースファイル。
置換される文字列。
置換する値。

例を見てその仕組みを確認しましょう。次の sfdx-project.json の例では、ファイル force-app/main/default/classes/myClass.cls のリリース時に、出現する replaceMe という文字列をすべて THE_REPLACEMENT 環境変数の値に置き換えることが指定されています。

1{
2  "packageDirectories": [
3     {
4       "path": "force-app",
5       "default": true
6     }
7  ],
8  "name": "myproj",
9  "replacements": [
10    {
11      "filename": "force-app/main/default/classes/myClass.cls",
12      "stringToReplace": "replaceMe",
13      "replaceWithEnv": "THE_REPLACEMENT"  
14    }
15  ]
16}

replacements プロパティでは、次のキーを指定できます。

ファイルの場所

次のプロパティのいずれかが必要です。

filename: 置換される文字列を含む単一のファイル。
glob: 置換される文字列を含むファイルのコレクション。例: **/classes/*.cls。

置換される文字列

次のプロパティのいずれかが必要です。

stringToReplace: 置換される文字列。
regexToReplace: 置換される文字列パターンを指定する正規表現 (regex)。

置換する値

次のプロパティのいずれかが必要です。

replaceWithEnv: 文字列が環境変数の値に置換されることを指定します。
replaceWithFile: 文字列がファイルの内容に置換されることを指定します。

条件付き処理

次のプロパティは省略可能です。

replaceWhenEnv: 特定の環境変数が特定の値に設定された場合にのみ文字列を置換することを指定します。環境変数を指定するには env プロパティ、文字列の置換をトリガする値を指定するには value プロパティを使用します。

次の構文規則に従います。

Windows の場合でも、ディレクトリには必ずスラッシュ (/) を使用します。
バックスラッシュ (\) は、JSON と正規表現の両方でエスケープ文字として使用されます。このため、エスケープが必要なドットを正規表現を使用して突き合わせるには、regexToReplace の値に 2 つのバックスラッシュを使用する必要があります。
1"regexToReplace" : "\\."
同様に、単一のバックスラッシュを突き合わせるには、3 つのバックスラッシュを指定する必要があります。
1"regexToReplace" : "\\\"

例

次の例は、前の例と似ていますが、2 つのファイルの文字列置換の設定方法を示しています。

1"replacements": [
2  {
3    "filename": "force-app/main/default/classes/FirstApexClass.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithEnv": "THE_REPLACEMENT"
6  },
7  {
8    "filename": "force-app/main/default/classes/SecondApexClass.cls",
9    "stringToReplace": "replaceMe",
10    "replaceWithEnv": "THE_REPLACEMENT"
11  }
12]

次の例は、環境変数 DEPLOY_DESTINATION が存在し、その値が PROD である場合にのみ文字列を置換するように指定する方法を示しています。

1"replacements": [
2  {
3    "filename": "force-app/main/default/classes/myClass.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithEnv": "THE_REPLACEMENT",
6    "replaceWhenEnv": [{
7      "env": "DEPLOY_DESTINATION",
8      "value": "PROD"
9    }]  
10  }
11]

次の例では、force-app/main/default ディレクトリ内の Apex クラスファイルのリリース時に、出現する replaceMe という文字列をすべて replacementFiles/copyright.txt ファイルの内容に置き換えることが指定されています。

1"replacements": [
2  {
3    "glob": "force-app/main/default/classes/*.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithFile": "replacementFiles/copyright.txt"
6  }
7]

リテラルテキストではなくテキストの検索パターンを指定するには、正規表現を使用します。たとえば、次のスニペットに示すように、Apex クラスの XML ファイルには、Salesforce API バージョンを示す <apiVersion> 要素が必ず含まれています。

1<?xml version="1.0" encoding="UTF-8" ?>
2<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
3    <apiVersion>55.0</apiVersion>
4    <status>Active</status>
5</ApexClass>

より新しい API バージョンで Apex クラスをテストしてから、すべてのクラスを実際に更新するとします。次の例は、正規表現を使用して <apiVersion> 要素を検索する方法を示しています。リリース時、この要素は、replacementFiles/latest-api-version.txt ファイルに含まれている <apiVersion>56.0</apiVersion> などの特定の文字列に置き換えられます。

1"replacements": [
2  {
3    "glob": "force-app/main/default/classes/*.xml",
4    "regexToReplace": "<apiVersion>\\d+\\.0</apiVersion>",
5    "replaceWithFile": "replacementFiles/latest-api-version.txt"
6  }
7]

文字列置換のテスト

ファイルを実際に組織にリリースせずに文字列置換をテストするには、次の手順を実行します。

SF_APPLY_REPLACEMENTS_ON_CONVERT 環境変数を true に設定します。
force:source:convert コマンドを実行します。ソースファイルがメタデータ API 形式に変換されます。次に例を示します。
1sfdx force:source:convert --outputdir mdapiOut --sourcepath force-app
出力ディレクトリ (この例では mdapiOut) のファイルを検査し、文字列置換と組織にリリースされる正確な内容を確認します。

テスト中にパスワードや秘密をファイルシステムに書き込むときは、注意してください。また、テスト中に環境変数を設定した場合はリセットし、その環境変数が後で誤って適用されないようにしてください。

警告

ヒントとコツ

(macOS または Linux のみ) replaceWithEnv または replaceWhenEnv プロパティを使用するときは、コマンドを実行する前に環境変数を先頭に追加して、その環境変数を単一のコマンドに適用することを指定できます。次に例を示します。
1THE_REPLACEMENT="some text" DEPLOY_DESTINATION=PROD sfdx force:source:push
パスワードや秘密は、ターミナルの履歴に表示されるため、このような方法で設定するときは注意してください。
警告
設定した文字列置換が多く、その管理が難しい場合は、1 つ以上のファイルの内容を環境に読み込むオープンソースツール (dotenv-cli など) を調べてください。この例の場合、2 つのローカル .env ファイルで設定されている環境変数は、force:source:push コマンドの実行前に読み込まれます。
1dotenv -e .env1 -e .env2 sfdx force:source:push
パスワードや秘密は、.env ファイルでコミットしないでください。
警告
force:source:deploy または force:source:push に --json を指定した場合は、影響を受けたファイルと置換された文字列を示す replacements プロパティが JSON 出力に含まれます。
人間が読み取り可能な出力である force:source:push には、文字列置換情報がデフォルトで表示されます。この情報を削除するには、--quiet を使用してください。これにより、JSON 出力からもこの情報が削除されます。

人間が読み取り可能な出力である force:source:deploy に文字列置換情報を表示するには、--verbose を指定してください。

考慮事項と制限

複数の文字列置換を複数のファイルで行うように設定すると、リリースのパフォーマンスが低下することがあります。可能であれば、filename キーを使用して、開くファイルを 1 つだけにすることを検討してください。glob を使用する必要がある場合は、単一のディレクトリまたはメタデータ型を指定して、開くファイルの数を制限することを試みてください。
たとえば、"glob": "force-app/main/default/classes/*.cls" のように指定すると、特定のディレクトリ内の Apex クラスファイルが検索対象となります。すべてのパッケージディレクトリですべての Apex メタデータファイルを検索する "glob": "**/classes/**” よりも効率的です。
静的リソースで文字列置換を使用するときは注意してください。文字列置換を実行しない場合、Salesforce CLI は、最初にディレクトリを検出したときにすべての静的リソースを単純に zip して、そのままリリースします。大規模な静的リソースディレクトリに対して文字列置換を設定した場合、CLI は、通常より多くのファイルを検査する必要があり、パフォーマンス低下の原因になります。
force:mdapi:deploy コマンドは、文字列置換をサポートしていません。
リリースがタイムアウトになった後、または force:source:deploy で --wait 0 フラグを指定した後、force:source:deploy:report を実行して状況を確認すると、リリースされたファイルには、文字列置換が通常どおり含まれています。ただし、force:source:deploy:report の出力には、force:source:deploy --verbose の場合と同じ文字列置換情報は表示されません。

Salesforce DX 開発者ガイド

リリース前のコードの文字列の置換

文字列置換の設定

例

文字列置換のテスト

ヒントとコツ

考慮事項と制限