activator-authoring-cli

更新チェック — セッションごとに1回（必須） このスキルをセッションで初めて使用する際は、先に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出してください（例：/fabric-skills:check-updates）。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルの package.json のバージョンを読み取り、git fetch origin main --quiet && git show origin/main:package.json（または GitHub API）でリモートのバージョンと比較してください。リモートのバージョンのほうが新しい場合は、変更履歴と更新手順を表示してください。
• このセッション中にすでにチェックを実行している場合はスキップしてください。

重要事項

1. ワークスペース名から詳細（ID を含む）を調べるには、すべてのワークスペースを一覧表示してから、JMESPath でフィルタリングしてください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を調べるには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath でフィルタリングしてください。

activator-authoring-cli — CLI による Activator アイテムとルールの作成

目次

タスク	リファレンス	備考
Fabric でのワークスペースとアイテムの検索	COMMON-CLI.md § Finding Workspaces and Items in Fabric	必須 — 先にリンクを読むこと［ワークスペース／アイテム ID の解決に必要］
認証とトークンの取得	COMMON-CORE.md § Authentication & Token Acquisition	Audience が異なると 401 になります
認証の手順	COMMON-CLI.md § Authentication Recipes	共通ドキュメントの az login／トークンに関するガイダンスを使用してください
コア コントロールプレーン REST API	COMMON-CORE.md § Core Control-Plane REST APIs	ワークスペースの一覧表示、アイテムの一覧表示、アイテムの作成
長時間実行操作（LRO）	COMMON-CORE.md § Long-Running Operations (LRO)	Create、getDefinition、updateDefinition は 202 を返す場合があります
Fabric アイテム定義	ITEM-DEFINITIONS-CORE.md § Definition Envelope	Base64 エンコードされたパーツの構造
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § Fabric Control-Plane API via az rest	必ず --resource https://api.fabric.microsoft.com を渡してください
LRO パターン	COMMON-CLI.md § Long-Running Operations (LRO) Pattern	202 レスポンスをポーリングします
エンティティの種類、ソース、ビュー	source-types.md	エンティティのエンベロープ、ソースエンティティ、timeSeriesView-v1 のバリエーション
Eventstream ソース	eventstream-source.md	プッシュソースのワークフロー：先に Eventstream シンクを作成し、その後、検出された Activator エンティティを拡張します
KQL ソース	kql-source.md	KQL ソースのスキーマ、時間軸のサポート、設計ガイダンス
Digital Twin Builder／Ontology ソース	dtb-source.md	DTB／Ontology ソースのスキーマ、JSON 文字列形式のクエリペイロード、スナップショットと時間軸に関するガイダンス
Real-time Hub ソース	real-time-hub-source.md	Real-time Hub ソースのスキーマ、ワークスペースのイベントの種類
Power BI ソース	powerbi-source.md	powerBiSource-v1、保存済みクエリペイロード、DatasetMetric、フィルター、永続化、ALM の読み戻しの制限
ルールの条件	rule-conditions.md	ルールテンプレートの構造、検出条件、集計、時間枠、発生オプション、エンリッチメント
アクションの種類	action-types.md	TeamsMessage、EmailMessage、FabricItemInvocation のアクションスキーマ

---

ツールスタック

ツール	用途
az CLI	Fabric 認証および REST API トークンの取得
curl	共有の fabric_lro ヘルパーを使用した、ヘッダー対応の Fabric REST 呼び出し
jq	JSON のフィルタリングと、デコードした定義の確認
python	ReflexEntities.json の構築に必ず使用してください — json.dumps() はネストされた文字列化を正しく処理します。PowerShell の ConvertTo-Json はネストされた JSON 文字列を破損させます。

⚠️ 重要：ReflexEntities.json のペイロードと API リクエスト本文の構築には、必ず Python（PowerShell ではなく）を使用してください。

Python のパターン

import json, base64, uuid

# Stringify template → JSON string for definition.instance
instance_string = json.dumps(template_dict, separators=(',', ':'))

# Encode entities and write updateDefinition request body
payload_b64 = base64.b64encode(json.dumps(entities).encode('utf-8')).decode('utf-8')
body = json.dumps({"definition": {"parts": [{"path": "ReflexEntities.json", "payload": payload_b64, "payloadType": "InlineBase64"}]}})
with open('update-body.json', 'w', encoding='utf-8') as f:
    f.write(body)
# Then: az rest --method POST --url "...updateDefinition" --resource "https://api.fabric.microsoft.com" --body @update-body.json

# Decode a getDefinition response
response = json.loads(api_output)
for part in response['definition']['parts']:
    if part['path'] == 'ReflexEntities.json':
        entities = json.loads(base64.b64decode(part['payload']).decode('utf-8'))

# Generate GUIDs for uniqueIdentifier and step id fields
entity_id = str(uuid.uuid4())

---

接続

COMMON-CLI.md § Authentication Recipes に記載されている共通の認証ガイダンスを使用してください。COMMON-CLI.md § Finding Workspaces and Items in Fabric に従ってワークスペース ID とアイテム ID を解決してください。以下の例では、WS_ID と REFLEX_ID がすでに解決済みであることを前提としています。

---

アイテムの CRUD

COMMON-CLI.md § Item CRUD Operations に記載されている共通の方法を使用してください。Activator では、汎用の items エンドポイントではなく、reflexes エンドポイントを使用します。

操作	エンドポイント	メソッド	スコープ	備考
作成	/v1/workspaces/{workspaceId}/reflexes	POST	Reflex.ReadWrite.All または Item.ReadWrite.All	202 LRO が返される場合があります — COMMON-CLI の fabric_lro を使用してください
メタデータの更新	/v1/workspaces/{workspaceId}/reflexes/{reflexId}	PATCH	Reflex.ReadWrite.All または Item.ReadWrite.All	COMMON-CLI のメタデータ更新パターンに従ってください
削除	/v1/workspaces/{workspaceId}/reflexes/{reflexId}	DELETE	Reflex.ReadWrite.All または Item.ReadWrite.All	完全に削除するには ?hardDelete=true を追加してください
getDefinition	/v1/workspaces/{workspaceId}/reflexes/{reflexId}/getDefinition	POST	Reflex.ReadWrite.All または Item.ReadWrite.All	空の本文が必要です。202 LRO が返される場合があります — fabric_lro を使用してください
updateDefinition	/v1/workspaces/{workspaceId}/reflexes/{reflexId}/updateDefinition	POST	Reflex.ReadWrite.All または Item.ReadWrite.All	Python で update-body.json を構築し、COMMON-CLI の updateDefinition パターンに従ってください

---

定義によるルール管理

ルールは getDefinition と updateDefinition を使用して管理します。ペイロードは、エンティティオブジェクトの JSON 配列を Base64 エンコードした ReflexEntities.json です。ワークフロー：取得 → デコード → 変更 → 再エンコード → 更新。

定義の取得

getDefinition は GET ではなく POST であり、ReadWrite スコープが必要です。また、202 LRO が返される場合があります。202 レスポンスをデコードする前に Location ヘッダー経由でポーリングできるよう、COMMON-CLI.md § Long-Running Operations (LRO) Pattern の fabric_lro ヘルパーを使用してください。

DEFINITION=$(fabric_lro POST \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/reflexes/${REFLEX_ID}/getDefinition" \
  '{}')

echo "$DEFINITION" \
  | jq '.definition.parts[] | select(.path=="ReflexEntities.json") | .payload' -r \
  | base64 -d | jq .

定義の更新

update-body.json の構築には必ず Python を使用し（Python のパターンを参照）、/v1/workspaces/{workspaceId}/reflexes/{reflexId}/updateDefinition に対して COMMON-CLI の updateDefinition パターンを使用してアップロードしてください。

ReflexEntities.json — 組み立て手順

エンティティを順番に JSON 配列として構築します。それぞれの uniqueIdentifier には、新しい GUID が必要です。このスキルで手作業で作成するプルソースのフローには、templateVersion 1.2.4 を使用してください。Eventstream シンクによって作成されたフローでは、デコードした Activator 定義にすでに含まれているテンプレートバージョンを維持してください。これらの読み戻しでは 1.1 が使用される場合があります。

ステップ 1 — コンテナー（1 つのみ）：

• 種類：container-v1。ソースグラフに一致するコンテナーペイロードの種類を使用してください。KQL ソースには kqlQueries、Real-Time Hub のワークスペースサブスクリプションには rthSubscriptions、Power BI ソースには大文字と小文字を区別する正確な pbiMetrics、Eventstream フローには読み戻しにすでに存在するサービス作成の種類を使用します。
• その他すべてのエンティティは、parentContainer.targetUniqueIdentifier を介してこれを参照します ステップ 2 — データソース（正確に 1 つ。適切な種類を選択してください）：
• サポートされているソースのワークフローについては、eventstream-source.md、kql-source.md、dtb-source.md、real-time-hub-source.md、または powerbi-source.md を参照してください
• 手動作成するプルソースでは、parentContainer.targetUniqueIdentifier → コンテナー GUID を設定します
• eventstreamSource-v1 の場合：ソースを手動作成することから始めないでください。先に Activator 宛先を指定して Eventstream を作成または更新し、その後 Activator 定義を読み取って、自動作成された eventstreamSource-v1 と SourceEvent エンティティを使って作業を続けます。公開される読み取り結果では、これらのシンクによって作成されたエンティティに明示的な parentContainer が含まれない場合があります。
• kqlSource-v1 の場合：KQL クエリはすべてのデータを返す必要があります（条件で事前にフィルターしないでください。ルールに処理させます）。eventhouseItem、metadata、queryParameters を含める必要があります。Fabric Eventhouse／KQL DB ソースでは、eventhouseItem: { itemId, workspaceId, itemType: "KustoDatabase" } を使用します。外部 ADX／Kusto ソースでは、eventhouseItem: { clusterHostName, databaseName } を使用します。Activator を作成する前に、対象ソースに対して KQL を直接実行し、返される列、タイムスタンプフィールド、行の構造が正しいことを確認してください。 クエリ結果に妥当なタイムスタンプ列がある場合は、eventTimeSettings と DURATION_START／DURATION_END のクエリパラメーターを使用し、KQL で declare query_parameters(startTime:datetime, endTime:datetime); を宣言してください。 スナップショットモード（queryParameters: []、eventTimeSettings なし、時間フィルターなし）を使用するのは、基になるデータに妥当なタイムスタンプ列がなく、各行が現在の状態を表す場合に限ります。kql-source.md を参照してください。
• digitalTwinBuilderSource-v1 の場合：DTB／Ontology の connection アイテム参照 { itemId, workspaceId, itemType } を使用します。itemType は DigitalTwinBuilder または Ontology のいずれかです。query.queryString は KQL ではなく、JSON 文字列形式のペイロードである必要があります。Activator を作成する前に、DTB／Ontology のクエリを直接実行し、返される列、キー項目、タイムスタンプフィールドが正しいことを確認してください。 返される行に妥当なタイムスタンプフィールドが含まれる場合は、eventTimeSettings と DURATION_START／DURATION_END のクエリパラメーターを使用してください。KQL とは異なり、これらの期間パラメーターはクエリ本文内で参照されるのではなく、DTB エンドポイントの URL クエリパラメーターとして適用されます。dtb-source.md を参照してください。
• powerBiSource-v1 の場合：対象を絞ったレポート／ページ／ビジュアルとセマンティックモデルのメタデータから、ソースを決定的に構築します。親コンテナーには、payload.type: "pbiMetrics" を正確に指定する必要があります。ソースクエリのペイロードは JSON テキストとして query.queryString に保存し、一致する DatasetMetric を metricDefinition に保存します。updateDefinition で永続化し、明示的な HTTP 200（または LRO の最終的な成功）を必須とし、インポートエラーが発生した場合は処理を中止します。powerbi-source.md を参照してください。

ステップ 3 — SourceEvent ビュー（正確に 1 つ）：

• 種類：timeSeriesView-v1、definition.type: "Event"、Source を entityId で参照する SourceEvent テンプレートインスタンス
• 手動作成するプルソースのワークフローでは、parentContainer → コンテナー GUID を設定します
• Eventstream のシンクによって作成されるワークフローでは、2 つ目を作成せず、読み取り結果から自動作成された SourceEvent を再利用します

ステップ 4 — トリガーの種類に基づいてエンティティグラフを選択します

• AttributeTrigger ルールの場合（しきい値、範囲、テキスト一致、ブール値のチェック、集計）：
  • Object ビューを作成します
  • イベントをオブジェクトインスタンスにマッピングする必要がある場合は、SplitEvent を作成します（任意）
  • IdentityPartAttribute と、必要な BasicEventAttribute エンティティを作成します
  • ルールはこれらの値属性を ScalarSelectStep で参照します
• EventTrigger ルールの場合（すべてのイベント、ハートビート、イベントフィールドの状態／変更で発火）：
  • 最小限のグラフを使用します：Container → Source → SourceEvent → Rule（＋任意の fabricItemAction-v1）
  • 属性ベースのモデリングがシナリオ上、本当に必要な場合を除き、Object、SplitEvent、IdentityPartAttribute、BasicEventAttribute エンティティは作成しないでください
  • FieldsDefaultsStep には、ネストされた EventReference.entityId が SourceEvent エンティティを参照する EventSelector 行が必要です。トップレベルの EventReference 行は無効です。
  • EventTrigger は、FieldsDefaultsStep／EventDetectStep でイベントの生フィールドを直接読み取ります

ステップ 5 — Rule（アラートごとに 1 つ）：

• 型：timeSeriesView-v1、definition.type："Rule"
• ユーザーにわかりやすくするため、必ず "description": "Created by: skills-for-fabric" を追加してください
• インスタンス：ルールテンプレート（rule-conditions.md を参照）
  • AttributeTrigger（v1.2.4）：ScalarSelectStep → ScalarDetectStep →（DimensionalFilterStep）* → ActStep
  • EventTrigger（v1.2.4）：FieldsDefaultsStep →（EventDetectStep）+ →（DimensionalFilterStep）* → ActStep
• instance は 必ず JSON 文字列にしてください（json.dumps() を使用）
• instance.steps[] 内の各テンプレートステップには id GUID が必要です。ステップ ID がない場合、バックエンドのトランスレーターがステップ ID を出力ノード ID として使用するため、無効な式グラフが生成されることがあります。
• AttributeTrigger の場合は、parentObject に Object を、parentContainer に Container を設定します
• EventTrigger の場合は、parentContainer に Container を設定し、設計上明示的に必要でない限り parentObject は省略します
• 新しく作成されたルールが started / running 状態で開始するよう、既定では settings: { "shouldRun": true, "shouldApplyRuleOnUpdate": false } を設定します
• shouldRun: false を設定するのは、ユーザーが停止中のルールを明示的に求めた場合、または副作用を避けるため、特定の安全な検証／評価ワークフローで無効なルールが必要な場合に限ります
• 動的コンテンツを含む TeamsMessage アクションでは、正常に読み戻されたデータにあるフィールド固有の参照形式を維持します。headline／optionalMessage 内のインラインの混在コンテンツフラグメントでは、type: "complex" の AttributeReference を使用します。一方、構造化された additionalInformation エントリでは、type: "complexReference" および name: "reference" の NameReferencePair ＋ AttributeReference／EventFieldReference を使用します。

ルールエンティティの例：

{
    "uniqueIdentifier": "<rule-guid>",
    "payload": {
        "name": "My Rule Name",
        "description": "Created by: skills-for-fabric",  # Required for user clarity
        "parentObject": {"targetUniqueIdentifier": "<object-guid>"},
        "parentContainer": {"targetUniqueIdentifier": "<container-guid>"},
        "definition": {
            "type": "Rule",
            "instance": stringify_instance(rule_template),
            "settings": {"shouldRun": True, "shouldApplyRuleOnUpdate": False}
        }
    },
    "type": "timeSeriesView-v1"
}

ステップ 6 — Fabric Item Action（FabricItemInvocation の場合のみ）：

• 型：fabricItemAction-v1 — ルールが Pipeline、Notebook、Spark ジョブ定義、Dataflow、UDF／Function Set などの Fabric アイテムを呼び出す場合は、常にこのスタンドアロンのアクションエンティティを使用します
• ルールの FabricItemBinding では、fabricJobConnectionDocumentId にスタンドアロンの fabricItemAction-v1.uniqueIdentifier を設定します
• ターゲットごとのスキーマと UDF 固有の注意事項（itemType と読み戻し時の FunctionSet の違い、subitemId、正規の parameterType マッピング、動的パラメーターの形式）については、action-types.md を参照してください

参照整合性の事前チェック

updateDefinition を実行する前に、送信する正確なエンティティ配列を検証してください：

1. ReflexEntities.json 内のすべてのトップレベル uniqueIdentifier のセットを構築します。
2. すべての parentContainer.targetUniqueIdentifier、parentObject.targetUniqueIdentifier、SourceReference.entityId、EventReference.entityId、AttributeReference.entityId、および fabricJobConnectionDocumentId が、同じ配列内のエンティティ（または再エンコードされた配列に含まれる、最新のデコード済み読み戻しからの未変更エンティティ）に解決されることを確認します。
3. 各参照が期待されるエンティティ型を指していることを確認します：コンテナは container-v1、テンプレートがビューを期待する場合の source/event/attribute/rule/object 参照は timeSeriesView-v1、source 参照はソースエンティティ、Fabric アイテムアクションバインディングは fabricItemAction-v1 です。
4. 参照が見つからない場合は、最新の getDefinition 出力からグラフを再構築し、updateDefinition を呼び出さないでください。

DocumentType timeSeriesView not found を伴う FailedToResolveEntity は、ルール、属性、スプリットイベント、またはイベント参照が、送信された定義に存在しない timeSeriesView-v1 GUID を指していることを意味します。これは一時的なバックエンド障害ではなく、再試行する前に修正すべきエンティティ配線のバグとして扱ってください。

エンティティ配線の概要

Container ← everything references this via parentContainer
    │
    ├── Source ← parentContainer → Container
    │
    ├── SourceEvent ← parentContainer → Container
    │        │         instance references Source by entityId
    │        │
    │        ├── EventTrigger Rule ← parentContainer → Container
    │        │       minimal event-only path; reads raw event fields directly
    │        │
    │        └── Object ← parentContainer → Container
    │              │
    │              ├── (SplitEvent) ← OPTIONAL, parentObject → Object, parentContainer → Container
    │              │       instance references SourceEvent by entityId
    │              │       maps events to objects via FieldIdMapping
    │              │
    │              ├── Identity Attr ← parentObject → Object, parentContainer → Container
    │              │
    │              ├── Value Attr(s) ← parentObject → Object, parentContainer → Container
    │              │       instance references SourceEvent (or SplitEvent if used) by entityId
    │              │
    │              └── AttributeTrigger Rule ← parentObject → Object, parentContainer → Container
    │                      instance references Value Attr by entityId in ScalarSelectStep
    │
    └── (FabricItemAction) ← parentContainer → Container (for any FabricItemInvocation action: Pipeline, Notebook, Spark job, Dataflow, or UDF / Function Set)

重要: definition.instance は JSON 文字列です

timeSeriesView-v1 エンティティの definition 内の instance は、ネストされたオブジェクトではなく、JSON エンコードされた文字列です。ルールテンプレートは常に完全なエンティティエンベロープでラップしてください。

❌ 誤り — 生のテンプレートオブジェクト（失敗します）:

{
  "templateId": "AttributeTrigger",
  "templateVersion": "1.2.4",
  "steps": [...]
}

✅ 正しい — 文字列化された instance を含むエンティティエンベロープ:

{
  "uniqueIdentifier": "<new-guid>",
  "payload": {
    "name": "My Rule Name",
    "parentObject": { "targetUniqueIdentifier": "<object-guid>" },
      "parentContainer": { "targetUniqueIdentifier": "<container-guid>" },
      "definition": {
        "type": "Rule",
        "instance": "{\"templateId\":\"AttributeTrigger\",\"templateVersion\":\"1.2.4\",\"steps\":[...]}",
        "settings": { "shouldRun": true, "shouldApplyRuleOnUpdate": false }
      }
    },
    "type": "timeSeriesView-v1"
}

文字列化には json.dumps() を使用してください。PowerShell の ConvertTo-Json は使用しないでください。

2 種類のルールテンプレート

テンプレート	使用する場合	ステップ
AttributeTrigger	属性値（数値、テキスト、ブール値）を監視する	ScalarSelectStep → ScalarDetectStep → (DimensionalFilterStep)* → ActStep
EventTrigger	イベントの発生（状態、変化、ハートビート）で発火する	FieldsDefaultsStep → (EventDetectStep)+ → (DimensionalFilterStep)* → ActStep

EventTrigger には ScalarSelectStep/ScalarDetectStep はありません。イベントを直接処理する場合に使用します。EventDetectStep を介した状態、変化、ハートビートの検出をサポートします。

---

ソース検証ゲート

シグナル（測定値、フィールド、またはイベントプロパティ）を参照するあらゆるルールを作成する前に、ソースが実在することを確認してください。要求されたソースは、次の 3 つのチェックをすべて通過した後にのみ実在すると見なされます：

1. 要求されたワークスペースのみでソースを解決する -- 別のワークスペースを検索したり代用したりしないでください。
2. 要求されたシグナルの列/フィールドがそのソースに存在することを検証する（KQL テーブル/列、Eventstream フィールド、Real-Time Hub イベントプロパティ、または DTB / Ontology プロパティ）。
3. そのシグナルを持つ代表的な行/イベント/サンプルを少なくとも 1 つ観測する -- KQL / DTB クエリを実行するかストリームを検査し、実際にデータが返されることを確認してください。

スキーマのみ、行数ゼロ、非出力、または古い証拠は、実在するソースではなくソースデータの欠落として扱ってください。ソースが欠落している場合は、停止して質問し、どのソースとフィールドがシグナルを提供するか（加えて、欠落しているしきい値、受信者、またはアクションの詳細）を確認してください。既存の Activator / Eventstream に対して Reflex を作成したり updateDefinition を呼び出したりして要求を無理に適合させないでください。また、Activator / Reflex / Eventstream は作成も更新もされなかったことを明確に述べてください。唯一の例外は、ユーザーが将来の / まだ出力されていないソースに対して作成するよう明示的に指示した場合です。

---

必須 / 推奨 / 回避

必ず実施すること

• 作成前に実際のソースを確認する — ソース検証ゲートに従い、要求されたワークスペース内でソースを特定し、要求されたシグナル列／フィールドを検証してから、代表的な行／イベント／サンプルを少なくとも1つ確認してください。スキーマしかない場合、行が0件の場合、データが出力されていない場合、または証拠が古い場合は、ソースデータが不足しています。作業を中止して確認してください。どのソースとフィールドが必要か（不足しているしきい値、受信者、アクションの詳細も含む）を尋ね、ルールを作成する代わりに、Activator／Reflex／Eventstreamを作成も更新もしていないことを伝えてください。ユーザーが将来のソース、またはまだデータが出力されていないソースに対する作成を明示的に指示した場合は、その前提を伝えて続行し、ソースを確認済みであるとは主張しないでください。
• az restでは必ず--resource https://api.fabric.microsoft.comを使用する — これを指定しないと、トークンのオーディエンスが正しくありません。
• getDefinitionでは必ず--body '{}'を送信する — これはPOSTであり、ボディを省略すると411エラーが発生することがあります。
• updateDefinitionを呼び出す際は、ReflexEntities.jsonのペイロードを必ずBase64エンコードする。
• timeSeriesView-v1エンティティのdefinition.instanceフィールドは、必ずJSON.stringifyで文字列化する — 入れ子のオブジェクトではなく、文字列である必要があります。ルールテンプレートは必ず完全なエンティティエンベロープで囲む（上記の❌／✅の例を参照）— エンティティラッパーのないテンプレートオブジェクトをそのまま出力しないでください。
• 必ず正しいテンプレートタイプを使用する — 値ベースの条件にはAttributeTrigger（ScalarSelectStepとScalarDetectStepを含む）、イベントベースの発火にはEventTrigger（FieldsDefaultsStepとEventDetectStepを含み、ScalarDetectStepは含まない）。
• 必ず正規のEventTriggerセレクターを使用する — FieldsDefaultsStep.rowsには、複合型のEventReferenceを入れ子にしたEventSelector（kind: Event）を含めます。EventReferenceをrowsに直接入れないでください。
• エンティティ追加時は、uniqueIdentifierに必ず新しいGUIDを使用する — GUIDが重複すると破損の原因になります。
• uniqueIdentifierを変更する場合は、必ずすべての相互参照を更新する — 他のエンティティはtargetUniqueIdentifierを介して参照しています。
• updateDefinitionの前に、必ず参照整合性の事前チェックを実行する — ペイロード内のすべてのtargetUniqueIdentifier、entityId、fabricJobConnectionDocumentIdが、送信するReflexEntities.jsonに含まれるエンティティに解決される必要があります。
• LROレスポンスを処理する — create、getDefinition、updateDefinitionが202を返す場合があります。Locationヘッダーをポーリングしてください。

推奨事項

• 全置換より読み取り・変更・書き込みを優先する — 現在の定義を取得し、エンティティ配列を変更してから更新します。
• 完全な削除を意図している場合を除き、ハード削除より論理削除を優先する。
• GUIDをハードコードするのではなく、ワークスペース一覧表示とJMESPathを使ってIDを動的に検出する。
• ほとんどのアラートでは、定常状態の条件より状態遷移に基づくアラート条件を優先する — ユーザーが「より大きい」「より小さい」「範囲外」といった、状態を示すカジュアルな表現を使った場合も、NumberBecomes、NumberEntersOrLeavesRange、LogicalBecomesなどの検出器や、明示的な変化条件を優先してください。条件が真のままの間に通知が繰り返されないよう、一般的なアラート表現は「その状態に移行したときに通知する」と解釈してください。
• IsGreaterThan、IsLessThan、IsOutsideRangeなどの定常状態の条件は、値が発火状態にある間、繰り返し発火するようユーザーが明示的に求めた場合に限り使用してください。たとえば「30より大きいときは毎回通知して」「30を超えている間は評価のたびに発火して」と指定された場合や、後続の発生／ウィンドウ処理のパターンでその意味が真に必要な場合です。

避けるべきこと

• ワークスペース ID やアイテム ID のハードコーディング — 常に動的に解決してください
• .platform 部分を忘れること — ?updateMetadata=true を使用する場合にのみ、updateDefinition に含めてください
• 一覧エンドポイントでフィルターなしの SELECT * を使用すること — 大規模なワークスペースではページネーションを使用してください
• 暗号化された機密ラベルが付いたアイテムの定義を変更すること — getDefinition はブロックされます
• KQL クエリで条件を事前にフィルターすること — KQL からすべてのデータを返し、しきい値、テキスト条件、ディメンションフィルターは Activator のルールステップで処理してください。KQL はデータソースであり、ルールエンジンではありません
• PowerShell の az rest --body に JSON をインラインで記述すること — PowerShell は引用符や特殊文字を正しく処理できません。常に [System.IO.File]::WriteAllText($path, $json, [System.Text.UTF8Encoding]::new($false)) を使って一時ファイルに JSON を書き込み、--body @$path を渡してください
• 削除後に表示名を再利用すること — 論理削除されたアイテムは数分間名前を保持します。固有の名前を使うか、先に完全削除してください
• 無関係な既存アイテムにリクエストを無理に当てはめること — ソース検証ゲートを通過するソースがない場合（ソースがない、スキーマのみ、行数が 0、イベントを出力しない、または古い）、リクエストを満たすために Reflex を作成したり、無関係な既存の Activator／Eventstream に対して updateDefinition を呼び出したりしないでください。まず不足しているソースを確認してください
• 読み取り専用の一覧表示や検査 — 「すべての Activator を表示して」「Activator を一覧表示して」「ルールを表示して」「このアラートを調べて」「定義をデコードして」などのリクエストには、activator-consumption-cli を使用してください。このオーサリングスキルは、ユーザーが作成、更新、削除、設定、または変更を依頼した場合にのみ実行してください

---

例

アセンブリ手順に従って定義を作成してください。エンティティスキーマの全容については、リファレンスドキュメントを参照してください：source-types.md、rule-conditions.md、action-types.md。

---

エージェント統合に関する注意事項

• このスキルでは、CRUD に Fabric Items API（/reflexes）を、ルール管理に Definition API を使用します
• 追加のデータプレーンプロトコルは不要です。すべての操作で Fabric API オーディエンスを指定した az rest を使用します
• Activator アイテムとルールを読み取るだけで変更しない場合は、代わりに activator-consumption-cli スキルを使用してください