Salesforce CLI 設定ガイド
jSalesforce CLI の API バージョンとソース API バージョンのしくみ
単純化のために、このトピックでは apiVersion と sourceApiVersion と表記します。最初にそれぞれの意味を定義します。
- apiVersion
-
apiVersion 値は HTTPS の要求や応答の形式を決定します。
具体的には、apiVersion は HTTPS の要求や応答の処理に使用されるメタデータ API のコアバージョンを指します。メタデータソースを組織にリリースする場合、Salesforce CLI は Connection オブジェクトに apiVersion 値を設定し、HTTPS 要求の URL を SOAP API または REST API で使用します。現在、メタデータ取得用の REST API がないため、Salesforce CLI では Connection オブジェクトに設定された apiVersion の値を使用して SOAP エンドポイントの URL が作成されます。
- sourceApiVersion
-
sourceApiVersion の値は HTTPS の要求や応答でのメタデータの形式を決定します。
Salesforce CLI は、マニフェストファイル (package.xml) の <version> 要素を設定するときに sourceApiVersion 値を使用します。package.xml ファイルは、リリースまたは取得時に、それぞれ HTTPS 要求または応答に組み込まれます。
次の 2 つの例は、2 つの設定がどのように連動するかを示しています。
- 取得: たとえば、Summer '22 リリース (API バージョン 55.0) でメタデータ型に新しい項目が追加されたとします。sourceApiVersion を 54.0 に設定してから project retrieve start コマンドを実行すると、取得したメタデータにはこの新しい項目が追加されません。ただし、sourceApiVersion を 55.0 に設定して同じように取得すると、新しい項目を含むメタデータが返されます。
- リリース: 同様に API バージョン 55.0 でメタデータ型に新しい項目が追加されたとします。sourceApiVersion を 54.0 に設定し、この新しい項目を含むローカルメタデータファイルをリリースしようとすると、リリースに失敗します。新しい項目でメタデータを正常にリリースするには、sourceApiVersion を 55.0 以上に設定する必要があります。
Salesforce CLI 設定の優先順位
apiVersion と sourceApiVersion を設定する方法は複数あります。また、これらの方法を明示的に指定していない場合は Salesforce CLI が複数の方法のいずれかでそれらの値を決定します。次の優先順位のリストを参照して、実際の環境での 2 つの設定の優先度を判断してください。リストの上位の設定が下位の設定よりも優先されます。この優先順位がメタデータのリリースと取得にどのように影響するかについては、このセクションの後の例を参照してください。
- apiVersion: 優先順位
-
- --api-version コマンドフラグ。
- SF_ORG_API_VERSION 環境変数。
- org-api-version ローカル設定変数。
- org-api-version グローバル設定変数。
- 対象組織でサポートされている最高の API バージョン。
- sourceApiVersion: 優先順位
-
- マニフェストファイル (package.xml) 内の <version> 要素。
- sfdx-project.json ファイルの sourceApiVersion プロパティ。
- --api-version コマンドフラグ。
- SF_ORG_API_VERSION 環境変数。
- org-api-version ローカル設定変数。
- org-api-version グローバル設定変数。
- 対象組織でサポートされている最高の API バージョン。
設定の優先順位を表すリリースの例
以下の例では、さまざまなユースケースを想定し、リリース後の結果を示しています。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。
-
コマンド: sf project deploy start --source-dir force-app
結果: Salesforce CLI は、API バージョン 55.0 のエンドポイントにリリース要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 54.0 です。これは、リリースされるメタデータソースが API バージョン 54.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。
-
コマンド: sf project deploy start --source-dir force-app --api-version=56.0
結果: Salesforce CLI は、API バージョン 56.0 のエンドポイントにリリース要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 54.0 です。これは、リリースされるメタデータソースが API バージョン 54.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。SF_ORG_API_VERSION 環境変数は 56.0 に設定されます。sourceApiVersion は sfdx-project.json では設定されていません。
-
コマンド: sf project deploy start --source-dir force-app
結果: Salesforce CLI は、API バージョン 56.0 のエンドポイントにリリース要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 56.0 です。これは、リリースされるメタデータソースが API バージョン 56.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。マニフェストファイルの <version> 要素は、53.0 に設定されます。
-
コマンド: sf project deploy start --manifest ./package.xml
結果: Salesforce CLI は、API バージョン 55.0 のエンドポイントにリリース要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 53.0 です。これは、リリースされるメタデータソースが API バージョン 53.0 の形態であることを意味します。
- 設定: なし。組織でサポートされる API の最大バージョンは 56.0 です。
-
コマンド: sf project deploy start --source-dir force-app
結果: Salesforce CLI は、API バージョン 56.0 のエンドポイントにリリース要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 56.0 です。これは、リリースされるメタデータソースが API バージョン 56.0 の形態であることを意味します。
設定の優先順位を表す取得の例
以下の例では、さまざまなユースケースを想定し、取得後の結果を示しています。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。
-
コマンド: sf project retrieve start --source-dir force-app
結果: Salesforce CLI は、API バージョン 55.0 の SOAP エンドポイントに取得要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 54.0 です。これは、取得されるメタデータソースが API バージョン 54.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。
-
コマンド: sf project retrieve start --source-dir force-app --api-version 56.0
結果: Salesforce CLI は、API バージョン 56.0 の SOAP エンドポイントに取得要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 54.0 です。これは、取得されるメタデータソースが API バージョン 54.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。SF_ORG_API_VERSION 環境変数は 56.0 に設定されます。sourceApiVersion は sfdx-project.json では設定されていません。
-
コマンド: sf project retrieve start --source-dir force-app
結果: Salesforce CLI は、API バージョン 56.0 の SOAP エンドポイントに取得要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 56.0 です。これは、取得されるメタデータソースが API バージョン 56.0 の形態であることを意味します。
- 設定: apiVersion はローカル設定変数 (sf config set org-api-version=55.0) を使用して 55.0 に設定されます。sourceApiVersion は、sfdx-project.json ファイルで 54.0 に設定されています。マニフェストファイルの <version> 要素は、53.0 に設定されます。
-
コマンド: sf project retrieve start --manifest ./package.xml
結果: Salesforce CLI は、API バージョン 55.0 の SOAP エンドポイントに取得要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 53.0 です。これは、取得されるメタデータソースが API バージョン 53.0 の形態であることを意味します。
- 設定: なし。組織でサポートされる API の最大バージョンは 56.0 です。
-
コマンド: sf project retrieve start --source-dir force-app
結果: Salesforce CLI は、API バージョン 56.0 の SOAP エンドポイントに取得要求を送信します。要求とともに送信されるマニフェストの <version> 要素の値は 56.0 です。これは、取得されるメタデータソースが API バージョン 56.0 の形態であることを意味します。