RestApiPoller-Datenkonnektorreferenz für das Codeless Connector Framework

Um einen RestApiPoller Datenconnector mit dem Codeless Connector Framework (CCF) zu erstellen, verwenden Sie diesen Verweis als Ergänzung zur Microsoft Sentinel-REST-API für Datenconnectors-Dokumente .

Jede dataConnector stellt eine bestimmte Verbindung eines Microsoft Sentinel-Datenconnectors dar. Ein Datenconnector verfügt möglicherweise über mehrere Verbindungen, die Daten aus verschiedenen Endpunkten abrufen. Die json-Konfiguration, die mit diesem Referenzdokument erstellt wurde, wird verwendet, um die Bereitstellungsvorlage für den CCF-Datenconnector abzuschließen.

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

Datenconnectors – Erstellen oder Aktualisieren

Verweisen Sie auf den Erstellungs- oder Aktualisierungsvorgang in den REST-API-Dokumenten, um die neueste stabile oder Vorschau-API-Version zu finden. Der Unterschied zwischen dem Erstellungs - und dem Aktualisierungsvorgang ist die Aktualisierung, die den etag-Wert erfordert.

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 Data Connectors – Create or Update URI Parameters.

Anforderungstext

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

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

RestApiPoller

RestApiPoller stellt einen API Poller CCF-Datenconnector dar, in dem Sie Paging-, Autorisierungs- und Anforderungs-/Antwortnutzlasten für Ihre Datenquelle anpassen.

Authentifizierungskonfiguration

Die CCF unterstützt die folgenden Authentifizierungstypen:

• Grundlegend
• APIKey
• OAuth2
• JWT

Verwenden Sie als bewährte Methode Parameter im Authentifizierungsabschnitt anstelle von hartcodierenden Anmeldeinformationen. Weitere Informationen finden Sie unter Sichere vertrauliche Eingaben.

Um die Bereitstellungsvorlage zu erstellen, die auch Parameter verwendet, müssen Sie die Parameter in diesem Abschnitt mit einem zusätzlichen Start [escapeen. Dadurch können die Parameter einen Wert zuweisen, der auf der Interaktion des Benutzers mit dem Konnektor beruht. Weitere Informationen finden Sie unter Escapezeichen für Vorlagenausdrücke.

Damit die Anmeldeinformationen über die Benutzeroberfläche eingegeben werden können, benötigt connectorUIConfig der instructions Abschnitt die gewünschten Parameter. Weitere Informationen finden Sie in der Datenkonnektordefinitionsreferenz für das Codeless Connector Framework.

Standardauthentifizierung

Beispiel für eine einfache Authentifizierung mithilfe von Parametern, die in connectorUIconfig:

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

APIKey

APIKey-Authentifizierungsbeispiele:

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

Dieses Beispiel führt zu dem aus Benutzereingaben definierten Geheimnis, das im folgenden Header gesendet wird: X-MyApp-Auth-Header: Bearer apikey

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

In diesem Beispiel werden die Standardwerte und Ergebnisse im folgenden Header verwendet: Autorisierung: Token 123123123

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

Da die ApiKeyName Eigenschaft explizit auf "" festgelegt ist, ist das Ergebnis der folgende Kopfzeile: Autorisierung: 123123123

OAuth2

Das Codeless Connector Framework unterstützt die OAuth 2.0-Autorisierungscodezuteilung und Clientanmeldeinformationen. Der Autorisierungscode-Genehmigungstyp wird von vertraulichen und öffentlichen Clients verwendet, um einen Autorisierungscode für ein Zugriffstoken austauschen. Nachdem der Benutzer über die Umleitungs-URL an den Client zurückkehrt, ruft die Anwendung den Autorisierungscode aus der URL ab und verwendet sie, um ein Zugriffstoken anzufordern.

Der Authentifizierungscodefluss dient zum Abrufen von Daten im Auftrag der Berechtigungen eines Benutzers und der Clientanmeldeinformationen zum Abrufen von Daten mit Anwendungsberechtigungen. Der Datenserver gewährt Zugriff auf die Anwendung. Da kein Benutzer im Clientanmeldeinformationsfluss vorhanden ist, ist kein Autorisierungsendpunkt erforderlich, nur ein Tokenendpunkt.

Beispiel: OAuth2-Erteilungstyp 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"
}

Beispiel: OAuth2-Erteilungstyp 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-/Kennwortanmeldeinformationen und die 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-Textkörper (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 Kopfzeilen (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 Kopfzeilen (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"
}

Authentifizierungsfluss:

1. Senden von Anmeldeinformationen zum TokenEndpoint Abrufen des JWT-Tokens

   • Wenn IsCredentialsInHeaders: true: Sendet den Standardauthentifizierungsheader mit benutzername:password
   • Wenn IsCredentialsInHeaders: false: Sendet Anmeldeinformationen im POST-Textkörper

2. Extrahieren eines Tokens mithilfe JwtTokenJsonPath oder aus dem Antwortheader

3. Verwenden des Tokens in nachfolgenden API-Anforderungen mit ApiKeyName Header

Eigenschaften:

Authentifizierungsfluss:

1. Senden von Anmeldeinformationen zum TokenEndpoint Abrufen des JWT-Tokens

   • Wenn IsCredentialsInHeaders: true: Sendet den Standardauthentifizierungsheader mit benutzername:password
   • Wenn IsCredentialsInHeaders: false: Sendet Anmeldeinformationen im POST-Textkörper

2. Extrahieren eines Tokens mithilfe JwtTokenJsonPath oder aus dem Antwortheader

3. Verwenden des Tokens in nachfolgenden API-Anforderungen mit ApiKeyName Header

Anforderungskonfiguration

Der Anforderungsabschnitt 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 die queryParameters oder queryParametersTemplate die einige integrierte Variablen enthalten.

StartTimeAttributeName-Beispiel

Betrachten Sie das folgende Beispiel:

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

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

QueryTimeIntervalAttributeName-Beispiel

Betrachten Sie das folgende Beispiel:

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

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

Beispiel RateLimitConfig

Betrachten Sie das folgende 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 Rate-Limit-Header enthält, kann der Connector diese Informationen nutzen, um seine Anfragerate anzupassen.

Anfordern von Beispielen mithilfe von Microsoft Graph als Datenquellen-API

In diesem Beispiel werden Nachrichten mit einem Filterabfrageparameter abfragen. 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.0000000. Der Zeitstempel wird für jedes queryWindowInMin Mal aktualisiert.

Die gleichen Ergebnisse werden in diesem Beispiel erzielt:

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

Eine weitere Option ist, wenn die Datenquelle 2 Abfrageparameter erwartet, eine für die Startzeit und eine 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",
}

Dadurch wird 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 . Im nächsten Beispiel wird eine POST Anforderung mit Parametern im Textkörper gesendet.

Beispiel:

"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 die Antwortbehandlung Ihres Datenconnectors mit den folgenden Parametern:

Beispiele für die Antwortkonfiguration

Es wird eine Serverantwort im JSON-Format erwartet, wobei die angeforderten Daten im Eigenschaftswert enthalten sind. Der Status der Antworteigenschaft gibt an, dass die Daten nur aufgenommen werden, wenn der Wert istsuccess.

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

Die erwartete Antwort in diesem Beispiel bereitet sich auf eine CSV ohne Header vor.

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

Auslagerungskonfiguration

Wenn die Datenquelle die gesamte Antwortnutzlast nicht gleichzeitig senden kann, muss der CCF-Datenconnector wissen, wie Teile der Daten auf Antwortseiten empfangen werden. Die paging-Typen, aus denen Sie wählen können, sind:

Konfigurieren von LinkHeader oder PersistentLinkHeader

Der am häufigsten verwendete Pagingtyp ist, wenn eine Serverdatenquelle-API URLs für die nächsten und vorherigen Seiten von Daten bereitstellt. Weitere Informationen zur Spezifikation des Linkheaders finden Sie unter RFC 5988.

LinkHeader Paging bedeutet, dass die API-Antwort eine der folgenden Elemente umfasst:

• der Link HTTP-Antwortheader
• oder einen JSON-Pfad, um den Link aus dem Antworttext abzurufen.

PersistentLinkHeader Paging hat die gleichen Eigenschaften wie LinkHeader, außer der Linkheader bleibt im Back-End-Speicher erhalten. Diese Option ermöglicht das Paging von Verknüpfungen über Abfragefenster hinweg. Beispielsweise unterstützen einige APIs keine Start- oder Endzeiten der Abfrage. Stattdessen unterstützen sie einen serverseitigen Cursor. Beständige Seitentypen können verwendet werden, um den serverseitigen Cursor zu merken. Weitere Informationen finden Sie unter Was ist ein Cursor?.

Im Folgenden finden Sie einige Beispiele:

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

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

Konfigurieren von NextPageUrl

NextPageUrl Paging bedeutet, dass die API-Antwort einen komplexen Link im Antworttext LinkHeaderähnlich enthält, 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 Die Paginierung verwendet ein Token (ein Hash oder ein Cursor), der den Status 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 Paginierung verwendet ein Token, das serverseitig beibehalten wird. Der Server merkt sich das letzte vom Client abgerufene Token und stellt das nächste Token in nachfolgenden Anforderungen bereit. Der Client wird weiterhin an der Stelle fortgesetzt, an der 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 Die 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

CountBasedPaging ermöglicht dem Client, die Anzahl der Elemente anzugeben, die in der Antwort zurückgegeben werden sollen. Dies ist nützlich für APIs, die die Paginierung basierend auf einem Anzahlparameter 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-Datenkonnektor

Hier ist ein Beispiel für alle Komponenten des CCF-Datenkonnektors JSON zusammen.

{
   "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": ["$"]
      }
   }
}