RestApiPoller-Datenconnectorreferenz für das Codeless Connector Framework

Sie können einen RestApiPoller Datenconnector mit dem Codeless Connector Framework (CCF) erstellen, indem Sie diesen Artikel als Ergänzung zur Dokumentation zur Microsoft Sentinel REST-API für Datenconnectors verwenden.

Jeder Datenconnector stellt eine bestimmte Verbindung eines Microsoft Sentinel-Datenconnectors dar. Ein Datenconnector kann über mehrere Verbindungen verfügen, die Daten von verschiedenen Endpunkten abrufen. Sie können die Bereitstellungsvorlage für den CCF-Datenconnector mithilfe der JSON-Konfiguration abschließen, die Sie mit diesem Artikel erstellen.

Weitere Informationen finden Sie unter Erstellen eines Connectors ohne Code für Microsoft Sentinel.

Erstellen oder Aktualisieren von Datenconnectors

Suchen Sie die neueste stabile oder Vorschauversion der API, indem Sie auf die create Vorgänge oder update in der REST-API-Dokumentation verweisen. Der Unterschied zwischen den Vorgängen create und update besteht darin, dass update der etag -Wert erforderlich ist.

PUT Methode:

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectors/{{dataConnectorId}}?api-version={{apiVersion}}

URI-Parameter

Weitere Informationen zur neuesten API-Version finden Sie unter Datenconnectors: Erstellen oder Aktualisieren von URI-Parametern.

Anforderungstext

Der Anforderungstext für einen RestApiPoller CCF-Datenconnector weist die folgende Struktur auf:

{
   "name": "{{dataConnectorId}}",
   "kind": "RestApiPoller",
   "etag": "",
   "properties": {
        "connectorDefinitionName": "",
        "auth": {},
        "request": {},
        "response": {},
        "paging": "",
        "dcrConfig": ""
   }
}

RestApiPoller

RestApiPoller ist ein API-Abruf-CCF-Datenconnector, mit dem Sie Paging, Autorisierung und Anforderungs-/Antwortnutzlasten für Ihre Datenquelle anpassen können.

Authentifizierungskonfiguration

Die CCF unterstützt die folgenden Authentifizierungstypen:

• Basic
• API-Schlüssel
• OAuth2
• JWT

Als bewährte Methode sollten Sie Parameter im Authentifizierungsabschnitt verwenden, anstatt Anmeldeinformationen hart zu codieren. Weitere Informationen finden Sie unter Schützen vertraulicher Eingaben.

Zum Erstellen der Bereitstellungsvorlage, die auch Parameter verwendet, müssen Sie die Parameter in diesem Abschnitt mit einem zusätzlichen Startzeichen versehen [. In diesem Schritt können die Parameter einen Wert basierend auf der Benutzerinteraktion mit dem Connector zuweisen. Weitere Informationen finden Sie unter Escapezeichen für Vorlagenausdrücke.

Damit die Anmeldeinformationen über die Benutzeroberfläche eingegeben werden können, connectorUIConfig müssen Sie im Abschnitt die gewünschten Parameter in instructionseingeben. Weitere Informationen finden Sie unter Referenz zu Datenconnectordefinitionen für das Codeless Connector Framework.

Standardauthentifizierung

Hier sehen Sie ein Beispiel für die Standardauthentifizierung, die in connectorUIconfigdefinierte Parameter verwendet:

"auth": {
    "type": "Basic",
    "UserName": "[[parameters('username')]",
    "Password": "[[parameters('password')]"
}

API-Schlüssel

APIKey Authentifizierungsbeispiele:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

Das Ergebnis dieses Beispiels ist das Geheimnis, das aus der Benutzereingabe definiert wird, die im folgenden Header gesendet wird: X-MyApp-Auth-Header: Bearer apikey.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

In diesem Beispiel werden die Standardwerte verwendet und der folgende Header zurückgegeben: Authorization: token 123123123.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

Da ApiKeyName explizit auf ""festgelegt ist, ist das Ergebnis der folgende Header: Authorization: 123123123.

OAuth2

Das Codeless Connector Framework unterstützt die OAuth 2.0-Autorisierungscodezuweisung und Clientanmeldeinformationen. Der Autorisierungscode-Gewährungstyp wird von vertraulichen und öffentlichen Clients verwendet, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen.

Nachdem der Benutzer über die Umleitungs-URL zum Client zurückkehrt, ruft die Anwendung den Autorisierungscode von der URL ab und verwendet ihn, um ein Zugriffstoken anzufordern.

Sie können den Authentifizierungscodeflow verwenden, um Daten im Namen der Berechtigungen eines Benutzers abzurufen. Sie können Clientanmeldeinformationen verwenden, um Daten mit Anwendungsberechtigungen abzurufen. Der Datenserver gewährt Zugriff auf die Anwendung. Da es keinen Benutzer im Clientanmeldeinformationsflow gibt, ist kein Autorisierungsendpunkt erforderlich, nur ein Tokenendpunkt.

Hier sehen Sie ein Beispiel für den OAuth2-Gewährungstyp authorization_code :

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "authorizationEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize",
    "authorizationEndpointHeaders": {},
    "authorizationEndpointQueryParameters": {
        "prompt": "consent"
    },
    "redirectUri": "https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "authorization_code"
}

Hier sehen Sie ein Beispiel für den OAuth2-Gewährungstyp client_credentials :

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

JWT

Die JSON-Webtokenauthentifizierung (JWT) unterstützt das Abrufen von Token über Benutzernamen- und Kennwortanmeldeinformationen und deren Verwendung für API-Anforderungen.

Einfaches Beispiel

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password", 
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://token_endpoint.contoso.com",
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

Anmeldeinformationen im POST-Text (Standard)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password",
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://api.example.com/token",
    "Headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    "IsCredentialsInHeaders": false,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

Anmeldeinformationen in Headern (Standardauthentifizierung)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "client_id",
        "value": "[[parameters('ClientId')]"
    },
    "password": {
        "key": "client_secret",
        "value": "[[parameters('ClientSecret')]"
    },
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "IsCredentialsInHeaders": true,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token",
    "RequestTimeoutInSeconds": 30
}

Anmeldeinformationen in Headern (Benutzertoken)

"auth": {
    "type": "JwtToken",
    "UserToken": "[[parameters('userToken')]",
    "UserTokenPrepend": "Bearer",
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "TokenEndpointHttpMethod": "GET",
    "NoAccessTokenPrepend": true,
    "JwtTokenJsonPath": "$.systemToken"
}

Befolgen Sie diesen Authentifizierungsflow:

1. Senden von Anmeldeinformationen an TokenEndpoint zum Abrufen des JWT-Tokens, wenn userName und passwordverwendet wird, IsCredentialsInHeaders wird verwendet, um zu bestimmen, wo Anmeldeinformationen in die Anforderung eingefügt werden sollen.

   • Wenn IsCredentialsInHeaders: true: Sendet einen Standardauthentifizierungsheader mit username:password.
   • Wenn IsCredentialsInHeaders: false: Sendet Anmeldeinformationen in einem POST Textkörper.

2. Extrahieren Sie das Token mithilfe JwtTokenJsonPath von oder aus dem Antwortheader.

3. Der Autorisierungsheader für die JWT-Token ist eine Konstante und lautet immer "Authorization".

Anforderungskonfiguration

Im Anforderungsabschnitt wird definiert, wie der CCF-Datenconnector Anforderungen an Ihre Datenquelle sendet (z. B. den API-Endpunkt und wie oft dieser Endpunkt abgerufen werden soll).

Wenn die API komplexe Parameter erfordert, verwenden Sie queryParameters oder queryParametersTemplate. Diese Befehle enthalten einige integrierte Variablen.

StartTimeAttributeName-Beispiel

Betrachten Sie dieses Beispiel:

• StartTimeAttributeName = from
• EndTimeAttributeName = until
• ApiEndpoint = https://www.example.com

Die Abfrage, die an den Remoteserver gesendet wird, lautet: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

QueryTimeIntervalAttributeName-Beispiel

Betrachten Sie dieses Beispiel:

• QueryTimeIntervalAttributeName = interval
• QueryTimeIntervalPrepend = time:
• QueryTimeIntervalDelimiter = ..
• ApiEndpoint = https://www.example.com

Die Abfrage, die an den Remoteserver gesendet wird, lautet: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

RateLimitConfig-Beispiel

Betrachten Sie dieses Beispiel:

ApiEndpoint = https://www.example.com.

"rateLimitConfig": {
  "evaluation": {
    "checkMode": "OnlyWhen429"
  },
  "extraction": {
    "source": "CustomHeaders",
    "headers": {
      "limit": {
        "name": "X-RateLimit-Limit",
        "format": "Integer"
      },
      "remaining": {
        "name": "X-RateLimit-Remaining",
        "format": "Integer"
      },
      "reset": {
        "name": "X-RateLimit-RetryAfter",
        "format": "UnixTimeSeconds"
      }
    }
  },
  "retryStrategy": {
    "useResetOrRetryAfterHeaders": true
  }
}

Wenn die Antwort Ratenbegrenzungsheader enthält, kann der Connector diese Informationen verwenden, um seine Anforderungsrate anzupassen.

Anfordern von Beispielen, die Microsoft Graph als Datenquellen-API verwenden

In diesem Beispiel werden Nachrichten mit einem Filterabfrageparameter abfragt. Weitere Informationen finden Sie unter Microsoft Graph-API-Abfrageparameter.

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Example-app-agent"
  },
  "QueryTimeIntervalAttributeName": "filter",
  "QueryTimeIntervalPrepend": "receivedDateTime gt ",
  "QueryTimeIntervalDelimiter": " and receivedDateTime lt "
}

Im vorherigen Beispiel wird eine GET Anforderung an https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000gesendet. Der Zeitstempel wird für jedes queryWindowInMin Mal aktualisiert.

Mit diesem Beispiel erzielen Sie die gleichen Ergebnisse:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "queryParameters": {
    "filter": "receivedDateTime gt {_QueryWindowStartTime} and receivedDateTime lt {_QueryWindowEndTime}"
  }
}

Es gibt eine weitere Option für Situationen, in der die Datenquelle zwei Abfrageparameter erwartet (einen für die Startzeit und einen für die Endzeit).

Beispiel:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/calendarView",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "StartTimeAttributeName": "startDateTime",
  "EndTimeAttributeName": "endDateTime",
}

Diese Option sendet eine GET Anforderung an https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Verwenden Sie QueryParametersTemplatefür komplexe Abfragen . In diesem Beispiel wird eine POST Anforderung mit Parametern im Text gesendet:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "POST",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "isPostPayloadJson": true,
  "queryParametersTemplate": "{\"query":"TableName | where createdTimestamp between (datetime({_QueryWindowStartTime}) .. datetime({_QueryWindowEndTime}))\"}"
}

Antwortkonfiguration

Definieren Sie, wie Ihr Datenconnector Antworten verarbeitet, indem Sie die folgenden Parameter verwenden:

Antwortkonfigurationsbeispiele

Es wird eine Serverantwort im JSON-Format erwartet. Die Antwort enthält die angeforderten Daten im Eigenschaftswert. Die Antworteigenschaft status gibt an, dass die Daten nur erfasst werden, wenn der Wert istsuccess.

"response": {
  "EventsJsonPaths ": ["$.value"],
  "format": "json",
  "SuccessStatusJsonPath": "$.status",
  "SuccessStatusValue": "success",
  "IsGzipCompressed": true
 }

Die erwartete Antwort in diesem Beispiel bereitet eine CSV-Datei ohne Header vor.

"response": {
  "EventsJsonPaths ": ["$"],
  "format": "csv",
  "HasCsvHeader": false
 }

Pagingkonfiguration

Wenn die Datenquelle nicht die gesamte Antwortnutzlast auf einmal senden kann, muss der CCF-Datenconnector wissen, wie Teile der Daten auf Antwortseiten empfangen werden. Folgende Pagingtypen stehen zur Auswahl:

Konfigurieren von LinkHeader oder PersistentLinkHeader

Der häufigste Pagingtyp ist, wenn eine Serverdatenquellen-API URLs für die nächste und vorherige Datenseite bereitstellt. Weitere Informationen zur Linkheaderspezifikation finden Sie unter RFC 5988.

LinkHeader Paging bedeutet, dass die API-Antwort eine der folgenden Optionen enthält:

• Der Link HTTP-Antwortheader.
• Ein JSON-Pfad zum Abrufen des Links aus dem Antworttext.

PersistentLinkHeader-type paging hat die gleichen Eigenschaften wie LinkHeader, mit der Ausnahme, dass der Linkheader im Back-End-Speicher beibehalten wird. Diese Option ermöglicht das Auslagern von Links über Abfragefenster hinweg.

Einige APIs unterstützen beispielsweise keine Start- oder Endzeiten für Abfragen. Stattdessen unterstützen sie einen serverseitigen Cursor. Sie können persistente Seitentypen verwenden, um den serverseitigen Cursor zu speichern. Weitere Informationen finden Sie unter Was ist ein Cursor?.

Hier sind einige Beispiele:

"paging": {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

"paging": {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

Konfigurieren von NextPageUrl

NextPageUrl-type paging bedeutet, dass die API-Antwort einen komplexen Link im Antworttext enthält, ähnlich wie LinkHeader, aber die URL ist im Antworttext anstelle des Headers enthalten.

Beispiel:

"paging": {
 "pagingType" : "NextPageUrl", 
  "nextPageTokenJsonPath" : "$.data.repository.pageInfo.endCursor", 
  "hasNextFlagJsonPath" : "$.data.repository.pageInfo.hasNextPage", 
  "nextPageUrl" : "https://api.github.com/graphql", 
  "nextPageUrlQueryParametersTemplate" : "{'query':'query{repository(owner:\"xyz\")}" 
}

Konfigurieren von NextPageToken oder PersistentToken

NextPageToken-type Paginierung verwendet ein Token (einen Hash oder einen Cursor), das den Zustand der aktuellen Seite darstellt. Das Token ist in der API-Antwort enthalten, und der Client fügt es an die nächste Anforderung an, um die nächste Seite abzurufen. Diese Methode wird häufig verwendet, wenn der Server den genauen Zustand zwischen Anforderungen beibehalten muss.

PersistentToken Die Paginierung verwendet ein Token, das serverseitig beibehalten wird. Der Server speichert das letzte Token, das der Client abgerufen hat, und stellt das nächste Token in nachfolgenden Anforderungen bereit. Der Client fährt dort fort, wo er aufgehört hat, auch wenn er später neue Anforderungen sendet.

Beispiele:

"paging": {
 "pagingType" : "NextPageToken", 
 "nextPageRequestHeader" : "ETag", 
 "nextPageTokenResponseHeader" : "ETag" 
}

"paging": {
 "pagingType" : "PersistentToken", 
    "nextPageParaName" : "gta", 
    "nextPageTokenJsonPath" : "$.alerts[-1:]._id" 
}

Konfigurieren des Offsets

Offset-type Paginierung gibt die Anzahl der zu überspringenden Seiten und einen Grenzwert für die Anzahl der Ereignisse an, die pro Seite in der Anforderung abgerufen werden sollen. Clients rufen einen bestimmten Bereich von Elementen aus dem Dataset ab.

Beispiel:

"paging": {
  "pagingType": "Offset", 
  "offsetParaName": "offset",
  "pageSize": 50,
  "pagingQueryParamOnly": true,
  "pagingInfoPlacement": "QueryString"
}

Konfigurieren von CountBasedPaging

CountBasedPagingMit der -type-Paginierung kann der Client die Anzahl der elemente angeben, die in der Antwort zurückgegeben werden sollen. Diese Funktion ist nützlich für APIs, die paginierung basierend auf einem count-Parameter als Teil der Antwortnutzlast unterstützen.

Beispiel:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

DCR-Konfiguration

Beispiel für einen CCF-Datenconnector

Hier sehen Sie ein Beispiel für alle Komponenten des JSON-Codes für den CCF-Datenconnector:

{
   "kind": "RestApiPoller",
   "properties": {
      "connectorDefinitionName": "ConnectorDefinitionExample",
      "dcrConfig": {
           "streamName": "Custom-ExampleConnectorInput",
           "dataCollectionEndpoint": "https://example-dce-sbsr.location.ingest.monitor.azure.com",
           "dataCollectionRuleImmutableId": "dcr-32_character_hexadecimal_id"
            },
      "dataType": "ExampleLogs",
      "auth": {
         "type": "Basic",
         "password": "[[parameters('username')]",
         "userName": "[[parameters('password')]"
      },
      "request": {
         "apiEndpoint": "https://rest.contoso.com/example",
         "rateLimitQPS": 10,
         "rateLimitConfig": {
            "evaluation": {
              "checkMode": "OnlyWhen429"
            },
            "extraction": {
              "source": "CustomHeaders",
              "headers": {
                "limit": {
                  "name": "X-RateLimit-Limit",
                  "format": "Integer"
                },
                "remaining": {
                  "name": "X-RateLimit-Remaining",
                  "format": "Integer"
                },
                "reset": {
                  "name": "X-RateLimit-RetryAfter",
                  "format": "UnixTimeSeconds"
                }
              }
            },
            "retryStrategy": {
              "useResetOrRetryAfterHeaders": true
            }
         },
         "queryWindowInMin": 5,
         "httpMethod": "POST",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader",
         "pagingInfoPlacement": "RequestBody",
         "pagingQueryParamOnly": true
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}