Erstellen Sie codelose Pull-Datenkonnektoren mithilfe verschachtelter API-Abfragen

Einige REST-APIs erfordern sequenzielle Aufrufe, bei denen die Antwort von einem Endpunkt Eingaben bereitstellt, die an einen anderen Endpunkt übergeben werden müssen. Das Microsoft Sentinel Codeless Connector Framework (CCF) unterstützt dieses Muster durch verschachtelte API-Abfragen für RestApiPoller Konnektoren.

Verwenden Sie geschachtelte API-Abrufe, wenn ein übergeordneter API-Aufruf Bezeichner, Cursor oder andere Werte zurückgibt, die von einem oder mehreren untergeordneten API-Aufrufen benötigt werden. CCF extrahiert die erforderlichen Werte aus der übergeordneten Antwort, fügt sie in die untergeordnete Anfrage ein und sendet die untergeordneten Antworten an die konfigurierte Zieltabelle.

Konfigurieren Sie verschachteltes API-Polling in einem CCF-Pull-Connector, indem Sie die Verschachtelungslogik in den RestApiPoller Verbindungsregeln definieren.

Den End-to-End-Prozess zum Erstellen und Verpacken eines CCF-Connectors finden Sie unter Erstellen eines codelosen Connectors für Microsoft Sentinel. Du kannst auch die Microsoft Sentinel-Erweiterung für Visual Studio Code verwenden, um verschachtelte API-Abfrage-Workflows zu implementieren und zu testen. Informationen zur Einrichtung und Verwendung finden Sie unter Benutzerdefinierte Connectors mit KI in Microsoft Sentinel erstellen. Informationen zu den Standardanforderungs- RestApiPoller , Antwort-, Authentifizierungs-, Paging- und DCR-Eigenschaften finden Sie in der Referenz zu RestApiPoller-Datenkonnektorverbindungsregeln.

Voraussetzungen

Bevor Sie geschachtelte API-Abrufe konfigurieren, stellen Sie sicher, dass Sie Folgendes verstehen:

• Die API-Endpunkte, die der Connector aufrufen muss.
• Welche Antwortwerte aus dem übergeordneten API-Aufruf vom untergeordneten API-Aufruf benötigt werden.
• Das Ausgabeschema für die Zieltabelle.
• So erstellen Sie einen Standard-CCF-RestApiPoller-Connector.

Ein vollständiger CCF-Connector umfasst die folgenden Komponenten:

• Tabelle: Die Log Analytics benutzerdefinierte Tabelle, in der aufgenommene Daten gespeichert werden.
• DCR: Die Datensammlungsregel, die die Aufnahmetransformation definiert.
• Connector-UI: Die Datenkonnektordefinition, die im Microsoft Sentinel Inhaltshub angezeigt wird.
• Datenverbindungsregeln: Die Connectorkonfiguration, die Daten aus der Quell-API abruft.

Verschachtelte API-Abfragen werden in den Datenverbindungsregeln für einen RestApiPoller Konnektor konfiguriert.

Was ist eine geschachtelte API-Abfrage?

Die geschachtelte API-Abfrage ist ein CCF-Abrufmuster, das REST-API-Aufrufe verkettet. Der erste API-Aufruf, der als übergeordneter Schritt bezeichnet wird, gibt Werte zurück, die von späteren API-Aufrufen erforderlich sind, die als untergeordnete Schritte bezeichnet werden.

Eine API kann z. B. dieses Muster verwenden:

1. GET /incidents gibt eine Liste der Vorfall-IDs zurück.
2. GET /incidents/{incidentId}/details gibt den vollständigen Vorfalldatensatz für jede ID zurück.

Ein einzelner API-Aufruf gibt die vollständigen Daten nicht zurück. Der Connector muss den Listenendpunkt aufrufen, jeden incidentIdextrahieren und dann den Detailendpunkt einmal für jede ID aufrufen.

Verwenden Sie geschachtelte API-Abrufe in folgenden Fällen:

• Ein Listenendpunkt gibt Ressourcen-IDs zurück, und ein Detailendpunkt erfordert jede ID im URL-Pfad oder in der Abfragezeichenfolge.
• Die Antwort der übergeordneten Anfrage gibt einen Cursor, ein Sitzungstoken, eine Abfrage-ID oder eine Referenz-ID zurück, die eine untergeordnete Anfrage benötigt.
• Eine Antwort enthält ein Array von Werten, die jeweils einzeln an einen anderen Endpunkt übergeben werden müssen.
• Die übergeordnete Antwort enthält Felder, die Sie beibehalten möchten, und die untergeordnete Antwort fügt Anreicherungsdaten hinzu, die mit derselben Ausgabezeile verknüpft werden sollen.

Wenn ein einzelner API-Aufruf alle benötigten Daten zurückgibt, ist die geschachtelte API-Abfrage nicht erforderlich. Verwenden Sie die Standardeigenschaft eventsJsonPaths , um Datensätze aus der Antwort zu extrahieren.

Wie verschachteltes API-Polling funktioniert

Die geschachtelte API-Abfrage ist mit den folgenden Abschnitten konfiguriert:

Der verschachtelte Polling-Ablauf funktioniert wie folgt:

1. Die übergeordnete Anforderung wird ausgeführt.
2. Die übergeordnete Antwort wird anhand von response.eventsJsonPaths in Datensätze aufgeteilt.
3. stepPlaceholdersParsingKql extrahiert Platzhalterwerte aus jedem übergeordneten Datensatz.
4. CCF ersetzt die Platzhalter in der Konfiguration für untergeordnete Schritte.
5. CCF führt die untergeordneten Anfragen aus.
6. Die untergeordnete Antwort wird entweder als Ausgabezeile ausgegeben oder mit dem übergeordneten Datensatz verknüpft, je nach Wert von shouldJoinNestedData.

Vorlage für die geschachtelte Abfragekonfiguration

Das folgende Beispiel zeigt die Struktur eines geschachtelten Verbinders RestApiPoller . Standard CCF-Eigenschaften werden abgekürzt mit ....

{
  "kind": "RestApiPoller",
  "properties": {
    "connectorDefinitionName": "...",
    "dcrConfig": { },
    "dataType": "...",
    "auth": { },
    "request": {
      "apiEndpoint": "https://api.example.com/incidents",
      "httpMethod": "GET",
      "queryWindowInMin": 60,
      "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
      "startTimeAttributeName": "startTime",
      "endTimeAttributeName": "endTime"
    },
    "response": {
      "eventsJsonPaths": [ "$.incidents" ],
      "format": "json"
    },
    "stepInfo": {
      "stepType": "Nested",
      "nextSteps": [
        {
          "stepId": "fetchIncidentDetails",
          "stepPlaceholdersParsingKql": "source | project res = parse_json(data) | project incidentId = res.incidentId"
        }
      ]
    },
    "stepCollectorConfigs": {
      "fetchIncidentDetails": {
        "shouldJoinNestedData": false,
        "request": {
          "httpMethod": "GET",
          "apiEndpoint": "https://api.example.com/incidents/$incidentId$/details"
        },
        "response": {
          "eventsJsonPaths": [ "$" ],
          "format": "json"
        }
      }
    }
  }
}

Verschachtelte Abfrageeigenschaften

Ersetzung von Platzhaltern

Platzhalter werden mit stepPlaceholdersParsingKql extrahiert und mit der Syntax $placeholderName$ referenziert.

Dieser KQL erstellt z. B. einen Platzhalter mit dem Namen incidentId:

source
| project res = parse_json(data)
| project incidentId = res.incidentId

Der untergeordnete Schritt kann dann den Platzhalter als $incidentId$ referenzieren:

"apiEndpoint": "https://api.example.com/incidents/$incidentId$/details"

Die Platzhaltersubstitution wird in der Konfiguration der untergeordneten Schritte unterstützt, einschließlich der untergeordneten Anforderung apiEndpoint, headers, queryParameters und queryParametersTemplate.

Eigenschaften untergeordneter Anfragen konfigurieren

Der Block request in einem untergeordneten Schritt unterstützt die allgemeinen Anfrageeigenschaften, die für API-Polling verwendet werden.

Zu den häufigen Eigenschaften untergeordneter Anforderungen gehören:

Die übergeordnete Anforderung steuert das Abfragezeitfenster. Konfigurieren Sie Zeitfenstereigenschaften wie queryWindowInMin, queryTimeFormat, startTimeAttributeName und endTimeAttributeName nur in der übergeordneten Anforderung. Untergeordnete Schritte werden in der Regel durch Platzhalterwerte gesteuert, die aus der übergeordneten Antwort extrahiert wurden.

Parallelität untergeordneter Anfragen konfigurieren

maxParallelism steuert, wie viele untergeordnete Anrufe gleichzeitig ausgeführt werden können. Der Standardwert ist 15.

maxParallelism ist nicht Teil der standardmäßigen konfiguration des übergeordneten Connectors und kann nicht für den übergeordneten Schritt festgelegt werden. Da untergeordnete Schritte ohne Übersetzung der Feldnamen weitergegeben werden, können Sie maxParallelism innerhalb des request-Blocks eines untergeordneten Schritts festlegen, wenn eine Anpassung erforderlich ist.

"stepCollectorConfigs": {
  "fetchIncidentDetails": {
    "shouldJoinNestedData": false,
    "request": {
      "httpMethod": "GET",
      "apiEndpoint": "https://api.contoso.com/incidents/$incidentId$/details",
      "maxParallelism": 15
    },
    "response": {
      "eventsJsonPaths": [ "$" ],
      "format": "json"
    }
  }
}

Auswählen, ob übergeordnete und untergeordnete Daten verknüpft werden sollen

Verwenden Sie shouldJoinNestedData, um zu steuern, wie Antworten von untergeordneten Elementen in den Stream übertragen werden.

shouldJoinNestedData: false verwenden

Setzen Sie shouldJoinNestedData auf false, wenn die übergeordnete Antwort nur die für die untergeordnete Anfrage erforderlichen Werte bereitstellt und die untergeordnete Antwort den vollständigen Datensatz enthält, den Sie importieren möchten.

Verwenden Sie false beispielsweise in folgenden Fällen:

• Der übergeordnete Aufruf gibt nur Incident-IDs zurück.
• Der untergeordnete Anruf gibt die vollständigen Vorfalldatensätze zurück.
• Sie müssen keine übergeordneten Felder in der Zielzeile beibehalten.

"stepCollectorConfigs": {
  "fetchIncidentDetails": {
    "shouldJoinNestedData": false,
    "request": {
      "httpMethod": "GET",
      "apiEndpoint": "https://api.contoso.com/incidents/$incidentId$/details"
    },
    "response": {
      "eventsJsonPaths": [ "$" ],
      "format": "json"
    }
  }
}

shouldJoinNestedData: true verwenden

Legen Sie shouldJoinNestedData auf true fest, wenn Sie Felder aus der übergeordneten Antwort und der untergeordneten Antwort in derselben Zielzeile benötigen.

Verwenden Sie true beispielsweise in folgenden Fällen:

• Der übergeordnete Aufruf gibt Warnungsfelder wie Warnungs-ID, Schweregrad und Erkennungszeitpunkt zurück.
• Der untergeordnete Aufruf gibt Anreicherungsfelder wie betroffener Benutzer, Quell-IP oder Geolokalisierung zurück.
• Die DCR-Transformation muss sowohl übergeordnete als auch untergeordnete Felder der Zieltabelle zuordnen.

Wenn shouldJoinNestedDatatrue ist, legen Sie joinedDataStepName auf den Namen der Spalte dynamic fest, in der die untergeordnete Antwort gespeichert wird.

"stepCollectorConfigs": {
  "fetchAlertEnrichment": {
    "shouldJoinNestedData": true,
    "joinedDataStepName": "enrichment",
    "request": {
      "httpMethod": "GET",
      "apiEndpoint": "https://api.contoso.com/alerts/$alertId$/enrichment"
    },
    "response": {
      "eventsJsonPaths": [ "$" ],
      "format": "json"
    }
  }
}

Beispiel: GET-Unteranforderung

In diesem Beispiel kommt eine zweistufige Contoso-Vorfall-API zum Einsatz:

1. Die übergeordnete Anfrage ruft GET /incidents auf und empfängt eine Liste von Incident-IDs.
2. stepPlaceholdersParsingKql extrahiert incidentId aus jedem übergeordneten Datensatz.
3. Die untergeordnete Anfrage ruft GET /incidents/$incidentId$/details einmal pro Vorfall-ID auf.
4. Die untergeordneten Antworten werden als flache Datensätze an den Datenstrom gesendet.

Antwort der übergeordneten Ebene

{
  "incidents": [
    { "incidentId": "INC-001" },
    { "incidentId": "INC-002" },
    { "incidentId": "INC-003" }
  ]
}

Unterantwort

{
  "incidentId": "INC-001",
  "title": "Suspicious login attempt",
  "severity": "High",
  "status": "Active",
  "createdAt": "2026-05-30T14:22:00Z",
  "affectedUser": "alice@contoso.com",
  "sourceIp": "198.51.100.42"
}

Abstimmungskonfiguration

{
  "kind": "RestApiPoller",
  "properties": {
    "connectorDefinitionName": "ContosoIncidentsConnector",
    "dcrConfig": {
      "dataCollectionEndpoint": "{{dataCollectionEndpoint}}",
      "dataCollectionRuleImmutableId": "{{dataCollectionRuleImmutableId}}",
      "streamName": "Custom-ContosoIncidents_CL"
    },
    "dataType": "ContosoIncidents_CL",
    "auth": {
      "type": "APIKey",
      "ApiKey": "{{apiKey}}",
      "ApiKeyName": "x-functions-key"
    },
    "request": {
      "apiEndpoint": "https://api.contoso.com/incidents",
      "httpMethod": "GET",
      "queryWindowInMin": 60,
      "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
      "startTimeAttributeName": "startTime",
      "endTimeAttributeName": "endTime",
      "headers": {
        "Accept": "application/json"
      }
    },
    "response": {
      "eventsJsonPaths": [ "$.incidents" ],
      "format": "json"
    },
    "stepInfo": {
      "stepType": "Nested",
      "nextSteps": [
        {
          "stepId": "fetchIncidentDetails",
          "stepPlaceholdersParsingKql": "source | project res = parse_json(data) | project incidentId = res.incidentId"
        }
      ]
    },
    "stepCollectorConfigs": {
      "fetchIncidentDetails": {
        "shouldJoinNestedData": false,
        "request": {
          "httpMethod": "GET",
          "apiEndpoint": "https://api.contoso.com/incidents/$incidentId$/details",
          "headers": {
            "Accept": "application/json"
          },
          "retryCount": 3,
          "timeoutInSeconds": 60
        },
        "response": {
          "eventsJsonPaths": [ "$" ],
          "format": "json"
        }
      }
    }
  }
}

Beispiel: Untergeordnete POST-Anfrage mit JSON-Text

Einige APIs erfordern, dass Bezeichner aus der übergeordneten Response im Body einer POST-Anfrage gesendet werden, statt im URL-Pfad oder in der Abfragezeichenfolge. Verwenden Sie queryParametersTemplate mit isPostPayloadJson für dieses Muster.

In diesem Beispiel gibt die übergeordnete Antwort ein incidentId zurück, und die untergeordnete Anfrage sendet diesen Wert in einem JSON-POST-Body.

"stepCollectorConfigs": {
  "fetchIncidentDetails": {
    "shouldJoinNestedData": false,
    "request": {
      "httpMethod": "POST",
      "apiEndpoint": "https://api.contoso.com/incidents/details:batchGet",
      "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
      },
      "queryParametersTemplate": "{'ids': ['$incidentId$']}",
      "isPostPayloadJson": true,
      "retryCount": 3,
      "timeoutInSeconds": 60
    },
    "response": {
      "eventsJsonPaths": [ "$.items" ],
      "format": "json"
    }
  }
}

Beispiel: Verknüpfen untergeordneter Anreicherungsdaten mit dem übergeordneten Datensatz

In diesem Beispiel wird eine Contoso-Warnungs-API verwendet, in der die übergeordnete Antwort Felder enthält, die beibehalten werden sollen, und die untergeordnete Antwort Daten zur Anreicherung enthält.

Antwort der übergeordneten Ebene

{
  "alerts": [
    {
      "alertId": "ALT-001",
      "severity": "High",
      "detectedAt": "2026-05-30T14:22:00Z",
      "riskScore": 92
    }
  ]
}

Unterantwort

{
  "alertId": "ALT-001",
  "affectedUser": "bob@contoso.com",
  "sourceIp": "198.51.100.77",
  "geolocation": "US/Virginia",
  "relatedIncidentId": "INC-042"
}

Abstimmungskonfiguration

{
  "kind": "RestApiPoller",
  "properties": {
    "connectorDefinitionName": "ContosoAlertsConnector",
    "dcrConfig": {
      "dataCollectionEndpoint": "{{dataCollectionEndpoint}}",
      "dataCollectionRuleImmutableId": "{{dataCollectionRuleImmutableId}}",
      "streamName": "Custom-ContosoAlerts_CL"
    },
    "dataType": "ContosoAlerts_CL",
    "auth": {
      "type": "APIKey",
      "ApiKey": "{{apiKey}}",
      "ApiKeyName": "x-functions-key"
    },
    "request": {
      "apiEndpoint": "https://api.contoso.com/alerts",
      "httpMethod": "GET",
      "queryWindowInMin": 60,
      "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
      "startTimeAttributeName": "startTime",
      "endTimeAttributeName": "endTime"
    },
    "response": {
      "eventsJsonPaths": [ "$.alerts" ],
      "format": "json"
    },
    "stepInfo": {
      "stepType": "Nested",
      "nextSteps": [
        {
          "stepId": "fetchAlertEnrichment",
          "stepPlaceholdersParsingKql": "source | project res = parse_json(data) | project alertId = res.alertId"
        }
      ]
    },
    "stepCollectorConfigs": {
      "fetchAlertEnrichment": {
        "shouldJoinNestedData": true,
        "joinedDataStepName": "enrichment",
        "request": {
          "httpMethod": "GET",
          "apiEndpoint": "https://api.contoso.com/alerts/$alertId$/enrichment"
        },
        "response": {
          "eventsJsonPaths": [ "$" ],
          "format": "json"
        }
      }
    }
  }
}

Die DCR-Transformation kann dann Felder aus dem übergeordneten Datensatz und der verknüpften untergeordneten Antwort projizieren.

Beispiel:

source
| extend enrichment = todynamic(enrichment)
| project
    TimeGenerated = todatetime(detectedAt),
    AlertId = tostring(alertId),
    Severity = tostring(severity),
    RiskScore = toint(riskScore),
    AffectedUser = tostring(enrichment.affectedUser),
    SourceIp = tostring(enrichment.sourceIp),
    Geolocation = tostring(enrichment.geolocation),
    RelatedIncidentId = tostring(enrichment.relatedIncidentId)

Feldnamen für die Authentifizierung und Paginierung untergeordneter Schritte

Die Feldnamenübersetzung gilt nur für den übergeordneten Schritt. Jeder Eintrag in stepCollectorConfigs wird unverändert weitergereicht und nicht neu zugeordnet. Daher muss jeder auth- oder paging-Block innerhalb eines untergeordneten Schritts die in den folgenden Tabellen aufgeführten Feldnamen des untergeordneten Schritts verwenden.

Authentifizierungsfelder

Bei OAuth2 wird der FlowName Wert ebenfalls transformiert. Verwenden Sie ClientCredentials z. B. anstelle von client_credentials, und AuthCode anstelle von authorization_code.

Paginierungsfelder

Alle anderen Seiten- und Antwortfeldnamen sind für übergeordnete und untergeordnete Schritte identisch.

Limits

Die geschachtelte API-Abfrage weist die folgenden Grenzwerte auf:

Vervollständigen Sie den Steckverbinder

Nachdem Sie die geschachtelten RestApiPoller Verbindungsregeln konfiguriert haben, schließen Sie die verbleibenden CCF-Connectorkomponenten ab:

• Erstellen oder aktualisieren Sie die Zieltabelle.
• Erstellen Sie den DCR und die Transformation.
• Erstellen Sie die Connector-UI-Definition.
• Verpacken Sie den Konnektor in einer ARM-Bereitstellungsvorlage.
• Stellen Sie den Connector bereit, und testen Sie ihn.

Informationen zum End-to-End-Prozess finden Sie unter Erstellen eines codelosen Connectors für Microsoft Sentinel.

Verwandte Inhalte

• Erstellen eines codelosen Connectors für Microsoft Sentinel
• Referenz zu RestApiPoller-Datenkonnektorverbindungsregeln
• Referenz zu Datenkonnektor-UI-Definitionen