getting-datacloud-schema

getting-datacloud-schema スキル

概要

このスキルは、SSOT REST API を使用して Salesforce Data Cloud から Data Lake Object（DLO）と Data Model Object（DMO）のスキーマ情報を取得します。組織内のすべての DLO または DMO を一覧表示したり、特定の DLO または DMO の詳細なスキーマを取得したりできます。

使用するタイミング

• Data Cloud 組織内のすべての DLO または DMO を確認したい場合
• 特定の DLO または DMO のフィールドスキーマが必要な場合
• Data Cloud のデータ構造を調べる場合
• DLO または DMO のフィールドタイプとメタデータを把握したい場合

前提条件

• SF CLI がインストールされ、対象の組織に認証されていること
• 組織で Data Cloud が有効になっていること
• ユーザーに適切な Data Cloud 権限があること

スキルの実行

パラメーター

1. org_alias（必須）：SF CLI の組織エイリアス（例：'afvibe'、'myorg'）
2. dlo_name（任意）：特定の DLO の開発者名（例：'Employee__dll'）
3. dmo_name（任意）：特定の DMO の開発者名（例：'Individual__dlm'）

ステップ 1：接続済みの組織を確認する

まず、sf org list を実行して接続されている組織を確認し、以降のすべての呼び出しで使用するエイリアスを取得します。

sf org list

出力例：

┌────┬───────┬──────────────────────────┬────────────────────┬───────────┐
│    │ Alias │ Username                 │ Org Id             │ Status    │
├────┼───────┼──────────────────────────┼────────────────────┼───────────┤
│ 🍁 │ myorg │ [email protected] │ 00DKZ00000b80NT2AY │ Connected │
└────┴───────┴──────────────────────────┴────────────────────┴───────────┘

出力から Alias の値（例：myorg）を取得し、以降のすべての呼び出しで <org_alias> として使用します。期限切れおよび削除済みのスクラッチ組織も表示するには、--all を使用します。

ステップ 2：SF CLI の認証を確認する

API 呼び出しを行う前に、組織が接続されていることを確認します。

sf org display --target-org <org_alias> --json

接続されていない場合は、次のコマンドを実行するようユーザーに伝えます。

sf org login web --alias <org_alias>

ステップ 3a：DLO スキーマスクリプトを実行する

Python スクリプトはこのスキルに同梱されています。この SKILL.md ファイルがあるディレクトリと同じディレクトリ内の scripts/ サブディレクトリに格納されています。そのディレクトリの絶対パスを使用してください。./scripts/ は現在の作業ディレクトリからの相対パスとして解決されるため、使用しないでください。スキルのディレクトリを基準にしたパスではありません。

すべての DLO を一覧表示するには：

python3 <skill_dir>/scripts/get_dlo_schema.py <org_alias>

特定の DLO のスキーマを取得するには：

python3 <skill_dir>/scripts/get_dlo_schema.py <org_alias> <dlo_name>

ステップ 3b：DMO スキーマスクリプトを実行する

すべての DMO を一覧表示するには：

python3 <skill_dir>/scripts/get_dmo_schema.py <org_alias>

特定の DMO のスキーマを取得するには：

python3 <skill_dir>/scripts/get_dmo_schema.py <org_alias> <dmo_name>

ステップ 4：結果を提示する

結果を解析し、ユーザーにとってわかりやすい形式で提示します。

DLO リストの場合：

• DLO 名、ラベル、カテゴリ、ID を表示する
• 合計数を示す
• データがある DLO（totalRecords > 0）を強調表示する

DLO スキーマの場合：

• 基本情報（名前、ラベル、カテゴリ、ステータス）を表示する
• すべてのフィールドを次の情報とともに一覧表示する：
  • フィールド名
  • データ型
  • 主キーかどうか
  • NULL 許容ステータス
• カスタムフィールドを強調表示する（DataSource__c、cdp_sys_* などのシステムフィールドは除外）
• 利用可能であれば、レコード数を表示する

DMO リストの場合：

• DMO 名、ラベル、カテゴリ、ID を表示する
• 合計数を示す

DMO スキーマの場合：

• 基本情報（名前、ラベル、カテゴリ、説明）を表示する
• すべてのフィールドを次の情報とともに一覧表示する：
  • フィールド名
  • データ型
  • 主キーかどうか
  • NULL 許容ステータス
• 利用可能であれば、データスペースの情報を表示する

ステップ 5：次のアクションを提案する

結果を表示した後、関連する次のアクションを提案します。

• DLO からデータをクエリする
• 計算インサイトを作成する
• セグメントを作成する
• データストリームを設定する
• DMO マッピングを作成する

使用する API エンドポイント

すべての DLO を一覧表示

GET /services/data/v64.0/ssot/data-lake-objects

レスポンス構造：

{
  "dataLakeObjects": [
    {
      "name": "Employee__dll",
      "label": "Employee",
      "category": "Profile",
      "id": "1dlXXXXXXXXXXXXXXX",
      "status": "ACTIVE",
      "totalRecords": 12,
      "fields": [...]
    }
  ],
  "totalSize": 5
}

DLO スキーマを取得

GET /services/data/v64.0/ssot/data-lake-objects/{dlo_name}

レスポンス構造（リストレスポンス内の個別オブジェクトと同じですが、ページネーション形式でラップされています）。

すべての DMO を一覧表示

GET /services/data/v64.0/ssot/data-model-objects

レスポンス構造：

{
  "dataModelObjects": [
    {
      "name": "Individual__dlm",
      "label": "Individual",
      "category": "Profile",
      "id": "0dmXXXXXXXXXXXXXXX",
      "fields": [...]
    }
  ],
  "totalSize": 10
}

DMO スキーマを取得

GET /services/data/v64.0/ssot/data-model-objects/{dmo_name}

レスポンス構造（リストレスポンス内の個別オブジェクトと同じですが、ページネーション形式でラップされています）。

エラー処理

よくある問題：

1. 組織が接続されていない

   • メッセージ："Org not connected"
   • 解決策：SF CLI で認証するようユーザーに依頼する

2. DLO が見つからない

   • メッセージ："DLO 'XYZ__dll' not found"
   • 解決策：まずすべての DLO を一覧表示し、名前を確認する

3. DMO が見つからない

   • メッセージ："DMO 'XYZ__dlm' not found"
   • 解決策：まずすべての DMO を一覧表示し、名前を確認する

4. 権限の問題

   • メッセージ：HTTP 403 エラー
   • 解決策：ユーザーに Data Cloud 権限があることを確認する

5. API バージョンの不一致

   • 現在のバージョン：v64.0
   • 解決策：新しい API バージョンに合わせてスクリプトを更新できます

使用例

例 1：すべての DLO を一覧表示

User: "Show me all DLOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dlo_schema.py afvibe
4. Display formatted list of DLOs

例 2：特定の DLO スキーマを取得

User: "Get the schema for Employee__dll in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dlo_schema.py afvibe Employee__dll
4. Display field schema with types and metadata

例 3：DLO を探索してからスキーマを取得

User: "What DLOs exist in myorg and show me the schema for the Employee one"

Response:
1. Run sf org list to discover connected org alias
2. List all DLOs in myorg
3. Identify Employee__dll
4. Get detailed schema for Employee__dll
5. Present both results

例 4：すべての DMO を一覧表示

User: "Show me all DMOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dmo_schema.py afvibe
4. Display formatted list of DMOs

例 5：特定の DMO スキーマを取得

User: "Get the schema for Individual__dlm in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dmo_schema.py afvibe Individual__dlm
4. Display field schema with types and metadata

例 6：DMO を探索してからスキーマを取得

User: "What DMOs exist in myorg and show me the schema for the Individual one"

Response:
1. Run sf org list to discover connected org alias
2. List all DMOs in myorg
3. Identify Individual__dlm
4. Get detailed schema for Individual__dlm
5. Present both results

出力形式

DLO リストの出力

Found 5 DLOs in org 'afvibe':

1. DataCustomCodeLogs__dll
   Label: DataCustomCodeLogs
   Category: Engagement
   Records: 233

2. Employee__dll
   Label: Employee
   Category: Profile
   Records: 12

[...]

DLO スキーマの出力

DLO: Employee__dll
Label: Employee
Category: Profile
Status: ACTIVE
Records: 12

Custom Fields:
  • id__c (Text) - Primary Key
  • name__c (Text)
  • position__c (Text)
  • manager_id__c (Number)

System Fields:
  • DataSource__c (Text)
  • InternalOrganization__c (Text)
  • cdp_sys_SourceVersion__c (Text)

Next steps:
- Query data: SELECT * FROM Employee__dll LIMIT 10
- Create segment based on position field
- Set up data stream for real-time updates

DMO リストの出力

Found 10 DMOs in org 'afvibe':

1. Individual__dlm
   Label: Individual
   Category: Profile

2. ContactPointEmail__dlm
   Label: Contact Point Email
   Category: Profile

[...]

DMO スキーマの出力

DMO: Individual__dlm
Label: Individual
Category: Profile
Description: Represents an individual person

Fields:
  • Id__c (Text) - Primary Key
  • FirstName__c (Text)
  • LastName__c (Text)
  • BirthDate__c (DateTime)

Next steps:
- Query data: SELECT * FROM Individual__dlm LIMIT 10
- View DLO mappings to this DMO
- Create calculated insights

注意事項

• DLO 名は必ず __dll サフィックスで終わります
• DMO 名は必ず __dlm サフィックスで終わります
• フィールド名は必ず __c サフィックスで終わります
• システムフィールド（DataSource__c、KQ_、cdp_sys_）は自動的に追加されます
• DLO および DMO のクエリには主キーのフィールドが必要です
• API は大規模な結果セット向けにページネーション（limit/offset）をサポートしています

関連スキル

• datakit_workflow：DMO マッピング操作に使用します
• datakit_validation：datakit 設定の検証に使用します
• DMO マッピングを作成する前にこのスキルを使用し、ソース DLO の構造を確認してください