platform-metadata-api-context-get

Salesforce Metadata API スキル

このスキルでは、604 種類すべての Salesforce Metadata API タイプに関する包括的なドキュメントを提供します。このスキルを使って、Salesforce DX プロジェクトで Salesforce メタデータ XML ファイルを作成、理解、変更できます。

概要

Salesforce Metadata API を使用すると、組織のカスタマイズを取得、デプロイ、作成、更新、削除できます。このスキルでは、各メタデータタイプについて、次のような詳細なドキュメントを利用できます。

• フィールド定義とデータ型
• 必須フィールドと任意フィールド
• WSDL スキーマ定義
• XML のサンプル構造
• ファイルの命名規則
• Salesforce DX プロジェクト内のディレクトリの場所

このスキルの使い方

重要：セクション単位での読み込み

JSON ファイル全体ではなく、必要なセクションだけを必ず読み込んでください。

重要：assets/metadata_api/*.json ファイルでは、必ず jq またはプログラムによる JSON 解析を使って、必要なセクションだけを抽出してください。 Read、cat、read_file、またはファイル全体を読み込むその他のツールを使って、これらのファイルを丸ごと読み込まないでください。詳細な WSDL のセグメントや、トークンの 60～80％を無駄にするその他のセクションが含まれています。（この SKILL.md やインデックス表のような小さなファイルを Read で読み込むのは問題ありません。このルールは、大きなメタデータタイプの JSON ファイルにのみ適用されます。）

各 JSON ファイルには、複数のセクション（fields、description、wsdl_segment など）が含まれています。ほとんどの用途で必要なのは、1～2 個のセクションだけです。

• フィールド定義の場合：fields セクションだけを読み込みます
• 目的を理解する場合：description セクションだけを読み込みます
• XML の例を確認する場合：declarative_metadata_sample_definition セクションだけを読み込みます
• デフォルトでは読み込まない項目：wsdl_segment（詳細なスキーマ）、file_information、directory_location

これにより、ファイルごとのトークン消費を 60～80％削減できます。

クイックスタート

特定のメタデータタイプに関する情報を取得するには、次のようにします。

1. セクションを指定する（最適）：「CustomObject.json の fields セクションだけを表示してください」
2. 複数のセクションを指定する：「Flow.json の fields と description を表示してください」
3. ファイル全体の読み込みを避ける：「CustomObject メタデータタイプ」とだけ尋ねるのではなく、必要なセクションを指定してください

クエリの例（セクション指定）

推奨：

• 「CustomObject.json の fields セクションだけを表示してください」
• 「Profile.json の fields セクションには、どのフィールドがありますか？」
• 「Flow.json の description と fields セクションを読み込んでください」
• 「ApexClass.json の declarative_metadata_sample_definition だけを教えてください」

避ける：

• 「CustomObject メタデータタイプを表示してください」（対象が広すぎます。ファイル全体が読み込まれます）
• 「CustomObject.json を読み込んでください」（不要な WSDL やその他のセクションも含まれます）

JSON ファイルの構造

各メタデータタイプは、assets/metadata_api/ 内に次の構造の JSON ファイルとして保存されています。

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "MetadataTypeName - Metadata API",
  "description": "Plain-text description of the metadata type.",
  "fields": {
    "fieldName": {
      "type": "string",
      "description": "Field description",
      "required": true
    }
  },
  "file_information": ".object",
  "directory_location": "objects",
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>",
  "declarative_metadata_sample_definition": [
    {
      "description": "Example description",
      "code": "<?xml version=\"1.0\"?>\n<MetadataType>...\n</MetadataType>"
    }
  ]
}

注： 文字列値（title、description、file_information、directory_location、wsdl_segment）はプレーンテキストとして保存されており、Markdown の見出し（#／##）やコードフェンスは含まれていません。file_information に格納されているのはファイルのサフィックス（例：.object、.ai）のみで、directory_location に格納されているのは SFDX フォルダー名（例：objects、aiApplications）のみです。

利用可能なセクション

sections 配列は、各ファイルに含まれるトップレベルのキーを示します。一般的なセクションは次のとおりです。

• title：メタデータ型の名前とヘッダー
• description：メタデータ型が表す内容
• fields：型固有のフィールドと、それぞれの型および説明
• sub_types：（複合型のみ）参照されるサブタイプ名 → そのサブタイプのフィールドのマップ。例：Flow → sub_types.FlowActionCall
• file_information：ファイルの命名規則と拡張子
• directory_location：SFDX プロジェクトでファイルが保存される場所
• wsdl_segment：WSDL の XML スキーマ定義
• declarative_metadata_sample_definition：XML コードの例

メタデータ型によっては、機能に固有の追加セクションがあります。詳しくは、Index Table をご覧ください。

詳細情報： トークン最適化が重要な理由、使用例、一般的なワークフロー、セクションの完全な用語集、バージョンとサポートに関する注意事項については、references/usage_guide.md をご覧ください。必要な場合にのみ、Read ツールで読み込んでください。

トークン最適化の戦略

重要：トークンの使用量とコストを最小限に抑えるには、次の点に従ってください。

1. コーパス全体ではなく、必要な特定のメタデータ型のみを読み込みます
2. ファイル全体ではなく、各ファイルから特定のセクションのみを読み込みます

セクション単位での読み込み（ベストプラクティス）

重大な警告：これらの JSON ファイルに read_file ツール（またはファイル全体を読み込むツール）を使用しないでください！

read_file はファイルの内容全体をコンテキストに読み込むため、セクション単位で読み込む目的が損なわれます。不要な WSDL セグメントや冗長なセクションを読み込むことで、トークン予算の 60～80％を無駄にします。（この SKILL.md やインデックステーブルなどの小さなファイルに Read を使うのは問題ありません。このルールは大きなメタデータ型 JSON ファイルにのみ適用されます。）

方法：ファイル全体を読み込むツールではなく、コードを使って JSON ファイルをプログラムで解析し、必要なセクションのみを抽出します。

動作するサンプルを用意しています：

複数の言語で、完全に動作するコード例を用意しています。

• Python：examples/python_section_loading.py - セクションを抽出する json.load() の使用例
• JavaScript/Node.js：examples/javascript_section_loading.js - セクションを抽出する JSON.parse() の使用例
• Bash + jq：examples/bash_section_loading.sh - jq によるコマンドラインの JSON 処理例

詳しい説明と使用方法については、examples/README.md をご覧ください。

基本的な手順（使用する言語に合わせて調整してください）：

1. JSON ファイルを読み込みます
2. データ構造に解析します
3. 必要なセクション（例：fields、description）のみを抽出します
4. 冗長なセクション（wsdl_segment、declarative_metadata_sample_definition）は無視します

避けるべきこと

これらの JSON ファイルに read_file ツールを絶対に使用しないでください：

read_file assets/metadata_api/CustomObject.json  # Loads entire file into context!
read_file assets/metadata_api/Flow.json          # Wastes 60-80% tokens!

ファイルをすべて読み込まないでください：

read_file assets/metadata_api/*.json  # This loads ~15MB of data!

トークンへの影響：

• セクション単位：メタデータ型あたり 50～200 トークン
• ファイル全体：メタデータ型あたり 500～2000 トークン
• 削減率：ファイルあたり 60～80％

複数の型を読み込む場合

• 関連する型：CustomObject + CustomField + ValidationRule
• 権限セット：Profile + PermissionSet + PermissionSetGroup
• UI コンポーネント：Layout + CompactLayout + QuickAction
• 自動化：Flow + WorkflowRule + ApexTrigger

特定のセクションを読み込むタイミング（強く推奨）

多くのメタデータタイプには、大規模な WSDL セグメントや広範なフィールドリストが含まれています。ファイル全体を読み込むのではなく、各 JSON ファイルから必要な特定のセクションだけを必ず読み込んでください。

1. まず、利用可能なセクションを確認します。JSON の sections 配列だけを読み込みます。
2. 必要なセクションだけを抽出します（例：フィールド定義には fields、概要には description）。
3. スキーマ検証が必要な場合を除き、WSDL セグメントは読み飛ばします。
4. 完全な XML の例が必要な場合を除き、declarative_metadata_sample_definition は読み飛ばします。

この方法では、冗長な WSDL 定義や長い例を除外することで、ファイルごとのトークン消費量を**60～80％**削減できます。

このスキルを使用するための概念的なアプローチ

ステップ 1：必要なものを特定する

自問してください。

• 何を作成または変更しようとしていますか？
• どの Salesforce メタデータタイプを扱っていますか？
• どの具体的な情報が必要ですか？
  • フィールド定義だけですか？→ fields セクションを読み込みます
  • 機能の理解ですか？→ description セクションを読み込みます
  • XML の例ですか？→ declarative_metadata_sample_definition セクションを読み込みます
  • スキーマ検証ですか？→ wsdl_segment セクションを読み込みます（ほとんど必要ありません）

ステップ 2：適切なタイプを見つける

次のいずれかの方法を使用します。

• 直接参照：タイプ名がわかっている場合（例：「CustomObject」）
• インデックス検索：関連するタイプを references/metadata_index_table.md で確認します
• 一般的なタイプ：以下の「クイックリファレンス：一般的なメタデータタイプ」セクションを参照します

ステップ 3：選択して読み込む（セクション単位）

セクション読み込みの判断ツリー：

Need field definitions?
  → Load ONLY 'fields' section (~50-200 tokens)

Need to understand what the type does?
  → Load ONLY 'description' section (~20-100 tokens)

Need XML structure example?
  → Load ONLY 'declarative_metadata_sample_definition' (~100-300 tokens)

Need all three?
  → Load 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → Still skip 'wsdl_segment', 'file_information', 'directory_location'
  → Savings: ~60-70% vs loading entire file

Need schema validation?
  → Only then load 'wsdl_segment' (this is verbose)

リクエスト形式：

• 単一セクション（最適）：「ApexClass.json から 'fields' セクションだけを表示してください」
• 複数セクション：「CustomObject.json から 'fields' と 'description' を読み込んでください」
• 冗長なセクションをスキップ：明示的に必要な場合を除き、wsdl_segment は読み込まないでください

ステップ 4：コードに適用する

読み込んだ情報を使用して、次のことを行います。

• 新しいメタデータ XML ファイルを作成する
• プロジェクト内の既存ファイルを理解する
• フィールド名と型を検証する
• 適切な名前空間で正しい XML 構造を生成する

ファイルの場所

すべてのメタデータタイプ JSON ファイルは次の場所にあります。

assets/metadata_api/
├── CustomObject.json
├── Flow.json
├── ApexClass.json
├── Profile.json
└── ... (600 more files)

パスの解決

このスキルを使用する場合、ファイルは次のように参照します。

• 絶対パス：assets/metadata_api/CustomObject.json
• スキルのルートからの相対パス：./assets/metadata_api/CustomObject.json

スキルは、作業ディレクトリに基づいてパスを自動的に解決します。

メタデータファイル生成の要件

有効でデプロイ可能なファイルを確実に作成するため、Salesforce メタデータ XML ファイルを生成する際は、次の要件に従ってください。

XML 構造の要件

すべてのメタデータファイルは、次の要件を満たす必要があります。

1. XML 宣言を含めます：

   <?xml version="1.0" encoding="UTF-8"?>
   

2. 正しい名前空間を使用します：

   <CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
   

3. ルート要素をメタデータタイプに一致させます：

   • CustomObject → <CustomObject>
   • Flow → <Flow>
   • Profile → <Profile>
   • など

名前空間の宣言

名前空間は必須であり、次のとおり正確に指定する必要があります。

http://soap.sforce.com/2006/04/metadata

正しい例：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

誤った例：

<CustomObject>  
<CustomObject xmlns="http://salesforce.com/metadata">  

必須フィールドと任意フィールド

各メタデータ型には異なるフィールド要件があります：

• スキーマ上必須（JSON 内で required: true）：WSDL がそのフィールドを必須としてマークしています。
• 実質的に必須（フラグは立っていないが実際には必要）：多くの場合、WSDL が必須としてマークするフィールドは、オーサリング契約が実際に要求するものよりも少なくなっています。CustomObject はその典型例です — JSON では externalDataSource、externalName、nameField のみが required: true とマークされています（最初の 2 つは外部オブジェクト専用の特殊事情です）が、通常の __c CustomObject をデプロイするには label、pluralLabel、deploymentStatus、sharingModel も必要です。常に declarative_metadata_sample_definition の例と照合してください。
• 条件付き必須：一部のフィールドは、特定の機能が有効な場合にのみ必須となります。
• 任意：ほとんどのフィールドは、不要であれば省略できます。

CustomObject からの例（注：実際のオーサリングでは required: true がマークする以上のものが必要です）：

{
  "fields": {
    "nameField": {
      "type": "CustomField",
      "description": "The name field for the custom object",
      "required": true
    },
    "label": {
      "type": "string",
      "description": "The label for the custom object (effectively required for normal __c objects)",
      "required": false
    },
    "sharingModel": {
      "type": "SharingModel (enumeration)",
      "description": "The sharing model for the object (effectively required for normal __c objects)",
      "required": false
    },
    "enableHistory": {
      "type": "boolean",
      "description": "Enable field history tracking",
      "required": false
    }
  }
}

検証のヒント

デプロイする前に：

1. XML 構文を検証する：整形式の XML であることを確認します（タグの対応、適切なネスト）
2. 必須フィールドを確認する：すべての必須フィールドが存在することを検証します
3. 名前空間を確認する：名前空間は正確でなければなりません
4. フィールド型をテストする：フィールドの値が期待される型と一致することを確認します
5. Salesforce CLI を使用する：sf project deploy validate を実行してエラーを検出します

詳細： フィールド型→XML のマッピング表、ファイル命名／2 ファイル／子型の規則、整形式ファイルの完全な例は references/usage_guide.md にあります。

重複する型名と曖昧な型名

一部の Metadata API 型名は、Enterprise/Data API や Tooling API のオブジェクト名としても存在します。例としては、ApexClass、ApexTrigger、CustomField、CustomObject、EmailTemplate、Layout、Profile、PermissionSet、RecordType、StaticResource、WebLink、ValidationRule、Flow などがあります。

プロンプトが曖昧な場合（例：「Profile について教えて」や「ApexClass にはどのフィールドがある？」）、ユーザーが次のどれを求めているかを確認してください：

1. ソース／デプロイのオーサリング向けの Metadata API XML 構造（本スキル、例：.profile-meta.xml、.cls-meta.xml）。
2. Enterprise/Data API の実行時 sObject／レコード参照（現在専用スキルはありません — Salesforce API ファミリールーターにフォールバックしてください）。
3. Tooling API の開発者ツール向けレコード参照（現在専用スキルはありません — Salesforce API ファミリールーターにフォールバックしてください）。

質問せずにほとんどの曖昧さを解消するヒューリスティクス：

• package.xml、force-app/、sfdx、.meta.xml、デプロイの意味での「deploy」「retrieve」「authoring」「blueprint」「template」「class definition」「permissions」への言及 → Metadata API（本スキル）。
• 「X にはどのフィールドがある？」／「どの列」／「DML」／「SOQL」／「query」／「REST」／「sObject」／「レコード」／「実行時」 → Enterprise/Data または Tooling API（別スキル）。
• Tooling 固有のシグナル：「Tooling API」、ApexCodeCoverage、EntityDefinition、TraceFlag、「code coverage」、「compile errors」、SymbolTable、デバッグログ → Tooling API。

シグナルがない場合のデフォルト規則：プロンプトに上記のシグナルがまったくなく、かつ本スキル（platform-metadata-api-context-get）が名前を指定して直接呼び出された場合、Metadata API の解釈をデフォルトとし、その前提をユーザーに明示的に開示してください（例：「これを .cls-meta.xml オーサリング向けの Metadata API 型として解釈します。Tooling API レコードや Enterprise/Data sObject を意味していた場合はお知らせください」）。スキル呼び出しのコンテキスト自体が、オーサリング／デプロイの意図を示すシグナルです。

トラブルシューティング

ファイルが見つかりません

問題: メタデータ型ファイルが見つかりません

解決策:

• ファイル名は区切り文字を使わない大文字始まりのパスカルケースです（例：CustomObject.json。customobject.json、Custom_Object.json、Custom-Object.jsonではありません）。
• 「見つからない」と判断する前に、references/metadata_index_table.mdを確認してください。インデックスに対して、次の2段階の復旧アルゴリズムを使用します。
  1. 正規化して部分一致を検索（大文字・小文字や区切り文字の違いに対応）：英数字以外の文字を取り除き、検索語と各インデックスエントリーを小文字に変換してから、部分一致を検索します。次のように解決されます：customobject、Custom_Object、Custom-Object → CustomObject。
  2. 見つからない場合は、あいまい一致を検索（文字抜けの誤入力に対応）：difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7)またはレーベンシュタイン距離が2以下のものを使用します。次のように解決されます：customfeld → CustomField、apxclass → ApexClass。部分一致だけでは、文字の削除には対応できません。
• 複数候補がある場合の判定方法：正規化して部分一致を検索した結果、複数の候補がある場合（例：customobjectがCustomObjectとCustomObjectTranslationの両方に一致）、正規化した長さが正規化した検索語の長さと等しいエントリーを優先します。それ以外の場合は、最も短い一致を優先します。
• 一部の型には、予想外の命名規則があります（アンダースコア、スペース、「OAuth」のような略語を使わないなど）。インデックスを正としてください。

SOAP エンベロープ／ヘッダー型（意図的に最小限）

次の2つの関連パターンを認識してください。

1. 結果型（AsyncResult、SaveResult、DeleteResult、UpsertResult、Error、DescribeMetadataResultなど） — fieldsは空で、wsdl_segmentに値が設定されています。これらはSOAPレスポンスのラッパーであり、スキーマ全体はwsdl_segmentにあります。構造が必要な場合は、そのセクションを参照してください。デプロイ可能なソースファイルではありません。
2. SOAPリクエストヘッダー（AllOrNoneHeader、SessionHeader、CallOptions、DebuggingHeader、OwnerChangeOptionsなど） — fieldsには最小限の項目が1～2個あり、wsdl_segmentはありません。これらはSOAPリクエストの動作を設定するものであり、呼び出し時のオプションであって、作成またはデプロイするメタデータではありません。

いずれの場合も、JSON出力が簡素なのは正しい状態です。これらの型にはソースファイル形式がないため、.AsyncResult-meta.xmlを作成しようとしないでください。

セクションがありません

問題: JSONファイルに想定したセクションがありません

解決策:

• sections配列を確認して、利用可能なセクションを確認してください
• すべてのメタデータ型にすべてのセクションがあるわけではありません
• セクションによっては型固有のものがあります（インデックステーブルに記載）

フィールド情報が不完全です

問題: フィールド定義に詳細情報がありません

解決策:

• 完全なスキーマ定義はwsdl_segmentで確認してください
• 一部のフィールドには、WSDLで定義された複合型があります
• 列挙値については、Salesforceのドキュメントと照合してください

サブタイプポインターをたどる（例：ProfileObjectPermissions[]）

fieldsセクションにProfileObjectPermissions[]、LayoutItem[]、ApprovalStep[]のような複合型名がある場合、そのネストされた型のサブフィールドはfieldsセクションにはありません。該当する複合型のwsdl_segmentにあります。このスキルの「デフォルトではwsdl_segmentをスキップする」というルールは、単純なフィールドの処理でトークンを節約するためのものです。ネストされた型の場合は、詳細を確認する必要があります。

実例 — ProfileのobjectPermissionsのサブフィールドを確認します。

# 1. Get the field type name from the fields section
jq '.fields.objectPermissions' assets/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' assets/metadata_api/Profile.json   | grep -A 30 'complexType name="ProfileObjectPermissions"'

grep -A Nを使うと、トークンコストを約150トークンに抑えられます。大きな型では5Kトークンを超えることがあるwsdl_segment全体を読み込まずに済みます。fieldsにFoo[]型があり、Fooのサブフィールドが必要な場合は、いつでもこのパターンを使用してください。

XML生成エラー

問題: 生成したXMLの検証に失敗します

解決策:

• 名前空間が正確に次のとおりであることを確認してください：http://soap.sforce.com/2006/04/metadata
• 必須フィールドがすべて含まれていることを確認してください
• フィールド値が想定された型と一致することを確認してください
• XML構文（終了タグ、正しいネスト）を検証してください

デプロイの失敗

問題：メタデータファイルをデプロイできません

解決策：

• まず sf project deploy validate を実行します
• Salesforce API バージョンとの互換性を確認します
• ファイル名が命名規則に従っていることを確認します
• ディレクトリ構造が SFDX 形式に準拠していることを確認します

クイックリファレンス：よく使われるメタデータ型

以下は、最もよく使われるメタデータ型です。

• CustomObject：フィールド、リレーションシップ、設定など、カスタム sObject のスキーマを定義します
• Flow：要素とコネクタを配置したビジュアルキャンバスを使用して、ビジネスプロセスを自動化します
• ApexClass：コンパイル済みの Apex サーバーサイドクラスです。本文、API バージョン、ステータスを含みます
• ApexTrigger：特定の sObject で DML イベントの前後に実行される Apex コードです
• Profile：ユーザープロファイルのオブジェクト／項目の権限、アプリの表示、ログイン設定を制御します
• PermissionSet：プロファイルとは独立してユーザーに付与される、追加の権限セットです
• CustomField：型、選択リスト値、数式など、標準オブジェクトまたはカスタムオブジェクトの項目を定義します
• Layout：レコードの詳細／編集ページにおける項目と関連リストの配置を制御します
• ValidationRule：数式条件が true の場合に保存を防ぎ、データ品質を維持します
• ApexPage：コントローラー参照とマークアップを含む、Visualforce ページ定義です
• ApexComponent：ページに埋め込める再利用可能な Visualforce コンポーネントです
• CustomTab：カスタムオブジェクト、Visualforce ページ、または Web URL を指すタブを定義します
• CustomApplication：アプリのタブバー、ナビゲーション項目、ブランディングを定義します
• LightningComponentBundle：JS、HTML、メタデータ記述子を含む LWC バンドルです
• AuraDefinitionBundle：コンポーネント、コントローラー、ヘルパーファイルを含む Aura（Lightning）コンポーネントバンドルです
• StaticResource：Visualforce と LWC からアクセスできるアップロード済みファイル（JS、CSS、画像、ZIP）です
• EmailTemplate：ワークフロールール、Process Builder、または Apex で使用するメールテンプレートです
• Report：フィルター、グループ化、列を含む保存済みレポート定義です
• Dashboard：レポートを基盤とするダッシュボードコンポーネントのコレクションです

すべてのメタデータ型の一覧については、インデックステーブルを参照してください。