experience-ui-bundle-site-generate

React UI バンドル向けデジタルエクスペリエンスサイト

Salesforce で React UI バンドルをホストするデジタルエクスペリエンスサイトを作成して構成します。このスキルは、React アプリを Salesforce から配信できるよう、必要最小限のサイトインフラストラクチャ（Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle、および sfdc_cms__site コンテンツタイプ）を生成します。

React サイトは標準の LWR サイトとは異なり、ルート、ビュー、テーマレイアウト、ブランドセットは必要ありません。サイトは薄いコンテナー（appContainer: true）として機能し、appSpace が参照する React UI バンドルにレンダリングを委ねます。

必須プロパティ

メタデータを生成する前に、5 つのプロパティすべてを解決してください。それぞれにフォールバックチェーンがあるため、値が見つかるまで順番に確認してください。

プロパティ	形式	解決方法
siteName	UpperCamelCase（例：MyCommunity）	ユーザーに尋ねるか、コンテキストから導き出します
siteUrlPathPrefix	すべて小文字（例：mycommunity）	ユーザーが指定した値を使うか、siteName を英数字のみのすべて小文字に変換します
appNamespace	文字列	sfdx-project.json の namespace → sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → デフォルトは c
appDevName	文字列	プロジェクト内の UIBundle メタデータ → sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias} → デフォルトは siteName
enableGuestAccess	Boolean	認証されていないゲストユーザーがサイトの API にアクセスできるかユーザーに尋ねます → デフォルトは false

appNamespace と appDevName プロパティは、今後のフォローアップ更新で使用する UIBundle バインディングを記録するものであり、サイトの初回作成時に appSpace に代入されるものではありません。sfdc_cms__site の content.json における appSpace は、初回作成時には常に "" です。その理由とフォローアップの手順については、configure-metadata-digital-experience.md を参照してください。

言語プロパティ

このスキルは、常に sfdc_cms__site と併せて sfdc_cms__languageSettings を出力します。すべてのサイトで defaultLocale を解決してください（デフォルトは en_US）。languages は、ユーザーがデフォルト以外の言語を追加するよう求めた場合にのみ解決してください。

プロパティ	形式	解決方法
defaultLocale	xx または xx_YY（例：en、en_US）	ユーザーに尋ねます → デフォルトは en_US
languages	{label, locale} のリスト	ユーザーが複数の言語、ロケール、国際化、または翻訳サポートを求めた場合にのみ、サイトがサポートする追加言語を尋ねます。要求がない場合、languageSettings のコンテンツでは、解決済みの defaultLocale のみを単一言語エントリとして宣言します。

コンテンツ項目のフォルダー名（languages）、title（LanguageContent）、および urlName（languagecontent）は、Experience Builder の固定された自動デフォルト値であり、ユーザーが指定するものではありません。configure-metadata-language-settings.md を参照してください。

事前確認：対象組織のリリース（多言語の場合のみ）

sfdc_cms__languageSettings コンテンツタイプで複数言語を宣言できるのは、Salesforce Release 264（API v68.0 以降）の場合のみです。ロケールを en_US のみとするサイトは、どの組織でも動作するため、この確認は不要です。

ユーザーが複数言語を求めた場合は、メタデータを書き込む前に、対象組織でサポートされる最大 API バージョンを確認してください。sf api request rest はインスタンス上の /services/data/ に直接アクセスし、トランスポート層で認証を処理します。そのため、アクセストークンをこのスクリプトのコンテキストに渡すことなく、組織が実際にサポートする上限が返されます。

MAX_API=$(sf api request rest "/services/data/" --target-org "${usernameOrAlias}" \
          | jq -r '[.[].version | tonumber] | max')

awk -v v="$MAX_API" 'BEGIN{ exit !(v+0 >= 68.0) }' \
  || { echo "ERROR: multi-language site containers require Salesforce Release 264 (API v68.0+). Target org's maximum supported API version is v${MAX_API}. Retarget to a Release 264+ org, or reduce the site to a single-locale (en_US) declaration." >&2; exit 1; }

確認に失敗した場合は、メタデータを書き込まないでください。バージョンの不一致をユーザーに報告し、処理を終了してください。

生成ワークフロー

ステップ 1：必須プロパティをすべて解決する

何かを作成する前に、5 つの必須プロパティすべてと、言語プロパティ defaultLocale の値を特定します。上記の表に記載された解決方法を使い、値が見つかるまで各オプションを順に確認します。languages プロパティを解決するのは、ユーザーが複数言語をリクエストした場合のみです。その場合は、ステップ 2 に進む前に、上記の事前確認を実行します。

ステップ 2：プロジェクト構造を作成する

Salesforce の利用可能なメタデータスキーマと Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle のフィールドコンテキストを使用して、各ファイルが有効な構造になるようにします。

まだ存在しないファイルやディレクトリを、次のパスに作成します。

メタデータタイプ	パス
Network	networks/{siteName}.network-meta.xml
CustomSite	sites/{siteName}.site-meta.xml
DigitalExperienceConfig	digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml
DigitalExperienceBundle	digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml
DigitalExperience (sfdc_cms__site)	digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*
DigitalExperience (sfdc_cms__languageSettings)	digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/*

各 DigitalExperience コンテンツタイプのディレクトリには、_meta.json と content.json のみを含めます。バンドル内では、sfdc_cms__site と sfdc_cms__languageSettings の両方が常に必要です。sfdc_cms__languageSettings のデフォルト設定には、解決済みの defaultLocale（例：en_US）のみを指定します。ユーザーが複数言語のサポートをリクエストした場合は、追加の言語を加えます。他のコンテンツタイプは許可されません。

ステップ 3：すべてのメタデータフィールドに値を設定する

以下のドキュメントにあるデフォルトのテンプレートを使用します。{中かっこ}内の値は解決済みのプロパティ参照です。ステップ 1 で特定した実際の値に置き換えます。

メタデータタイプ	テンプレート参照
Network	configure-metadata-network.md
CustomSite	configure-metadata-custom-site.md
DigitalExperienceConfig	configure-metadata-digital-experience-config.md
DigitalExperienceBundle	configure-metadata-digital-experience-bundle.md
DigitalExperience (sfdc_cms__site)	configure-metadata-digital-experience.md
DigitalExperience (sfdc_cms__languageSettings)	configure-metadata-language-settings.md

URL の更新については、update-site-urls.mdを参照してください。

ステップ 3 の実行に関する注意：ドキュメントを読み込んで使用する

• エージェントは、メタデータフィールドへの値の設定を試みる前に、ステップ 3 で参照されている各 references/*.md ファイルの全文を必ず読む必要があります。
• プラットフォームのファイル読み取りツール（例：read_file）を使用して、これらのファイルを全文読み込んでください。その後、ステップ 1 で解決したプロパティを使って、{中かっこ}内の値を置換します。
• 読み込むファイル：
  • references/configure-metadata-network.md
  • references/configure-metadata-custom-site.md
  • references/configure-metadata-digital-experience-config.md
  • references/configure-metadata-digital-experience-bundle.md
  • references/configure-metadata-digital-experience.md
  • references/configure-metadata-language-settings.md
• ファイル全体を読み込み、プレースホルダー（例：{siteName}）を解決済みの値に置き換えてから、展開したテンプレートを使用してメタデータの XML／JSON コンテンツに値を設定します。

ステップ 4: テンプレート化されていないプロパティを変更しない

{braces} で囲まれた変数として表現されていない Network、CustomSite、DigitalExperience、DigitalExperienceConfig、または DigitalExperienceBundle メタデータのデフォルトプロパティ値は一切変更しないでください。

検証チェックリスト

デプロイする前に、以下を確認してください:

• 5 つの必須プロパティがすべて解決されており、defaultLocale も解決されている (ユーザーが指定しない場合は en_US がデフォルトになります)
• プロジェクト構造に従って、すべてのメタデータディレクトリとファイルが存在する
• すべてのメタデータフィールドが、{braces} を置換しただけのステップ 3 のテンプレートと一致している。他のデフォルトプロパティ値は追加も変更もされていない
• sfdc_cms__site の content.json 内の appSpace が空文字列 "" である (初回のサイト作成では appSpace は決してバインドされません。これは UIBundle がターゲット組織にデプロイされた後の、別個のフォローアップ更新です)
• sfdc_cms__languageSettings/languages/ ファイルが存在する。言語宣言が以下のすべてのプラットフォームルールを満たしている:
  • defaultLocale が、宣言されたいずれかの言語の locale と一致しており、その言語がアクティブである
  • すべての locale が Salesforce でサポートされており、すべての言語が isActive: true であり、各 locale + label の組み合わせが一意であり、宣言された言語の数がプラットフォームの上限を超えていない
  • ルールカタログの全体については configure-metadata-language-settings.md を参照してください。単一言語のデフォルト宣言はすべてのルールを自明に満たします。
• デプロイが正常に検証される (DigitalExperience タイプはすでに sfdc_cms__languageSettings をカバーしているため、--metadata リストの変更は不要です):

sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

一般的なワークフロー

Experience サイトの URL を更新する

使用する場合 ユーザーがサイトの URL (urlPathPrefix) を更新または変更したい場合。

手順:

• update-site-urls.md を読んで、3 コンポーネントのアーキテクチャと URL 更新ワークフローを理解する
• ドキュメントのステップバイステップのワークフローに従って、3 つのコンポーネント (DigitalExperienceConfig、Network、CustomSite) すべてにわたって URL を一貫して更新する

多言語サポートを構成する

使用する場合 ユーザーが、すべてのサイトがすでに受け取るデフォルトロケールのみの宣言を超えて、サイトが複数の言語、ロケール、国際化、または翻訳をサポートすることを望む場合。

手順:

• サイトがサポートすべき追加言語と、どのロケールをデフォルトにするかを収集する (上記の defaultLocale プロパティと languages プロパティを解決します)
• 事前チェック: ターゲット組織のリリース チェックを実行する — 組織がリリース 264 (API v68 以降) より下の場合は中止する
• テンプレート、フィールドリファレンス、およびプラットフォームの検証ルールについては configure-metadata-language-settings.md を読む
• sfdc_cms__languageSettings/languages/content.json (デフォルトロケールですでに存在します) を拡張して追加の言語エントリを含め、デプロイ検証を再実行する

注: これはオーサリング専用です — 宣言されたロケールはクリーンにデプロイされますが、リクエスト時にパス内ロケールのルーティングはまだ解決されません。UI バンドルのコンテンツ自体は翻訳しないでください。これはサイトがサポートする言語を宣言するだけです。