Opret en eventstream med en eventhouse direkte indlæsningsdestination ved hjælp af API'er

Denne artikel giver en trin-for-trin guide til at oprette en Eventstream med en Eventhouse DirectIngesti-destination ved hjælp af API'er.

Du gennemfører tre trin:

Forudsætninger

• Du har adgang til et arbejdsområde med kapaciteten Fabric eller Fabric Prøve arbejdsområde med bidragyder eller højere tilladelser.

Autentificering og tilladelseskrav

For at arbejde med Fabric API'er, hent først et Microsoft Entra ID-token til Fabric-tjenesten, og brug derefter dette token i autorisationsheaderen i API-kaldet. Du kan få et Fabric-token ved at bruge MSAL.NET.

Hent token ved hjælp af MSAL.NET

Hvis dit program skal have adgang til Fabric-API'er ved hjælp af en tjenesteprincipal, kan du bruge biblioteket MSAL.NET til at hente et adgangstoken. Følg Fabric API quickstart for at oprette en C#-konsolapp, som erhverver et Microsoft Entra ID-token ved at bruge MSAL.NET-biblioteket og derefter bruger C# HttpClient til at kalde List Workspaces API'en.

Trin 1: Opret Eventhouse via API

API-adresse og parametre

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/eventhouses

Tegn

Authorization: Bearer <fabric_access_token>
Content-Type: application/json

Nyttedata

Brug en minimal payload til at skabe Eventhouse-genstanden.

{
  "displayName": "es-eh-demo"
}

Hvis du har brug for avancerede provisioning by definition-dele, brug Eventhouse definitionskontrakten i referencedokumentationen.

Svareksempel

{
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "Eventhouse",
  "displayName": "es-eh-demo",
  "description": "",
  "workspaceId": "00000000-0000-0000-0000-000000000000"
}

Fang værdien for de næste trin:

• Eventhouse item ID (id)

Trin 2: Opret en KQL-database med tabel og mapping i definitionen

Brug Fabric REST API'en til at oprette KQL-databasen med dens skema-definition i et enkelt kald. Dette trin bruger kun Fabric API-endepunkterne (ingen Eventhouse-administrations-endpointkald er nødvendige). Den nye database tilføjes automatisk til Eventhouse fra trin 1 via parentEventhouseItemId, og tabellen samt indlæsningsmappingen er defineret i DatabaseSchema.kql.

API-adresse og parametre

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/kqlDatabases

Tegn

Authorization: Bearer <fabric_access_token>
Content-Type: application/json

Definitionsdele

Forbered to definitionsdele:

• DatabaseProperties.json: Binder databasen til Eventhouse fra trin 1 ved hjælp af parentEventhouseItemId feltet (dette er nøgleforbindelsen mellem din database og eventhouse).
• DatabaseSchema.kql: Definerer og opretter KQL-tabelstrukturen og indlæsningsmapping, som automatisk kører, når databasen oprettes.

DatabaseProperties.json Eksempel:

{
  "databaseType": "ReadWrite",
  "parentEventhouseItemId": "<eventhouseItemId>",
  "oneLakeCachingPeriod": "P36500D",
  "oneLakeStandardStoragePeriod": "P36500D"
}

DatabaseSchema.kql Eksempel:

.create-merge table Orders (id:string, eventTime:datetime, amount:real)
.create-or-alter table Orders ingestion json mapping 'orders_json_map' "[{\"column\":\"id\",\"Properties\":{\"path\":\"$.id\"}},{\"column\":\"eventTime\",\"Properties\":{\"path\":\"$.eventTime\"}},{\"column\":\"amount\",\"Properties\":{\"path\":\"$.amount\"}}]"

Kod definitionsdele til Base64

$databaseProperties = @'
{
  "databaseType": "ReadWrite",
  "parentEventhouseItemId": "<eventhouseItemId>",
  "oneLakeCachingPeriod": "P36500D",
  "oneLakeStandardStoragePeriod": "P36500D"
}
'@

$databaseSchema = @'
.create-merge table Orders (id:string, eventTime:datetime, amount:real)
.create-or-alter table Orders ingestion json mapping 'orders_json_map' "[{\"column\":\"id\",\"Properties\":{\"path\":\"$.id\"}},{\"column\":\"eventTime\",\"Properties\":{\"path\":\"$.eventTime\"}},{\"column\":\"amount\",\"Properties\":{\"path\":\"$.amount\"}}]"
'@

$base64DatabaseProperties = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($databaseProperties))
$base64DatabaseSchema = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($databaseSchema))

Anmod om nyttedata

{
  "displayName": "es-kql-demo",
  "description": "KQL database created by API with schema definition",
  "definition": {
    "parts": [
      {
        "path": "DatabaseProperties.json",
        "payload": "<base64DatabaseProperties>",
        "payloadType": "InlineBase64"
      },
      {
        "path": "DatabaseSchema.kql",
        "payload": "<base64DatabaseSchema>",
        "payloadType": "InlineBase64"
      }
    ]
  }
}

Svar

API'et returnerer 202 Accepted med en Location header for denne langvarige operation. Poll endpointet i Location headeren for at tjekke, hvornår operationen er færdig.

Når operationen lykkes, oprettes KQL-databasen med tabellen Orders og JSON-indlæsningsmappingen orders_json_map allerede konfigureret.

Fang disse værdier for trin 3:

• tableName: Orders
• mappingRuleName: orders_json_map

Trin 3: Opret Eventstream i DirectIngestion-tilstand

API-adresse og parametre

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

Eventstream-topologi-nyttelast

Denne prøvelast bruges SampleData som kilde og Eventhouse DirectIngestion destination. Hold destinationsegenskaberne i overensstemmelse med din API-version.

Topologien definerer tre komponenter:

Sørg for, at og itemIdworkspaceId i din destination matcher Eventhouse fra trin 1, og at og tableName matcher mappingRuleName det, du har oprettet i trin 2.

{
  "sources": [
    {
      "name": "sample-data-source",
      "type": "SampleData",
      "properties": {
        "type": "StockMarket"
      }
    }
  ],
  "destinations": [
    {
      "name": "eventhouse-direct-ingestion",
      "type": "Eventhouse",
      "properties": {
        "dataIngestionMode": "DirectIngestion",
        "workspaceId": "<eventhouseWorkspaceId>",
        "itemId": "<eventhouseItemId>",
        "tableName": "Orders",
        "connectionName": "es-eh-conn-7f3a",
        "mappingRuleName": "orders_json_map"
      },
      "inputNodes": [
        {
          "name": "eventstream-main-stream"
        }
      ]
    }
  ],
  "streams": [
    {
      "name": "eventstream-main-stream",
      "type": "DefaultStream",
      "properties": {},
      "inputNodes": [
        {
          "name": "sample-data-source"
        }
      ]
    }
  ],
  "operators": [],
  "compatibilityLevel": "1.1"
}

Destinationsfelter brugt i DirectIngesti-tilstand:

Kod topologien til Base64

$json = Get-Content -Path "eventstream.json" -Raw
$bytes = [System.Text.Encoding]::UTF8.GetBytes($json)
$base64Eventstream = [Convert]::ToBase64String($bytes)

Eksempelanmodning

Eksempelforespørgslen indeholder en payload med to Base64-kodede definitionsdele: eventstream.json (topologien, du definerede ovenfor) og .platform (metadatafil, påkrævet for alle Fabric elementer).

{
  "displayName": "es-directingest-demo",
  "type": "Eventstream",
  "description": "Eventstream created by API in DirectIngestion mode",
  "definition": {
    "parts": [
      {
        "path": "eventstream.json",
        "payload": "<base64Eventstream>",
        "payloadType": "InlineBase64"
      },
      {
        "path": ".platform",
        "payload": "<base64Platform>",
        "payloadType": "InlineBase64"
      }
    ]
  }
}

For at generere din egen .platform nyttelastværdi, gør følgende:

1. Opret en .platform fil ved at bruge formatet, der vises i Create Eventstream-elementet med definition.
2. Base64-kod hele .platform filindholdet ved at bruge samme tilgang som vist i Encode the topology to Base64.
3. Brug den kodede streng som værdi for feltet payload , og erstat <base64Platform> i eksempelforespørgslen.

Eksempel:

{
  "path": ".platform",
  "payload": "ewogICIkc2NoZW1hIjogImh0dHBzOi8vZGV2ZWxvcGVyLm1pY3Jvc29mdC5jb20vanNvbi1zY2hlbWFzL2ZhYnJpYy9naXRJbnRlZ3JhdGlvbi9wbGF0Zm9ybVByb3BlcnRpZXMvMi4wLjAvc2NoZW1hLmpzb24iLAogICJtZXRhZGF0YSI6IHsKICAgICJ0eXBlIjogIkV2ZW50c3RyZWFtIiwKICAgICJkaXNwbGF5TmFtZSI6ICJhbGV4LWVzMSIKICB9LAogICJjb25maWciOiB7CiAgICAidmVyc2lvbiI6ICIyLjAiLAogICAgImxvZ2ljYWxJZCI6ICIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiCiAgfQp9",
  "payloadType": "InlineBase64"
}

Eksempelsvar

202 Accepted

API'et returnerer 202 Accepted for denne langvarige operation. Afhængigt af klienten kan responsteksten være tom eller indeholde en bogstavelig null. Hvis svaret indeholder en Location header, brug den til at polle for operationens fuldførelse.

Tjekliste fra ende til ende

1. Få et Fabric-token (aud = https://api.fabric.microsoft.com).
2. Opret Eventhouse og fang workspaceId og itemId.
3. Opret en KQL-database med DatabaseProperties.json og DatabaseSchema.kql.
4. Byg og Base64-kode eventstream.json.
5. Opret Eventstream med en Eventhouse DirectIngesti-destination.

Referencer

• Eventhouse create API
• definition af eventhouse
• Opret KQL database API
• KQL-databasedefinition
• Opret item API (til Eventstream)
• Eksempel på eventstream-definitionsskabelon

Relateret indhold

• Opret Eventstream-element med definition
• Få Eventstream-definitionen
• Opdater Eventstream-definitionen
• Eventstream REST API