1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【SFDCメタデータ構造チェック Day1】package.xmlとソース形式(SFDX)の全体像

1
Last updated at Posted at 2026-11-01

image.png

はじめに

「SFDCメタデータ構造チェック Advent Calendar 2026」は、よく使うSalesforceメタデータを1日1種類ずつ取り上げ、retrieveしたときのXML構造と実務上のハマりどころを整理するシリーズです。

Day1は導入回として、すべての回の土台になる package.xml と ソース形式(SFDX) の全体像を整理します。

  • 対象APIバージョン:68.0(Winter '27、執筆時点の最新)
  • CLI:sf CLI(v2)

※本記事は個人の整理メモです。CLIの挙動は公式ドキュメントに加え、Salesforce CLIの公式リポジトリ(forcedotcom/source-deploy-retrieve、salesforcecli/plugin-deploy-retrieve)のソースで確認しています。実際のSalesforce組織でのretrieve動作は未検証です。 バージョン依存の挙動は利用中のバージョンで再確認してください。

package.xmlとは何か

package.xmlは、Metadata APIに「どの型の、どのコンポーネントを」retrieve / deployするかを伝える マニフェスト(目録) です。sf CLIはこれを元に組織からメタデータを取得し、ローカルには ソース形式 で保存します。

fig0_flow.png

package.xmlの構造

最小構成はこれだけです。

manifest/package.xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>Account</members>
        <members>MyObject__c</members>
        <name>CustomObject</name>
    </types>
    <version>68.0</version>
</Package>
要素 役割 メモ
Package ルート要素 名前空間 http://soap.sforce.com/2006/04/metadata
types メタデータ型ごとのまとまり 型の数だけ繰り返す
members 取得するコンポーネントのフルネーム * でワイルドカード(対応型のみ)
name メタデータ型名 CustomObject、ApexClass など
version retrieve / deployで使うメタデータのAPIバージョン CLI側の値との関係は後述

👉 members の書式は型ごとに違います(項目なら Account.Foo__c、レポートなら MyFolder/MyReport)。

Metadata API形式とソース形式の違い

ローカルに置く形式は2種類あります。

fig1_format_compare.png

観点 Metadata API形式(mdapi) ソース形式(SFDX)
ルート package.xml を含むフォルダ force-app/main/default/ など
CustomObject Account.object 1ファイルに項目等を内包 objects/Account/ 配下の fields/、listViews/、recordTypes/、validationRules/ などへ 分解
XMLのみの型 Account.object Account.object-meta.xml(-meta.xml 付き)
Apex等 .cls + .cls-meta.xml 同じ

CustomObjectの分解先は、businessProcesses / compactLayouts / fields / fieldSets / indexes / listViews / recordTypes / sharingReasons / validationRules / webLinks の10種類です(CLIのメタデータレジストリ定義より)。

👉 分解のおかげで、項目追加のPRは fields/Foo__c.field-meta.xml 1ファイルの差分になり、レビューしやすくなります。

主要コマンド(sf CLI v2)

# ローカルのソースからpackage.xmlを生成
sf project generate manifest --source-dir force-app --output-dir manifest
# 組織に存在するメタデータからpackage.xmlを生成
sf project generate manifest --from-org my-org --output-dir manifest
# package.xmlを指定してソース形式でretrieve
sf project retrieve start --manifest manifest/package.xml --target-org my-org
# ソース形式 → Metadata API形式(出力先に package.xml も生成される)
sf project convert source --root-dir force-app --output-dir mdapi_out
# Metadata API形式 → ソース形式(--root-dir は package.xml があるフォルダを指す)
sf project convert mdapi --root-dir mdapi_out --output-dir force-app

Metadata API形式のまま取りたい場合は --target-metadata-dir を付けます。

# Metadata API形式でretrieveし、zipを展開する
sf project retrieve start --manifest manifest/package.xml --target-org my-org --target-metadata-dir mdapi_retrieved --unzip

このとき、zipは unpackaged.zip という名前で保存され、--unzip で mdapi_retrieved/unpackaged/unpackaged/ に展開されます(unpackaged が二重になる点に注意)。続けて convert mdapi する場合は --root-dir mdapi_retrieved/unpackaged/unpackaged を指定します。

ハマりどころ・Tips

1. 標準オブジェクトは * では取れない

CustomObject の * で取れるのはカスタムオブジェクト側だけで、Account などの 標準オブジェクトは含まれません。標準オブジェクトやその上のカスタム項目が必要なら、<members>Account</members> のように 明示指定 します。標準オブジェクトもカスタムオブジェクトと同じ <name>CustomObject</name> の types に書きます。

また、フォルダ型(Report、Dashboard、EmailTemplate、Document)は フォルダ名/名前 での列挙が基本です。たとえばReportは、公式ドキュメントで「package.xmlで * は使えない」と明記されています。* 対応可否は、Metadata API Developer Guideの型ごとのページで確認するのが確実です。

2. Profileは「一緒に取ったもの」によって取得内容が変わる

Profileをretrieveしたときに返る内容のうち、FLSやオブジェクト権限など他のコンポーネントに紐づく設定は、同じリクエストで一緒に取得したコンポーネント に左右されます。

たとえば項目レベルセキュリティ(FLS)は、同じリクエストで取得したオブジェクトの項目に関する設定が対象になります。Profileだけを取得すると、FLSなどが含まれない場合があります。

一方、PermissionSetは挙動が異なります。 API 40.0以降では、PermissionSetをretrieveすると、同じリクエストで関連コンポーネントを指定しなくても、そのPermissionSetのメタデータを取得できます。

※API 39.0以前のPermissionSetには、同時取得したコンポーネントに依存する仕様がありました。

この違いはDay12(PermissionSet)・Day14(Profile)で詳しく扱います。

3. version とCLIのAPIバージョンは別物として意識する

sf CLIのretrieveでは、2種類のバージョンが別々に決まります。

  • メタデータのバージョン:--manifest を使う場合は、package.xmlの <version> の値が使われます。返ってくるXMLの形(要素の有無)はこちらに依存します
  • SOAP APIのバージョン:リクエストに使うAPIのバージョンです。--api-version で上書きできます。指定しなければ org-api-version の設定値、それもなければ接続先組織がサポートする最新バージョンが使われます

package.xmlに <version> がない場合や --source-dir 指定時は、sfdx-project.json の sourceApiVersion がメタデータのバージョンとして使われます。それもなければ、SOAP APIと同じバージョンになります。retrieve時には次のようなログが出るので、両方の値を確認する習慣をつけると安心です。

Retrieving v68.0 metadata from user@example.com using the v68.0 SOAP API

※上記の解決順は、執筆時点のCLIのソースコードで確認したものです。CLIのバージョンによって細部が変わる可能性があるため、package.xmlには <version> を明示しておくのがおすすめです。

4. 分解のされ方は型ごとに違う

CustomLabelsは、デフォルトでは分解されず、labels/CustomLabels.labels-meta.xml の1ファイルに集約されます。PermissionSetも、デフォルトでは1ファイルです。

一部の型は、sfdx-project.json の sourceBehaviorOptions で分解を オプトイン できます。執筆時点のCLIで指定できる値は次のとおりで、いずれも名前に Beta が付いています。

  • decomposePermissionSetBeta / decomposePermissionSetBeta2
  • decomposeCustomLabelsBeta / decomposeCustomLabelsBeta2
  • decomposeSharingRulesBeta
  • decomposeWorkflowBeta
  • decomposeExternalServiceRegistrationBeta

有効化には sf project convert source-behavior --behavior <値> を使います。このコマンドは sfdx-project.json を書き換え、既存のローカルファイルも変換します。まず --dry-run で影響を確認するのが安全です。

retrieve用のpackage.xml断片

シリーズで使う「まず一通り取る」用の断片です。

※以下はpackage.xmlのtypes部分の抜粋です。実際に利用する際は、Packageルート要素とversionを含めてください。

manifest/package.xml
<types>
    <members>*</members>
    <members>Account</members>
    <members>Contact</members>
    <name>CustomObject</name>
</types>
<types>
    <members>*</members>
    <name>ApexClass</name>
</types>
<types>
    <members>*</members>
    <name>PermissionSet</name>
</types>

👉 * と標準オブジェクト名は、同じ types 内に併記できます(CustomObjectは「ワイルドカードと名前の併用」に対応する型です)。

まとめ

  • package.xmlは types(members + name)と version だけのシンプルな目録。ただし members の書式とワイルドカード対応は型ごとに違う
  • 標準オブジェクトは * に含まれないため明示指定が必要
  • ソース形式はCustomObjectなどを分解し、XMLのみの型に -meta.xml を付ける。形式間は sf project convert source / mdapi で行き来できる

シリーズ目次(予定)

Day テーマ Day テーマ
1 package.xmlとソース形式の全体像(本記事) 14 Profile
2 CustomObject 15 Flow
3 CustomField 16 ApexClass / ApexTrigger
4 RecordType 17 LightningComponentBundle
5 ValidationRule 18 CustomLabels
6 ListView 19 CustomMetadata(カスタムメタデータ型)
7 Layout 20 GlobalValueSet / StandardValueSet
8 CompactLayout 21 EmailTemplate(フォルダ型)
9 FlexiPage(Lightningページ) 22 Report / Dashboard
10 CustomTab 23 SharingRules
11 CustomApplication 24 NamedCredential / ExternalCredential
12 PermissionSet 25 destructiveChangesと総まとめ
13 PermissionSetGroup

※予定は変更になる場合があります。

次回Day2は CustomObject です。分解後の objects/<オブジェクト名>/ 配下と、本体の *.object-meta.xml に残る要素を見ていきます。

初めての方向け:ざっくり理解

Salesforceのメタデータを扱う際によく登場する3つの用語を、簡単に整理します。

  • package.xml(パッケージ):Salesforceから取得したい設定情報を指定する「目録(リスト)」です。例えば、どのオブジェクトやApexクラスを取得するかを記載します。
  • retrieve(リトリーブ):Salesforce組織にある設定情報を、ローカル環境(自分のPCなど)へ取得する操作です。
  • ソース形式(SFDX):取得した設定情報を、種類ごとにファイルやフォルダへ分けて保存する形式です。変更箇所を確認・管理しやすいのが特徴です。

例えば、「案件」オブジェクトの設定を取得する場合は、次の流れになります。

  1. package.xmlで取得したい設定情報を指定する
  2. retrieveでSalesforceから設定情報を取得する
  3. ソース形式でファイルやフォルダに整理して保存する

つまり、「package.xmlで指定 → retrieveで取得 → ソース形式で保存」という関係です。

この流れを覚えておくと、Salesforceの設定情報をファイルとして管理する仕組みが理解しやすくなります。

参考

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?