platform-dataspace-access-configure

platform-dataspace-access-configure

Salesforce Data Cloud で DataSpace アクセスを、次の 2 層モデルを使用して設定します。

1. DataSpace レベルのアクセス — 権限セット XML に <dataspaceScopes> 要素を含めて MDAPI でデプロイし、PermissionSet に DataSpace へのアクセス権を付与します。
2. オブジェクトレベルのアクセス（任意） — Object Access Grants Connect API を使用して、その権限セットに DataSpace 内の特定の DMO／DLO／CIO オブジェクトへのアクセス権を付与します。

PermissionSet と DataSpace の関連付けを確立するには、MDAPI レイヤーが必要です。Connect API レイヤーは任意であり、データガバナンスポリシーだけでアクセスを制御するのではなく、特定のオブジェクトにアクセスを限定する場合にのみ必要です。

---

最初にケースを決定する

ファイルを作成する前に、以下の表からケースを 1 つだけ選択してください。各ケースで出力形式が異なります。

ケース	ユーザーの意図	権限セットの状態	出力するファイル
A. DS アクセス付きの新しい権限セットを作成	「Y のデータスペーススコープを持つ、X という名前の権限セットを作成する」	まだ存在しない	permissionsets/<Name>.permissionset-meta.xml および package.xml
B. 既存の権限セットに DS アクセスを追加	「既存の権限セット X にデータスペース Y へのアクセス権を付与する」	すでにデプロイ済み（他の権限を含む場合あり）	permissionsets/<Name>.permissionset-meta.xml（パッチ適用済み）および package.xml — 以下のケース B のワークフローを参照
C. オブジェクトレベルの権限付与のみ	「権限セット X に（データスペース Y 内の）オブジェクト Z へのアクセス権を付与する」— 権限セットとスコープはすでに設定済み	dataspaceScopes を含めてデプロイ済み	api-request.json（Connect API の本文）。権限セット XML は不要、package.xml も不要
D. 既存の DS アクセスを確認	「どの権限セットがデータスペース Y にアクセスできるか？」	任意	チャット／レポートのみ。デプロイ可能なファイルは不要、実行時の API 変更も不要

選択したケースに記載されているファイルのみを出力してください。ケース C の要求に対してケース A／B のファイルを出力する（またはその逆）と、正確性に問題が生じます。余分なファイルによってデプロイの形式が変わります。

ケース B — 重要： PermissionSet の MDAPI デプロイはメタデータ全体の置き換えです。再デプロイ時に省略した <objectPermissions>、<fieldPermissions>、<userPermissions>、<tabSettings>、<applicationVisibilities>、<recordTypeVisibilities>、<customPermissions>、<pageAccesses>、<classAccesses>、<customMetadataTypeAccesses>、<customSettingAccesses>、<externalDataSourceAccesses> の各要素は、すべて組織から削除されます。既存の権限セットに <dataspaceScopes> を追加する前に、現在の XML を取得してパッチを適用してください。最初から手作業で作成してはいけません。

ケース B のワークフロー

1. 既存の権限セットを取得します。

   sf project retrieve start --metadata PermissionSet:<Name> --target-org <alias>
   

2. 取得した permissionsets/<Name>.permissionset-meta.xml を開きます。既存の要素をすべて保持してください。
3. 対象の DataSpace の <dataspaceScopes> ブロックを挿入します（MDAPI ではファイル内の要素の順序は問いません）。ファイルに同じ DataSpace 用の <dataspaceScopes> ブロックがすでにある場合は、そのブロックだけを置き換えます。他の DataSpace 用の <dataspaceScopes> ブロックはすべてそのまま残してください。DataSpace ごとにブロックは 1 つです。指定されたスコープを削除する場合は、該当するブロックだけを削除してデプロイします。ブロックを省略すると、その DataSpace の権限が取り消されます。PermissionSet を取得し直し、該当する <dataspaceScopes> ブロックが存在しないことを確認して検証します。
4. <members> に権限セットを記載した package.xml を作成します。
5. sf project deploy start で再デプロイします。

---

このスキルがタスクを担当する場合

ユーザーが次のことを求めている場合に、このスキルを呼び出します。

• Data Cloud の DataSpace へのアクセスを許可する権限セットを作成する
• 既存の権限セットに dataspaceScopes を追加または変更する
• DataSpace 内の特定の DMO / DLO / CIO オブジェクトへのアクセスを権限セットに許可する
• DataSpace スコープを持つ権限セットを一覧表示し、そのアクセスレベルを確認する
• DataSpace スコープの dataAccessLevel と objectAccessLevel を設定する
• 権限セットと DataSpace の組み合わせに対するオブジェクトアクセス許可を一覧表示または削除する

次の場合は、ほかのスキルに委任します。

• 権限セットに DataSpace へのアクセスがまったくない → platform-permission-set-generate

---

レイヤー 1 — DataSpace レベルのアクセス（MDAPI）

PermissionSet XML 内に <dataspaceScopes> 要素を埋め込み、MDAPI でデプロイします。

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Data Cloud Analyst</label>
    <description>Data cloud analyst access to the default dataspace</description>
    <hasActivationRequired>false</hasActivationRequired>
    <dataspaceScopes>
        <dataspaceScope>default</dataspaceScope>
        <dataAccessLevel>ALL</dataAccessLevel>
        <objectAccessLevel>BY_POLICY</objectAccessLevel>
    </dataspaceScopes>
</PermissionSet>

要素のルール

要素	必須	有効な値	用途
<dataspaceScopes>	はい	親要素（複数形）	単一の DataSpace スコープ許可のコンテナー
<dataspaceScope>	はい	DataSpace の API 名（例：default）	この許可の対象となる DataSpace
<dataAccessLevel>	はい	NONE、CONTROLLED_BY_PARENT、ALL	DataSpace 内の行レベルのデータアクセス
<objectAccessLevel>	はい	BY_POLICY、ALL_IN_DATASPACE	オブジェクトレベルのアクセス。BY_POLICY はデータガバナンスポリシーに委ねます。ALL_IN_DATASPACE は、dataAccessLevel が CONTROLLED_BY_PARENT の場合にのみ許可されます

よくある間違い

• 親要素名が間違っている — <dataspaceScopes> の代わりに <dataspaceScopeAccess> を使用しています。デプロイがエラーを表示せずに失敗したり、分かりにくいエラーが発生したりします。
• 子要素名が間違っている — <dataspaceScope> の代わりに <dataspaceScopeName> を使用しています。
• 列挙値が間違っている — ViewAllRows / Read / OWNER / EDIT は有効ではありません。dataAccessLevel には NONE、CONTROLLED_BY_PARENT、ALL を、objectAccessLevel には BY_POLICY または ALL_IN_DATASPACE を使用してください。許可される組み合わせについては、「要素のルール」表を参照してください。デプロイエラー -379999659 は列挙値が無効であることを示します。
• 1 つの要素に複数のスコープを指定している — <dataspaceScopes> がアクセスを許可する DataSpace は 1 つだけです。複数の DataSpace へのアクセスを許可するには、<dataspaceScopes> ブロックを複数追加してください。

パッケージのレイアウト（ケース A およびケース B）

レイヤー 1 用のデプロイ可能なバンドルには、常に両方のファイルが含まれます。

<output-root>/
  package.xml
  permissionsets/<Name>.permissionset-meta.xml

package.xml（必須 — デプロイ対象のすべての権限セットを <members> に記載します）：

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Data_Cloud_Analyst</members>
        <name>PermissionSet</name>
    </types>
    <version>67.0</version>
</Package>

デプロイします。

sf project deploy start --source-dir force-app/main/default/permissionsets/ --target-org <alias>

---

読み取り専用の DataSpace スコープの確認 — ケース D

ユーザーが DataSpace へのアクセス権を持つ権限セットを尋ねている場合、または変更を加えずに dataAccessLevel と objectAccessLevel の確認を求めている場合は、ケース D を使用します。

SOQL で DataspaceScope または DataspaceScopeAccess をクエリしないでください。 これらのオブジェクトは、このリレーションシップに対してサポートされているクエリ対象ではありません。検出、フォールバック、トラブルシューティングのいずれの場合も、SOQL を試さないでください。

1. PermissionSet メタデータを、分離された一時ローカルプロジェクトと出力ディレクトリに取得します。ユーザーの既存のメタデータツリーには取得しないでください。最初にスキルリポジトリのパスを保存します（可能であれば絶対パスを使用します）：

   REPO_ROOT="<absolute/path/to/sf-skills-internal>"  # or $(pwd) if you're in the repo root
   WORK_DIR=$(mktemp -d)
   sf project generate --name dataspace-scope-inspection --output-dir "$WORK_DIR"
   cd "$WORK_DIR/dataspace-scope-inspection"
    sf project retrieve start --json \
      --metadata "PermissionSet:*" --target-org <alias> \
      --output-dir "$WORK_DIR/retrieved"
   

   Inspect the JSON result before continuing. A nonzero command status, a failed result.status, warnings, or an unexpectedly low result.fileProperties count means the retrieve may be incomplete. Report that limitation rather than treating the result as empty, and do not fall back to SOQL.
2. Run the inspection script from the skill directory (do not rely on relative paths after cd changed the working directory). Supply the retrieved directory and optional DataSpace name:

   "$REPO_ROOT/skills/platform-dataspace-access-configure/scripts/inspect-dataspace-scopes.sh" \
     "$WORK_DIR/retrieved" "<DataSpace API name, if given>"
   

   結果を 1 行につき 1 件ずつユーザーに報告します。

ケース D では、組織に対する操作は読み取り専用です。メタデータのデプロイ、権限セットの割り当て、Apex の実行、レコードの DML、POST、PUT、PATCH、DELETE リクエストを行わないでください。確認作業の一環として、ユーザーのワークスペースに package.xml、PermissionSet XML、api-request.json を生成しないでください。報告後、一時作業ディレクトリを削除します：rm -rf "$WORK_DIR"。スコープレベルの objectAccessLevel は、明示的なオブジェクト許可の一覧ではありません。これらは、ユーザーから依頼があった場合に限り、読み取り専用のオブジェクトアクセス許可エンドポイントで別途確認してください。

レイヤー 2 — オブジェクトレベルのアクセス（Connect API）— ケース C

objectAccessLevel が BY_POLICY ではない場合、またはガバナンスポリシーが対象オブジェクトをカバーしていない場合にのみ必要です。権限付与は実行時に行われます。MDAPI のデプロイ、package.xml、権限セット XML は不要です。 ケース C のタスクで必要な成果物は、Connect API 呼び出しを記述する単一の api-request.json だけです。

まず API バージョンを解決する

このレイヤーの各 Connect API endpoint には、/services/data/v<apiVersion>/… セグメントが含まれます。v67.0 をハードコードしないでください。 エンベロープを作成する前に、対象組織の実際の API バージョンを解決し、リクエストがその組織でサポートされている仕様に合致するようにしてください。

sf org display --target-org <alias> --json | jq -r '.result.apiVersion'

• 返された値（例：67.0、68.0）を endpoint の v<apiVersion> に代入します。
• 組織をクエリできない場合（オフラインでの作成、エイリアスがまだない場合）は、このスキルのフロントマターにある minApiVersion（67.0）にフォールバックします。エンドポイントはこのバージョンで導入されており、それ以降のバージョンでも同じ本文を使用できます。
• ユーザーがプロンプトでバージョンを明示的に指定した場合は、その値をそのまま使用します。

以下のテンプレートでは、{apiVersion} はプレースホルダーです。api-request.json を出力する前に、解決した API バージョン（例：67.0、68.0）に置き換えてください。

api-request.json — 標準形式

リクエストは、method、endpoint、headers、body、expectedResponse を含む自己記述型エンベロープとして出力します。本文のみを出力しないでください。レビュー担当者や後続のツールはエンベロープを参照します。

{
  "method": "POST",
  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "permissionSetName": "Data_Cloud_Analyst",
    "dataSpaceName": "default",
    "objectApiName": "Account__dlm"
  },
  "expectedResponse": {
    "status": 201,
    "body": {
      "permissionSetName": "Data_Cloud_Analyst",
      "dataSpaceName": "default",
      "objectApiName": "Account__dlm"
    }
  }
}

一括権限付与

api-request.json のエンベロープ形式は同じです。endpoint には /actions/bulk-create サフィックスを追加し、body.objectApiName をリスト値の body.objectApiNames に置き換えます。一括レスポンスではフラットなリクエストペイロードではなく、オブジェクトごとのステータスエントリが返されるため、expectedResponse から body フィールドを省略します（詳しくは以下の「注意点」を参照）。

{
  "method": "POST",
  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants/actions/bulk-create",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "permissionSetName": "Data_Cloud_Analyst",
    "dataSpaceName": "default",
    "objectApiNames": ["Account__dlm", "Contact__dlm", "Opportunity__dlm"]
  },
  "expectedResponse": {
    "status": 201
  }
}

権限付与の一覧表示

method: "GET" を指定し、endpoint にクエリパラメーターを含め、body は指定しない、同じエンベロープ形式を使用します。

{
  "method": "GET",
  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default",
  "headers": {
    "Accept": "application/json"
  },
  "expectedResponse": {
    "status": 200
  }
}

権限付与の取り消し

method: "DELETE" を指定し、パスセグメントとしてオブジェクト API 名を含めます。また、expectedResponse.status: 204（コンテンツなし）を指定します。

{
  "method": "DELETE",
  "endpoint": "/services/data/v{apiVersion}/ssot/data-governance/object-access-grants/Account__dlm?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default",
  "headers": {
    "Accept": "application/json"
  },
  "expectedResponse": {
    "status": 204
  }
}

オブジェクトの種類

• DMO（データモデルオブジェクト）— 統合プロファイルオブジェクト。サフィックスは __dlm
• DLO（データレイクオブジェクト）— 取り込まれた未加工データ。サフィックスは __dll
• CIO（計算済みインサイトオブジェクト）— 計算されたメトリクス。サフィックスは __cio

---

セットアップの組み合わせ — 初期状態からのケース A + ケース C

ユーザーが何も設定されていない状態から開始し、権限セットとスコープ、およびオブジェクトごとの権限付与の両方を単一のリクエストで求めている場合にのみ、このセクションを使用してください。ユーザーのプロンプトが Connect API による権限付与（ケース C）のみを対象としている場合（例：「Account__dlm へのアクセス権を付与してください。権限セットとデータスペースのスコープはすでに設定済みです」）は、このセクションを完全にスキップし、レイヤー 2 の api-request.json のみを出力してください。

以下のコマンドは、オペレーター向けの sf CLI 呼び出し（初期状態から実行できる手順）であり、出力する成果物ではありません。通常のケース C タスクでの成果物は、前述のレイヤー 2 で説明した単一の api-request.json エンベロープです。

目標： default DataSpace 内の Account__dlm と Contact__dlm へのアクセス権を、Data_Cloud_Analyst 権限セットに付与します。

ステップ 1 — DataSpace スコープを指定して PermissionSet をデプロイ（MDAPI）：

<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Data Cloud Analyst</label>
    <description>Data cloud analyst access to the default dataspace</description>
    <hasActivationRequired>false</hasActivationRequired>
    <dataspaceScopes>
        <dataspaceScope>default</dataspaceScope>
        <dataAccessLevel>ALL</dataAccessLevel>
        <objectAccessLevel>BY_POLICY</objectAccessLevel>
    </dataspaceScopes>
</PermissionSet>

sf project deploy start --source-dir permissionsets/ --target-org <alias>

ステップ 2 — オブジェクトへのアクセス権を付与（Connect API）： （ここでは、default DataSpace に Account__dlm と Contact__dlm を対象とするガバナンスポリシーがないため、必須です。BY_POLICY ポリシーが対象オブジェクトをすでに管理している場合は、ステップ 2 をスキップしてください。レイヤー 1 のみで十分です。）

まず組織の API バージョンを解決し（上記のまず API バージョンを解決するを参照）、その後、--path の値に代入します。

API_VERSION=$(sf org display --target-org <alias> --json | jq -r '.result.apiVersion')

sf org api rest --target-org <alias> \
  --method POST \
  --path "/services/data/v${API_VERSION}/ssot/data-governance/object-access-grants/actions/bulk-create" \
  --body '{
    "permissionSetName": "Data_Cloud_Analyst",
    "dataSpaceName": "default",
    "objectApiNames": ["Account__dlm", "Contact__dlm"]
  }'

ステップ 3 — 検証：

sf org api rest --target-org <alias> \
  --path "/services/data/v${API_VERSION}/ssot/data-governance/object-access-grants?permissionSetName=Data_Cloud_Analyst&dataSpaceName=default"

---

ルールと制約

ルール	理由
親要素には<dataspaceScopes>（複数形）、子要素には<dataspaceScope>（単数形）を使用します	XML スキーマの要件です。他の名前ではデプロイに失敗します
dataAccessLevelの値はNONE、CONTROLLED_BY_PARENT、ALLのみです	他の値（例：OWNER、ViewAllRows）は拒否されます
objectAccessLevelの値はBY_POLICY、ALL_IN_DATASPACEのみです	他の値（例：READ、EDIT、Read）は拒否されます。ALL_IN_DATASPACEにはdataAccessLevel=CONTROLLED_BY_PARENTが必要です
データガバナンスポリシーがある場合は、BY_POLICYを優先してください	行や列のフィルタリングを中央ポリシーに委任できるため、オブジェクトごとの権限付与は不要です
DataSpaceごとに<dataspaceScopes>ブロックを1つ指定します	同じ権限セットに複数のDataSpaceを指定する場合は、ブロックを繰り返します
<dataspaceScopes>をデプロイするには、組織でData Cloudがプロビジョニングされている必要があります	Data Cloudがない組織では、この要素は無視されるか、拒否されます
SOQLでDataspaceScope／DataspaceScopeAccessをクエリしないでください	クエリできません。既存のスコープを確認するには、Case DのPermissionSet Metadata API取得を使用してください。代替手段としてSOQLを使用しないでください

---

注意点

問題	解決方法
エラー-379999659でデプロイに失敗する	列挙値を確認してください。dataAccessLevelはNONE／CONTROLLED_BY_PARENT／ALL、objectAccessLevelはBY_POLICY／ALL_IN_DATASPACEである必要があります
権限セットはデプロイされるが、ユーザーがDataSpaceのデータをクエリできない	レイヤー2が適用されていません。objectAccessLevel != BY_POLICYの場合、オブジェクトに明示的な権限付与が必要です
一括作成で一部のオブジェクトにAlreadyExistsが返される	冪等性があるため、安全に再試行できます。応答にはオブジェクトごとのステータスが表示されます
オブジェクト権限付与エンドポイントへのConnect APIリクエストで404が返される	組織でData Cloudがプロビジョニングされていないか、解決されたAPIバージョンが最低要件を下回っています。このエンドポイントはv67.0で導入されました。sf org display --jsonを再実行し、組織のapiVersionフィールドが67.0以降であることを確認して、その値をendpointパスに指定してください
取得したPermissionSet XMLで、デプロイ時とは異なる要素名が表示される	Metadata APIでは、取得時にレガシー名が返されることがあります。作成時には必ず現行の名前を使用してください