Informations de référence sur le connecteur de données RestApiPoller pour la plateforme de connecteurs sans code

Pour créer un RestApiPoller connecteur de données avec la plateforme de connecteurs sans code (CCP), utilisez cette référence comme supplément à la documentation de l’API REST Microsoft Sentinel pour les connecteurs de données.

Chacun dataConnector représente une connexion spécifique d’un connecteur de données Microsoft Sentinel. Un connecteur de données peut avoir plusieurs connexions, qui extraient des données à partir de différents points de terminaison. La configuration JSON créée à l’aide de ce document de référence est utilisée pour terminer le modèle de déploiement pour le connecteur de données CCP.

Pour plus d’informations, consultez Créer un connecteur sans code pour Microsoft Sentinel.

Connecteurs de données - Créer ou mettre à jour

Référencez l’opération Créer ou mettre à jour dans la documentation de l’API REST pour trouver la dernière version stable ou préliminaire de l’API. La différence entre la création et l’opération de mise à jour est que la mise à jour nécessite la valeur etag .

PUT , méthode

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

Paramètres d’URI

Pour plus d’informations sur la dernière version de l’API, consultez Connecteurs de données - Créer ou mettre à jour des paramètres d’URI.

Corps de la demande

Le corps de la demande d’un RestApiPoller connecteur de données CCP a la structure suivante :

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

RestApiPoller

RestApiPoller représente un connecteur de données CCP Poller API dans lequel vous personnalisez les charges utiles de pagination, d’autorisation et de requête/réponse pour votre source de données.

Configuration de l'authentification

Le CCP prend en charge les types d’authentification suivants :

• De base
• APIKey
• OAuth2
• Jwt

En guise de meilleure pratique, utilisez des paramètres dans la section d’authentification au lieu de coder en dur les informations d’identification. Pour plus d’informations, consultez Entrée confidentielle sécurisée.

Pour créer le modèle de déploiement qui utilise également des paramètres, vous devez échapper aux paramètres de cette section avec un démarrage [supplémentaire. Cela permet aux paramètres d'attribuer une valeur en fonction de l'interaction de l'utilisateur avec le connecteur. Pour plus d’informations, consultez caractères d’échappement des expressions de modèle.

Pour permettre l’entrée des informations d’identification à partir de l’interface utilisateur, la connectorUIConfig section nécessite instructions les paramètres souhaités. Pour plus d’informations, consultez la référence des définitions de connecteur de données pour la plateforme de connecteurs sans code.

Authentification de base

Exemple d’authentification de base à l’aide de paramètres définis dans connectorUIconfig:

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

APIKey

Exemples d’authentification APIKey :

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

Cet exemple montre comment obtenir le secret défini à partir de l’entrée utilisateur envoyée dans l’en-tête suivant : X-MyApp-Auth-Header : Porteur apikey

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

Cet exemple utilise les valeurs par défaut et génère l’en-tête suivant : Autorisation : jeton 123123123

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

Étant donné que le ApiKeyName paramètre est défini ""explicitement sur , le résultat est l’en-tête suivant : Autorisation : 123123123

OAuth2

La plateforme de connecteurs sans code prend en charge l’octroi de code d’autorisation OAuth 2.0 et les informations d’identification du client. Le type d’autorisation du code d’autorisation est utilisé par les clients confidentiels et publics pour échanger un code d’autorisation pour un jeton d’accès. Une fois que l’utilisateur est retourné au client via l’URL de redirection, l’application obtient le code d’autorisation de l’URL et l’utilise pour demander un jeton d’accès.

Le flux de code d’authentification permet d’extraire des données pour le compte des autorisations d’un utilisateur et des informations d’identification client est d’extraire des données avec des autorisations d’application. Le serveur de données accorde l’accès à l’application. Étant donné qu’il n’existe aucun utilisateur dans le flux d’informations d’identification du client, aucun point de terminaison d’autorisation n’est nécessaire, qu’un point de terminaison de jeton.

Exemple : type d’octroi OAuth2 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"
}

Exemple : type d’octroi OAuth2 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

Exemple : jeton web JSON (JWT)

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

Configuration de requête

La section de requête définit la façon dont le connecteur de données CCP envoie des requêtes à votre source de données, comme le point de terminaison de l’API et la fréquence à laquelle interroger ce point de terminaison.

Lorsque l’API nécessite des paramètres complexes, utilisez ou queryParameters queryParametersTemplate incluez des variables intégrées.

Exemple StartTimeAttributeName

Prenons cet exemple :

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

La requête envoyée au serveur distant est la suivante : https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

Exemple QueryTimeIntervalAttributeName

Prenons cet exemple :

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

La requête envoyée au serveur distant est la suivante : https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Exemples de requête utilisant Microsoft Graph comme API de source de données

Cet exemple interroge les messages avec un paramètre de requête de filtre. Pour plus d’informations, consultez les paramètres de requête de l’API Microsoft Graph.

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

L’exemple précédent envoie une GET requête à https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. L’horodatage est mis à jour pour chaque queryWindowInMin fois.

Les mêmes résultats sont obtenus avec cet exemple :

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

Une autre option est lorsque la source de données attend 2 paramètres de requête, un pour l’heure de début et l’autre pour l’heure de fin.

Exemple :

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

Cela envoie une GET demande à https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Pour les requêtes complexes, utilisez QueryParametersTemplate. Cet exemple suivant envoie une POST requête avec des paramètres dans le corps.

Exemple :

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

Configuration de réponse

Définissez la gestion des réponses de votre connecteur de données avec les paramètres suivants :

Exemples de configuration de réponse

Une réponse de serveur au format JSON est attendue, avec les données demandées dans la valeur de propriété. L’état de la propriété de réponse indique d’ingérer les données uniquement si la valeur est success.

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

La réponse attendue dans cet exemple prépare un fichier CSV sans en-tête.

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

Configuration de pagination

Lorsque la source de données ne peut pas envoyer l’intégralité de la charge utile de réponse en même temps, le connecteur de données CCP doit savoir comment recevoir des parties des données dans les pages de réponse. Les types de pagination à choisir sont les suivants :

Configurer LinkHeader ou PersistentLinkHeader

Le type de pagination le plus courant est lorsqu’une API de source de données serveur fournit des URL aux pages de données suivantes et précédentes. Pour plus d’informations sur la spécification de l’en-tête de lien, consultez RFC 5988.

LinkHeader la pagination signifie que la réponse de l’API inclut les éléments suivants :

• en-tête de Link réponse HTTP
• ou un chemin JSON pour récupérer le lien à partir du corps de la réponse.

PersistentLinkHeader la pagination a les mêmes propriétés que , sauf que LinkHeaderl’en-tête de lien persiste dans le stockage back-end. Cette option active la pagination des liens entre les fenêtres de requête. Par exemple, certaines API ne prennent pas en charge les heures de début ou les heures de fin des requêtes. Au lieu de cela, ils prennent en charge un curseur côté serveur. Les types de pages persistantes peuvent être utilisés pour mémoriser le curseur côté serveur. Pour plus d’informations, consultez Qu’est-ce qu’un curseur ?.

Voici quelques exemples :

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

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

Configurer NextPageUrl

NextPageUrl la pagination signifie que la réponse de l’API inclut un lien complexe dans le corps de la réponse similaire à LinkHeader, mais que l’URL est incluse dans le corps de la réponse au lieu de l’en-tête.

Exemple :

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

Configurer NextPageToken ou PersistentToken

NextPageToken la pagination utilise un jeton (hachage ou curseur) qui représente l’état de la page active. Le jeton est inclus dans la réponse de l’API, et le client l’ajoute à la requête suivante pour extraire la page suivante. Cette méthode est souvent utilisée lorsque le serveur doit maintenir l’état exact entre les requêtes.

PersistentToken pagination utilise un jeton qui conserve le côté serveur. Le serveur mémorise le dernier jeton récupéré par le client et fournit le jeton suivant dans les requêtes suivantes. Le client continue là où il s’est arrêté même s’il effectue de nouvelles demandes ultérieurement.

Exemples :

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

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

Configurer offset

Offset pagination spécifie le nombre de pages à ignorer et une limite du nombre d’événements à récupérer par page dans la demande. Les clients extraient une plage spécifique d’éléments à partir du jeu de données.

Exemple :

Paging: {
   
       "pagingType": "Offset", 
        "offsetParaName": "offset" 
 }

Configuration DCR

Exemple de connecteur de données CCP

Voici un exemple de tous les composants du connecteur de données CCP JSON ensemble.

{
   "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,
         "queryWindowInMin": 5,
         "httpMethod": "GET",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader"
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}