Eventstream REST API

Le API REST di Microsoft Fabric consentono di automatizzare procedure e processi dell'infrastruttura, aiutando l'organizzazione a completare le attività in modo più efficiente e accurato. Automatizzando questi flussi di lavoro, è possibile ridurre gli errori, migliorare la produttività e ottenere risparmi sui costi tra le operazioni.

In Infrastruttura un elemento rappresenta un set di funzionalità all'interno di un'esperienza specifica. Ad esempio, Eventstream è un elemento nell'esperienza di intelligence in tempo reale. Ogni elemento in Fabric è definito da una definizione di elemento, ovvero un oggetto che delinea la struttura, il formato e i componenti chiave che costituiscono l'elemento.

Questo articolo offre una guida completa sull'uso delle Microsoft Fabric REST APIs per creare e gestire elementi di Eventstream all'interno del workspace Fabric. Sono disponibili specifiche dettagliate per ogni operazione dell'API Eventstream, insieme alle istruzioni per la configurazione e la configurazione delle chiamate API.

Per una panoramica completa delle API REST di Microsoft Fabric, visitare: Uso delle API REST di Microsoft Fabric

API di Eventstream supportate

Attualmente, Eventstream supporta le API basate su definizioni seguenti:

Per gestire gli elementi Eventstream usando operazioni CRUD, vedere Api REST di Infrastruttura - Eventstream. Queste API supportano le operazioni seguenti:

• Creare flusso di eventi
• Elimina flusso di eventi
• Ottieni Eventstream
• Elencare flussi di eventi
• Aggiorna Eventstream

Come chiamare l'API Eventstream?

Passaggio 1: Eseguire l'autenticazione a Fabric

Per usare le API di Infrastruttura, è prima necessario ottenere un token Microsoft Entra per il servizio Fabric, quindi usare tale token nell'intestazione di autorizzazione della chiamata API. Sono disponibili due opzioni per acquisire il token Microsoft Entra.

opzione 1: Ottenere il token con MSAL.NET

Se l'applicazione deve accedere alle API di Fabric usando un'entità servizio, è possibile usare la libreria MSAL.NET per acquisire un token di accesso. Seguire la guida introduttiva all'API infrastruttura per creare un'app console C# che acquisisce un token di Azure AD usando la libreria MSAL.Net, quindi usare C# HttpClient per chiamare l'API di elenco delle aree di lavoro.

Opzione 2: Ottenere il token usando il Fabric Portal

È possibile usare il token di Azure AD per autenticare e testare le API di Infrastruttura. Accedi al Fabric Portal per il tenant su cui desideri effettuare il test e premere F12 per accedere alla modalità sviluppatore del browser. Nella console eseguire:

powerBIAccessToken

Copiare il token e incollarlo nell'applicazione.

Passaggio 2: Preparare un corpo EventStream in JSON

Creare un payload JSON che verrà convertito in base64 nella richiesta API. La definizione dell'elemento Eventstream segue una struttura simile a un grafo ed è costituita dai componenti seguenti:

Usare i modelli API in GitHub per definire il corpo Eventstream.

È possibile fare riferimento a questo documento di Swagger per informazioni dettagliate su ogni proprietà dell'API e illustra anche la definizione di un payload dell'API Eventstream.

Modalità di inserimento diretto Eventhouse

Quando si usa la modalità di inserimento diretto eventhouse come destinazione nel payload dell'API Eventstream, assicurarsi di fornire le proprietà specifiche di Eventhouse nella definizione di destinazione, ad esempio connectionName e mappingRuleName.

Per la procedura di configurazione completa, incluso come:

• creare la eventhouse,
• ottenere le proprietà del database KQL,
• creare la tabella e la regola di mappatura JSON e
• creare eventstream in modalità DirectIngestion usando le API,

vedi Creazione di un Eventstream con una destinazione DirectIngestion Eventhouse tramite API.

Per altri dettagli sulla definizione di un elemento Eventstream, consultare la sezione definizione dell'elemento Eventstream.

esempio di definizione eventstream in JSON:

{
  "sources": [
    {
      "name": "SqlServerOnVmDbCdc",
      "type": "SQLServerOnVMDBCDC",
      "properties":
      {
        "dataConnectionId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "tableName": ""
      }
    }
  ],
  "destinations": [
    {
      "name": "Lakehouse",
      "type": "Lakehouse",
      "properties":
      {
        "workspaceId": "bbbb1111-cc22-3333-44dd-555555eeeeee",
        "itemId": "cccc2222-dd33-4444-55ee-666666ffffff",
        "schema": "",
        "deltaTable": "newTable",
        "minimumRows": 100000,
        "maximumDurationInSeconds": 120,
        "inputSerialization":
        {
          "type": "Json",
          "properties":
          {
            "encoding": "UTF8"
          }
        }
      },
      "inputNodes": [{"name": "derivedStream"}]
    }
  ],
  "streams": [
    {
      "name": "myEventstream-stream",
      "type": "DefaultStream",
      "properties":
      {},
      "inputNodes": [{"name": "SqlServerOnVmDbCdc"}]
    },
    {
      "name": "derivedStream",
      "type": "DerivedStream",
      "properties":
      {
        "inputSerialization":
        {
          "type": "Json",
          "properties":
          {
            "encoding": "UTF8"
          }
        }
      },
      "inputNodes": [{"name": "GroupBy"}]
    }
  ],
  "operators": [
    {
      "name": "GroupBy",
      "type": "GroupBy",
      "inputNodes": [{"name": "myEventstream-stream"}],
      "properties":
      {
        "aggregations": [
          {
            "aggregateFunction": "Average",
            "column":
            {
              "expressionType": "ColumnReference",
              "node": null,
              "columnName": "payload",
              "columnPathSegments": [{"field": "ts_ms"}]
            },
            "alias": "AVG_ts_ms"
          }
        ],
        "groupBy": [],
        "window":
        {
          "type": "Tumbling",
          "properties":
          {
            "duration":
            {
              "value": 5,
              "unit": "Minute"
            },
            "offset":
            {
              "value": 1,
              "unit": "Minute"
            }
          }
        }
      }
    }
  ],
  "compatibilityLevel": "1.1"
}

Passaggio 3: Creare una stringa base64 di JSON Eventstream

Usare uno strumento come Codifica e decodifica Base64 per convertire il JSON di Eventstream in una stringa in base64.

Passaggio 4: Creare il corpo della richiesta API

Usare il codice JSON Eventstream con codifica Base64 nel passaggio precedente come contenuto per il corpo della richiesta API.

Ecco un esempio di payload con la stringa con codifica Base64:

{
 "definition": {
  "parts": [
   {
    "path": "eventstream.json",
    "payload": "ewogICJzb3VyY2VzIjogWwogICAgewogICAgICAibmFtZSI6ICJTcWxTZXJ2ZXJPblZtRGJDZGMiLAogICAgICAidHlwZSI6ICJTUUxTZXJ2ZXJPblZNREJDREMiLAogICAgICAicHJvcGVydGllcyI6CiAgICAgIHsKICAgICAgICAiZGF0YUNvbm5lY3Rpb25JZCI6ICJhYWFhYWFhYS0wMDAwLTExMTEtMjIyMi1iYmJiYmJiYmJiYmIiLAogICAgICAgICJ0YWJsZU5hbWUiOiAiIgogICAgICB9CiAgICB9CiAgXSwKICAiZGVzdGluYXRpb25zIjogWwogICAgewogICAgICAibmFtZSI6ICJMYWtlaG91c2UiLAogICAgICAidHlwZSI6ICJMYWtlaG91c2UiLAogICAgICAicHJvcGVydGllcyI6CiAgICAgIHsKICAgICAgICAid29ya3NwYWNlSWQiOiAiYmJiYjExMTEtY2MyMi0zMzMzLTQ0ZGQtNTU1NTU1ZWVlZWVlIiwKICAgICAgICAiaXRlbUlkIjogImNjY2MyMjIyLWRkMzMtNDQ0NC01NWVlLTY2NjY2NmZmZmZmZiIsCiAgICAgICAgInNjaGVtYSI6ICIiLAogICAgICAgICJkZWx0YVRhYmxlIjogIm5ld1RhYmxlIiwKICAgICAgICAibWluaW11bVJvd3MiOiAxMDAwMDAsCiAgICAgICAgIm1heGltdW1EdXJhdGlvbkluU2Vjb25kcyI6IDEyMCwKICAgICAgICAiaW5wdXRTZXJpYWxpemF0aW9uIjoKICAgICAgICB7CiAgICAgICAgICAidHlwZSI6ICJKc29uIiwKICAgICAgICAgICJwcm9wZXJ0aWVzIjoKICAgICAgICAgIHsKICAgICAgICAgICAgImVuY29kaW5nIjogIlVURjgiCiAgICAgICAgICB9CiAgICAgICAgfQogICAgICB9LAogICAgICAiaW5wdXROb2RlcyI6IFt7Im5hbWUiOiAiZGVyaXZlZFN0cmVhbSJ9XQogICAgfQogIF0sCiAgInN0cmVhbXMiOiBbCiAgICB7CiAgICAgICJuYW1lIjogIm15RXZlbnRzdHJlYW0tc3RyZWFtIiwKICAgICAgInR5cGUiOiAiRGVmYXVsdFN0cmVhbSIsCiAgICAgICJwcm9wZXJ0aWVzIjoKICAgICAge30sCiAgICAgICJpbnB1dE5vZGVzIjogW3sibmFtZSI6ICJTcWxTZXJ2ZXJPblZtRGJDZGMifV0KICAgIH0sCiAgICB7CiAgICAgICJuYW1lIjogImRlcml2ZWRTdHJlYW0iLAogICAgICAidHlwZSI6ICJEZXJpdmVkU3RyZWFtIiwKICAgICAgInByb3BlcnRpZXMiOgogICAgICB7CiAgICAgICAgImlucHV0U2VyaWFsaXphdGlvbiI6CiAgICAgICAgewogICAgICAgICAgInR5cGUiOiAiSnNvbiIsCiAgICAgICAgICAicHJvcGVydGllcyI6CiAgICAgICAgICB7CiAgICAgICAgICAgICJlbmNvZGluZyI6ICJVVEY4IgogICAgICAgICAgfQogICAgICAgIH0KICAgICAgfSwKICAgICAgImlucHV0Tm9kZXMiOiBbeyJuYW1lIjogIkdyb3VwQnkifV0KICAgIH0KICBdLAogICJvcGVyYXRvcnMiOiBbCiAgICB7CiAgICAgICJuYW1lIjogIkdyb3VwQnkiLAogICAgICAidHlwZSI6ICJHcm91cEJ5IiwKICAgICAgImlucHV0Tm9kZXMiOiBbeyJuYW1lIjogIm15RXZlbnRzdHJlYW0tc3RyZWFtIn1dLAogICAgICAicHJvcGVydGllcyI6CiAgICAgIHsKICAgICAgICAiYWdncmVnYXRpb25zIjogWwogICAgICAgICAgewogICAgICAgICAgICAiYWdncmVnYXRlRnVuY3Rpb24iOiAiQXZlcmFnZSIsCiAgICAgICAgICAgICJjb2x1bW4iOgogICAgICAgICAgICB7CiAgICAgICAgICAgICAgImV4cHJlc3Npb25UeXBlIjogIkNvbHVtblJlZmVyZW5jZSIsCiAgICAgICAgICAgICAgIm5vZGUiOiBudWxsLAogICAgICAgICAgICAgICJjb2x1bW5OYW1lIjogInBheWxvYWQiLAogICAgICAgICAgICAgICJjb2x1bW5QYXRoU2VnbWVudHMiOiBbeyJmaWVsZCI6ICJ0c19tcyJ9XQogICAgICAgICAgICB9LAogICAgICAgICAgICAiYWxpYXMiOiAiQVZHX3RzX21zIgogICAgICAgICAgfQogICAgICAgIF0sCiAgICAgICAgImdyb3VwQnkiOiBbXSwKICAgICAgICAid2luZG93IjoKICAgICAgICB7CiAgICAgICAgICAidHlwZSI6ICJUdW1ibGluZyIsCiAgICAgICAgICAicHJvcGVydGllcyI6CiAgICAgICAgICB7CiAgICAgICAgICAgICJkdXJhdGlvbiI6CiAgICAgICAgICAgIHsKICAgICAgICAgICAgICAidmFsdWUiOiA1LAogICAgICAgICAgICAgICJ1bml0IjogIk1pbnV0ZSIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgIm9mZnNldCI6CiAgICAgICAgICAgIHsKICAgICAgICAgICAgICAidmFsdWUiOiAxLAogICAgICAgICAgICAgICJ1bml0IjogIk1pbnV0ZSIKICAgICAgICAgICAgfQogICAgICAgICAgfQogICAgICAgIH0KICAgICAgfQogICAgfQogIF0sCiAgImNvbXBhdGliaWxpdHlMZXZlbCI6ICIxLjEiCn0=",
    "payloadType": "InlineBase64"
   },
   {
    "path": ".platform",
    "payload": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vZGV2ZWxvcGVyLm1pY3Jvc29mdC5jb20vanNvbi1zY2hlbWFzL2ZhYnJpYy9naXRJbnRlZ3JhdGlvbi9wbGF0Zm9ybVByb3BlcnRpZXMvMi4wLjAvc2NoZW1hLmpzb24iLAogICJtZXRhZGF0YSI6IHsKICAgICJ0eXBlIjogIkV2ZW50c3RyZWFtIiwKICAgICJkaXNwbGF5TmFtZSI6ICJhbGV4LWVzMSIKICB9LAogICJjb25maWciOiB7CiAgICAidmVyc2lvbiI6ICIyLjAiLAogICAgImxvZ2ljYWxJZCI6ICIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiCiAgfQp9",
    "payloadType": "InlineBase64"
   }
  ]
 }
}

Passaggio 5: Creare un elemento Eventstream usando l'API

Nella tua applicazione, invia una richiesta per creare un elemento Eventstream con la stringa codificata in Base64 nel payload.

Esempio di PowerShell :

$evenstreamAPI = "https://api.fabric.microsoft.com/v1/workspaces/$workspaceId/items" 

## Invoke the API to create the Eventstream
Invoke-RestMethod -Headers $headerParams -Method POST -Uri $evenstreamAPI -Body ($body) -ContentType "application/json"

Definizione dell'elemento Eventstream

La definizione dell'elemento Eventstream ha una struttura simile a un grafo costituita da quattro componenti: origini, destinazioni, operatori e flussi.

Origini

Per definire un'origine Eventstream nel corpo dell'API, assicurarsi che ogni campo e proprietà sia specificato correttamente in base alla tabella.

Esempio di origine Eventstream nel corpo dell'API:

{
  "sources": [
    {
      "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "name": "AzureEventHubSource",
      "type": "AzureEventHub",
      "properties":
      {
        "dataConnectionId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "consumerGroupName": "$Default",
        "inputSerialization":
        {
          "type": "Json",
          "properties":
          {
            "encoding": "UTF8"
          }
        }
      }
    }
  ]
}

Destinazioni

Per definire una destinazione Eventstream nel corpo dell'API, assicurarsi che ogni campo e proprietà sia specificato correttamente in base alla tabella.

Se utilizzi una destinazione con modalità di inserimento diretto Eventhouse, assicurati che connectionName e mappingRuleName siano specificati correttamente. Per i passaggi di configurazione end-to-end, vedere Creare un flusso di eventi con una destinazione DirectIngestion eventhouse usando le API.

Esempio di origine Eventstream nel corpo dell'API:

{
  "destinations": [
    {
      "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "name": "EventhouseDestination",
      "type": "Eventhouse",
      "properties":
      {
        "dataIngestionMode": "ProcessedIngestion",
        "workspaceId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "itemId": "cccc2222-dd33-4444-55ee-666666ffffff",
        "databaseName": "myeventhouse",
        "tableName": "mytable",
        "inputSerialization":
        {
          "type": "Json",
          "properties":
          {
            "encoding": "UTF8"
          }
        }
      },
      "inputNodes": [{"name": "eventstream-1"}]
    }
  ]
}

Operatori

Per definire un operatore Eventstream nel corpo dell'API, assicurarsi che ogni campo e proprietà sia specificato correttamente in base alla tabella.

Esempio di operatore Eventstream nel corpo dell'API:

{
  "operators": [
    {
      "name": "FilterName",
      "type": "Filter",
      "inputNodes": [{"name": "eventstream-1"}],
      "properties":
      {
        "conditions": [
          {
            "column":
            {
              "node": "nodeName",
              "columnName": "columnName",
              "columnPath": ["path","to","column"]
            },
            "operator": "Equals",
            "value":
            {
              "dataType": "nvarchar(max)",
              "value": "stringValue"
            }
          }
        ]
      }
    }
  ]
}

Flussi

Per definire un flusso nel corpo dell'API, assicurarsi che ogni campo e proprietà siano specificati correttamente in base alla tabella.

Esempio di flusso nel corpo dell'API:

{
  "streams": [
    {
      "name": "myEventstream-stream",
      "type": "DefaultStream",
      "properties":
      {},
      "inputNodes": [{"name": "sourceName"}]
    },
    {
      "name": "DerivedStreamName",
      "type": "DerivedStream",
      "properties":
      {
        "inputSerialization":
        {
          "type": "Json",
          "properties":
          {
            "encoding": "UTF8"
          }
        }
      },
      "inputNodes": [{"name": "FilterName"}]
    }
  ]
}

Contenuto correlato

• Uso delle API REST di Microsoft Fabric
• Definizione dell'elemento Eventstream