eventstream-authoring-cli

by microsoft

Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding. npx skills add https://github.com/microsoft/skills-for-fabric --skill eventstream-authoring-cli Download ZIPGitHub716

Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the check-updates skill.

• Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version.

• Skip if the check was already performed earlier in this session.

CRITICAL NOTES

• To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering

• To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

• Eventstream ≠ Eventhouse. Eventstream is a real-time event ingestion and routing pipeline. For KQL database operations, use eventhouse-authoring-cli or eventhouse-consumption-cli.

Eventstream Authoring — CLI Skill

Table of Contents

Task Reference Notes Finding Workspaces and Items in Fabric COMMON-CLI.md § Finding Workspaces and Items in Fabric Mandatory — READ link first [needed for finding workspace id by its name or item id by its name, item type, and workspace id] Fabric Topology & Key Concepts COMMON-CORE.md § Fabric Topology & Key Concepts Environment URLs COMMON-CORE.md § Environment URLs Authentication & Token Acquisition COMMON-CORE.md § Authentication & Token Acquisition Wrong audience = 401; read before any auth issue Core Control-Plane REST APIs COMMON-CORE.md § Core Control-Plane REST APIs Includes pagination, LRO polling, and rate-limiting patterns Gotchas, Best Practices & Troubleshooting COMMON-CORE.md § Gotchas, Best Practices & Troubleshooting Tool Selection Rationale COMMON-CLI.md § Tool Selection Rationale Authentication Recipes COMMON-CLI.md § Authentication Recipes az login flows and token acquisition Fabric Control-Plane API via az rest COMMON-CLI.md § Fabric Control-Plane API via az rest Always pass --resource; includes pagination and LRO helpers Gotchas & Troubleshooting (CLI-Specific) COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific) az rest audience, shell escaping, token expiry Quick Reference COMMON-CLI.md § Quick Reference az rest template + token audience/tool matrix Eventstream Resource Model EVENTSTREAM-AUTHORING-CORE.md § Eventstream Resource Model Read first — graph-based topology with sources, operators, streams, destinations Source Configuration EVENTSTREAM-AUTHORING-CORE.md § Source Configuration 25 API-supported source types with per-source properties Transformation Operators EVENTSTREAM-AUTHORING-CORE.md § Transformation Operators 8 operator types: Filter, Aggregate, GroupBy, Join, ManageFields, Union, Expand, SQL Destination Configuration EVENTSTREAM-AUTHORING-CORE.md § Destination Configuration 4 API-supported destination types with node schema Stream Types EVENTSTREAM-AUTHORING-CORE.md § Stream Types DefaultStream (auto) and DerivedStream (from operators) Eventstream Lifecycle (REST API) EVENTSTREAM-AUTHORING-CORE.md § Eventstream Lifecycle (REST API) CRUD + Definition endpoints Item Definitions and Deployment EVENTSTREAM-AUTHORING-CORE.md § Item Definitions and Deployment Base64 encoding pattern for eventstream.json Gotchas and Limitations EVENTSTREAM-AUTHORING-CORE.md § Gotchas and Limitations Max 11 custom endpoints, base64 encoding, naming constraints Create an Eventstream SKILL.md § Create an Eventstream Deploy Full Topology SKILL.md § Deploy Full Topology End-to-end: build topology JSON → base64 encode → submit definition Update Eventstream Topology SKILL.md § Update Eventstream Topology Delete an Eventstream SKILL.md § Delete an Eventstream Gotchas, Rules, Troubleshooting SKILL.md § Gotchas, Rules, Troubleshooting MUST DO / AVOID / PREFER checklists

Create an Eventstream

Create an empty Eventstream item, then configure it with sources, destinations, and operators via the definition API.

Step 1: Create the Item

az rest --method POST \
 --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventstreams" \
 --resource "https://api.fabric.microsoft.com" \
 --headers "Content-Type=application/json" \
 --body '{"displayName": "my-eventstream", "description": "IoT sensor pipeline"}'

Save the returned id as EVENTSTREAM_ID.

Step 2: Build the Topology

Construct the eventstream.json topology with sources, streams, operators, and destinations. Each node references its upstream via inputNodes.

Prefer building the JSON programmatically to avoid serialization errors. Key rules:

• The topology must have exactly one DefaultStream — all sources feed into it via inputNodes

• Operators reference their input via inputNodes[].name

• DerivedStreams require inputSerialization in properties

• Destinations reference their input stream or operator

Step 3: Deploy the Definition

Base64-encode the topology JSON and submit via the definition API. See Item Definitions and Deployment for the full payload structure.

Update Eventstream Topology

• Get current definition: POST /v1/workspaces/{wsId}/eventstreams/{esId}/getDefinition

• Decode the eventstream.json payload from base64

• Modify the topology (add/remove/update nodes)

• Re-encode to base64

• Submit: POST /v1/workspaces/{wsId}/eventstreams/{esId}/updateDefinition

API Note: The Eventstream Definition APIs use POST with action verbs (getDefinition, updateDefinition), not GET/PUT on a /definition resource. This follows the Fabric Items Definition pattern. See official docs.

The Update Definition API returns 202 Accepted for long-running operations. Poll the Location header URL until completion.

Adding a Filter Operator

⚠️ CRITICAL: Filter operator conditions use nested objects for column and value — NOT bare strings. Using "column": "temperature" instead of the object form below will cause a silent API rejection.

{
 "name": "FilterHighTemp",
 "type": "Filter",
 "inputNodes": [{"name": "my-stream"}],
 "properties": {
 "conditions": [{
 "column": {
 "node": null,
 "columnName": "temperature",
 "columnPath": null,
 "expressionType": "ColumnReference"
 },
 "operatorType": "GreaterThan",
 "value": {
 "dataType": "Float",
 "value": "30.0",
 "expressionType": "Literal"
 }
 }]
 }
}

Required structure for ALL operator condition fields:

• column → object with {node, columnName, columnPath, expressionType: "ColumnReference"}

• value → object with {dataType, value, expressionType: "Literal"}

• operatorType → string: GreaterThan, LessThan, Equals, NotEquals, GreaterThanOrEqual, LessThanOrEqual

• dataType → Float, Int, Long, String, DateTime

This same nested-object pattern applies to all operators that reference columns (Filter, Aggregate, GroupBy, Join, ManageFields).

Delete an Eventstream

az rest --method DELETE \
 --url "https://api.fabric.microsoft.com/v1/workspaces/${WORKSPACE_ID}/eventstreams/${EVENTSTREAM_ID}" \
 --resource "https://api.fabric.microsoft.com"

Returns 200 OK on success.