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 Anfrage 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 der untergeordneten 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.

Gerüst für die Konfiguration einer geschachtelten Abfrage

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"
        }
      }
    }
  }
}

Eigenschaften einer geschachtelten Abfrage

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 mit $incidentId$ auf den Platzhalter verweisen:

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

Die Ersetzung des Platzhalters wird in der Konfiguration der untergeordneten Schritte unterstützt, einschließlich der untergeordneten Anfragen apiEndpoint, headers, queryParameters und queryParametersTemplate.

Eigenschaften untergeordneter Anfragen konfigurieren

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

Häufige Eigenschaften untergeordneter Anfragen:

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

Gleichzeitige untergeordnete Anfragen konfigurieren

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

maxParallelism ist nicht Teil der Standardkonfiguration des übergeordneten Konnektors 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

Steuern Sie über shouldJoinNestedData, wie untergeordnete Antworten in den Datenstrom ü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 erfassen möchten.

Verwenden Sie false beispielsweise in folgenden Fällen:

• der übergeordnete Aufruf nur Vorfall-IDs zurückgibt,
• der untergeordnete Aufruf die vollständigen Vorfalldatensätze zurückgibt,
• 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 sowohl aus der übergeordneten Antwort als auch aus 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 sowohl übergeordnete als auch untergeordnete Felder der Zieltabelle zuordnen muss.

Wenn shouldJoinNestedData auf true festgelegt ist, legen Sie joinedDataStepName auf den Namen der dynamic-Spalte 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: untergeordnete Anfrage ABRUFEN

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.

Übergeordnete Antwort

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

Untergeordnete Antwort

{
  "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 Anfrage mit einem JSON-Text POSTEN

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

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

"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: Untergeordnete Anreicherungsdaten mit dem übergeordneten Datensatz verknüpfen

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.

Übergeordnete Antwort

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

Untergeordnete Antwort

{
  "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)

Authentifizierung eines untergeordneten Schritts und Paging der Feldnamen

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.

Pagingfelder

Alle anderen Paging- 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