Partager via

Informations de référence sur le connecteur de données RestApiPoller pour l’infrastructure du connecteur sans code

Pour créer un RestApiPoller connecteur de données avec codeless Connector Framework (CCF), 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 CCF.

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.

Nom Descriptif
dataConnectorId L’ID du connecteur de données doit être un nom unique et est identique au paramètre dans le name corps de la requête.
resourceGroupName Nom du groupe de ressources, pas sensible à la casse.
subscriptionId ID de l’abonnement cible.
workspaceName Nom de l’espace de travail, et non de l’ID.
Modèle d’expression régulière : ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
api-version Version de l’API à utiliser pour cette opération.

Corps de la demande

Le corps de la demande d’un RestApiPoller connecteur de données CCF 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 CCF Poller d’API dans lequel vous personnalisez les charges utiles de pagination, d’autorisation et de requête/réponse pour votre source de données.

Nom Requise Catégorie Descriptif
nom Vrai ficelle Nom unique de la connexion correspondant au paramètre URI
gentil Vrai ficelle Doit être RestApiPoller
etag Identifiant Unique Global (GUID) Laissez vide pour la création de nouveaux connecteurs. Pour les opérations de mise à jour, l’etag doit correspondre à l’etag (GUID) du connecteur existant.
properties.connectorDefinitionName ficelle Nom de la ressource DataConnectorDefinition qui définit la configuration de l’interface utilisateur du connecteur de données. Pour plus d’informations, consultez Définition du connecteur de données.
Propriétés.Auth Vrai JSON imbriqué Décrit les propriétés d’authentification pour l’interrogation des données. Pour plus d’informations, consultez la configuration de l’authentification.
Propriétés.demander Vrai JSON imbriqué Décrit la charge utile de la requête pour interroger les données, telles que le point de terminaison de l’API. Pour plus d’informations, consultez Configuration de request.
Propriétés.réponse Vrai JSON imbriqué Décrit l’objet de réponse et le message imbriqué renvoyés par l’API lors de l’interrogation des données. Pour plus d’informations, consultez Configuration de response.
Propriétés.pagination JSON imbriqué Décrit la charge utile de la pagination lors de l’interrogation des données. Pour plus d’informations, consultez Configuration de paging.
Propriétés.dcrConfig JSON imbriqué Paramètres obligatoires lorsque les données sont envoyées à une règle de collecte de données (DCR). Pour plus d’informations, consultez configuration DCR.

Configuration de l'authentification

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

Remarque

L’implémentation CCF OAuth2 ne prend pas en charge les informations d’identification de certificat client.

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 l’infrastructure du connecteur sans code.

Authentification de base

Champ Requise Catégorie
Nom d’utilisateur Vrai ficelle
Mot de passe Vrai ficelle

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

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

APIKey

Champ Requise Catégorie Descriptif Valeur par défaut
ApiKey Vrai ficelle clé secrète utilisateur
ApiKeyName ficelle nom de l’en-tête Uri contenant la valeur ApiKey Authorization
ApiKeyIdentifier ficelle valeur de chaîne à ajouter au jeton token
IsApiKeyInPostPayload booléen envoyer un secret dans le corps POST au lieu d’en-tête false

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

Codeless Connector Framework 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.

Champ Requise Catégorie Descriptif
ClientId Vrai Chaîne ID client
ClientSecret Vrai Chaîne Secret client
AuthorizationCode True quand grantType = authorization_code Chaîne Si le type d’octroi est authorization_code cette valeur de champ correspond au code d’autorisation retourné par le service d’authentification.
Portée True pour le type d’octroi authorization_code
facultatif pour le type d’octroi client_credentials		 Chaîne Liste d’étendues séparées par un espace pour le consentement de l’utilisateur. Pour plus d’informations, consultez les étendues et autorisations OAuth2.
RedirectUri True quand grantType = authorization_code Chaîne L’URL de redirection doit être https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights
GrantType Vrai Chaîne authorization_code ou client_credentials
TokenEndpoint Vrai Chaîne URL permettant d’échanger du code avec un jeton valide dans l’octroi ou l’ID authorization_code client et le secret avec un jeton valide dans client_credentials l’octroi.
TokenEndpointHeaders Objet Objet de valeur de clé facultatif pour envoyer des en-têtes personnalisés au serveur de jetons
TokenEndpointQueryParameters Objet Objet de valeur de clé facultatif pour envoyer des analyseurs de requête personnalisés au serveur de jetons
PointDeFinD'Autorisation Vrai Chaîne URL du consentement de l’utilisateur pour authorization_code le flux
AuthorizationEndpointHeaders Objet Objet de valeur de clé facultatif pour envoyer des en-têtes personnalisés au serveur d’authentification
ParamètresDeRequêteDuPointDeTerminaisonD'Autorisation Objet Paire de valeurs de clé facultative utilisée dans la demande de flux de code d’autorisation OAuth2

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

L’authentification JWT (JSON Web Token) prend en charge l’obtention de jetons via des informations d’identification de nom d’utilisateur/mot de passe et leur utilisation pour les demandes d’API.

Exemple de base :

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

Informations d’identification dans le corps POST (valeur par défaut) :

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

Informations d’identification dans les en-têtes (Authentification de base) :

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

Informations d’identification dans les en-têtes (jeton utilisateur) :

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

Flux d’authentification :

  1. Envoyer des informations d’identification pour TokenEndpoint obtenir le jeton JWT

    • If IsCredentialsInHeaders: true: envoie l’en-tête d’authentification de base avec nom d’utilisateur :password
    • If IsCredentialsInHeaders: false: envoie des informations d’identification dans le corps POST

  2. Extraire le jeton à l’aide ou à partir de l’en-tête JwtTokenJsonPath de réponse

  3. Utiliser un jeton dans les demandes d’API suivantes avec ApiKeyName en-tête

Propriétés:

Champ Requise Catégorie Descriptif
type Vrai Chaîne Doit être JwtToken
nom d’utilisateur True (si userToken n’est pas utilisé) Objet Paire clé-valeur pour les informations d’identification du nom d’utilisateur. Si userName et password sont envoyés dans la demande d’en-tête, spécifiez la value propriété avec le nom d’utilisateur. Si userName et password envoyé dans la demande de corps, spécifiez le Key et Value
mot de passe True (si userToken n’est pas utilisé) Objet Paire clé-valeur pour les informations d’identification du mot de passe. Si userName et password sont envoyés dans la demande d’en-tête, spécifiez la value propriété avec le nom d’utilisateur. Si userName et password envoyé dans la demande de corps, spécifiez le Key et Value
userToken True (si userName n’est pas utilisé) Chaîne Jeton utilisateur généré par le client pour obtenir le jeton système pour l’authentification
UserTokenPrepend Faux Chaîne Texte prédéfini avant le jeton. Exemple : Bearer
NoAccessTokenPrepend Faux Booléen Indicateur d’accès pour indiquer que le jeton ne doit pas précéder quoi que ce soit
TokenEndpointHttpMethod Faux Chaîne Méthode HTTP pour le point de terminaison de jeton. Peut être Get ou Post. Valeur par défaut : Post
TokenEndpoint Vrai Chaîne Point de terminaison d’URL pour obtenir le jeton JWT
IsCredentialsInHeaders Booléen Envoyez les informations d’identification en tant qu’en-tête d’authentification de base (true) et post body (false). Valeur par défaut : false
IsJsonRequest Booléen Envoyer une requête au format JSON (en-tête Content-Type = application/json) et encodée par formulaire (en-tête Content-Type = application/x-www-form-urlencoded). Valeur par défaut : false
JwtTokenJsonPath Chaîne JSONPath pour extraire le jeton de la réponse (par exemple, «$.access_token »)
JwtTokenInResponseHeader Booléen Extrayez le jeton de l’en-tête de réponse par rapport au corps. Valeur par défaut : false
JwtTokenHeaderName Chaîne Nom de l’en-tête lorsque le jeton se trouve dans l’en-tête de réponse. Valeur par défaut : «Authorization »
JwtTokenIdentifier Chaîne Identificateur utilisé pour extraire le JWT d’une chaîne de jeton préfixée
QueryParameters Objet Paramètres de requête personnalisés à inclure lors de l’envoi de la requête au point de terminaison de jeton
En-têtes Objet En-têtes personnalisés à inclure lors de l’envoi de la requête au point de terminaison de jeton
RequestTimeoutInSeconds Nombre entier Délai d’expiration de la demande en secondes. Valeur par défaut : 100, Max 180

Flux d’authentification :

  1. Envoyer des informations d’identification pour TokenEndpoint obtenir le jeton JWT

    • If IsCredentialsInHeaders: true: envoie l’en-tête d’authentification de base avec nom d’utilisateur :password
    • If IsCredentialsInHeaders: false: envoie des informations d’identification dans le corps POST

  2. Extraire le jeton à l’aide ou à partir de l’en-tête JwtTokenJsonPath de réponse

  3. Utiliser un jeton dans les demandes d’API suivantes avec ApiKeyName en-tête

Remarque

Limitations :

  • Nécessite l’authentification par nom d’utilisateur/mot de passe pour l’acquisition de jetons
  • Ne prend pas en charge les demandes de jetons basés sur des clés d’API
  • L’authentification d’en-tête personnalisée (sans nom d’utilisateur/mot de passe) n’est pas prise en charge

Configuration de requête

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

Champ Requise Catégorie Descriptif
ApiEndpoint Vrai Chaîne URL du serveur distant. Définit le point de terminaison à partir duquel extraire les données.
RateLimitQPS Nombre entier Définit le nombre d’appels ou de requêtes autorisés en une seconde.
RateLimitConfig Objet Définit la configuration de la limite de taux pour l’API RESTful. Consultez l’exemple.
QueryWindowInMin Nombre entier Définit la fenêtre de requête disponible en minutes. Le minimum est de 1 minute. La valeur par défaut est de 5 minutes.
HttpMethod Chaîne Définit la méthode d’API : GET(par défaut) ou POST
QueryTimeFormat Chaîne Définit le format de date et d’heure attendu par le point de terminaison (serveur distant). Le CCF utilise la date et l’heure actuelles où cette variable est utilisée. Les valeurs possibles sont les constantes : UnixTimestamp, UnixTimestampInMills ou toute autre représentation valide de l’heure de date, par exemple : yyyy-MM-dd, MM/dd/yyyy HH:mm:ss
la valeur par défaut est ISO 8601 UTC
RetryCount Entier (1...6) Définit 1 les 6 nouvelles tentatives autorisées à récupérer à partir d’un échec. La valeur par défaut est 3.
TimeoutInSeconds Entier (1...180) Définit le délai d’expiration de la requête, en secondes. La valeur par défaut est 20
IsPostPayloadJson Booléen Détermine si la charge utile POST est au format JSON. La valeur par défaut est false
En-têtes Objet Paires clé-valeur qui définissent les en-têtes de requête.
QueryParameters Objet Paires clé-valeur qui définissent les paramètres de requête de requête.
StartTimeAttributeName True quand est EndTimeAttributeName défini Chaîne Définit le nom du paramètre de requête pour l’heure de début de la requête. Consultez l’exemple.
EndTimeAttributeName True quand est StartTimeAttributeName défini Chaîne Définit le nom du paramètre de requête pour l’heure de fin de la requête.
QueryTimeIntervalAttributeName Chaîne Si le point de terminaison nécessite un format spécialisé pour interroger les données sur une période de temps, utilisez cette propriété avec les paramètres et les QueryTimeIntervalPrependQueryTimeIntervalDelimiter paramètres. Consultez l’exemple.
QueryTimeIntervalPrepend True quand est QueryTimeIntervalAttributeName défini Chaîne Consultez QueryTimeIntervalAttributeName
QueryTimeIntervalDelimiter True quand est QueryTimeIntervalAttributeName défini Chaîne Consultez QueryTimeIntervalAttributeName
QueryParametersTemplate Chaîne Modèle de requête à utiliser lors du passage de paramètres dans des scénarios avancés.
br>Par exemple : "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"

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

Variable intégrée pour une utilisation dans queryParameters pour une utilisation dans queryParametersTemplate
_QueryWindowStartTime Oui Oui
_QueryWindowEndTime Oui Oui
_APIKeyName non Oui
_APIKey non Oui

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}

Exemple RateLimitConfig

Prenons cet exemple :

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

Lorsque la réponse inclut des en-têtes de limite de débit, le connecteur peut utiliser ces informations pour ajuster son débit de requête.

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 :

Champ Requise Catégorie Descriptif
EventsJsonPaths Vrai Liste des chaînes Définit le chemin d’accès au message dans la réponse JSON. Une expression de chemin d’accès JSON spécifie un chemin d’accès à un élément, ou à un ensemble d’éléments, dans une structure JSON
SuccessStatusJsonPath Chaîne Définit le chemin d’accès au message de réussite dans la réponse JSON. Lorsque ce paramètre est défini, le SuccessStatusValue paramètre doit également être défini.
SuccessStatusValue Chaîne Définit le chemin d’accès vers la valeur du message de réussite dans la réponse JSON.
IsGzipCompressed Booléen Détermine si la réponse est compressée dans un fichier gzip
format Vrai Chaîne json ou csv ou xml
CompressionAlgo Chaîne L’algorithme de compression, soit multi-gzipdeflate. Pour l’algorithme de compression gzip, configurez IsGzipCompressed simplement pour True définir une valeur pour ce paramètre.
CsvDelimiter Chaîne Si le format de réponse est CSV et que vous souhaitez modifier le délimiteur CSV par défaut de ","
Limite de hachage Booléen Indiquer si les données CSV ont une limite
HasCsvHeader Booléen Indiquer si les données CSV ont un en-tête, la valeur par défaut est True
CsvEscape Chaîne Caractère d’échappement pour une limite de champ, la valeur par défaut est "

Par exemple, un fichier CSV avec des en-têtes id,name,avg et une ligne de données contenant des espaces comme 1,"my name",5.5 nécessite la limite de " champ.
ConvertChildPropertiesToArray Booléen Cas particulier dans lequel le serveur distant retourne un objet au lieu d’une liste d’événements où chaque propriété contient des données.

Remarque

Le type de format CSV est analysé par la spécification RFC4180 .

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 CCF doit savoir comment recevoir des parties des données dans les pages de réponse. Les types de pagination à choisir sont les suivants :

Type de pagination facteur de décision
La réponse de l’API contient-elle des liens vers les pages suivantes et précédentes ?
La réponse de l’API a-t-elle un jeton ou un curseur pour les pages suivantes et précédentes ?
La réponse de l’API prend-elle en charge un paramètre pour le nombre d’objets à ignorer lors de la pagination ?
La réponse de l’API prend-elle en charge un paramètre pour le nombre d’objets à retourner ?

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 ?.

Remarque

Il ne peut y avoir qu’une seule requête s’exécutant pour le connecteur avec PersistentLinkHeader afin d’éviter les conditions de concurrence sur le curseur côté serveur. Cela peut affecter la latence.

Champ Requise Catégorie Descriptif
LinkHeaderTokenJsonPath Faux Chaîne Utilisez cette propriété pour indiquer où obtenir la valeur dans le corps de la réponse.

Par exemple, si la source de données retourne le code JSON suivant : { nextPage: "foo", value: [{data}]}LinkHeaderTokenJsonPath$.nextPage
Taille de la Page Faux Nombre entier Nombre d’événements par page
PageSizeParameterName Faux Chaîne Nom du paramètre de requête pour la taille de page
PaginationInfoPlacement Faux Chaîne Comment les informations de pageage sont remplies. Accepte soit « QueryString » soit « RequestBody »
PagingQueryParamOnly Faux Booléen Si elle est réglée sur true, elle omettra tous les autres paramètres de requête sauf les paramètres de requête de pagination.

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.

Champ Requise Catégorie Descriptif
Taille de la Page Faux Nombre entier Nombre d’événements par page
PageSizeParameterName Faux Chaîne Nom du paramètre de requête pour la taille de page
NextPageUrl Faux Chaîne Uniquement si le connecteur est pour l’API Coralogix
NextPageUrlQueryParameters Faux Paires de valeurs clé d’objet : ajout d’un paramètre de requête personnalisé à chaque demande de la page suivante
NextPageParaName Faux Chaîne Détermine le nom de la page suivante dans la requête.
HasNextFlagJsonPath Faux Chaîne Définit le chemin d’accès à l’attribut d’indicateur HasNextPage
NextPageRequestHeader Faux Chaîne Détermine le nom de l’en-tête de la page suivante dans la requête.
NextPageUrlQueryParametersTemplate Faux Chaîne Uniquement si le connecteur est pour l’API Coralogix
PaginationInfoPlacement Faux Chaîne Comment les informations de pageage sont remplies. Accepte soit « QueryString » soit « RequestBody »
PagingQueryParamOnly Faux Booléen Si elle est réglée sur true, elle omettra tous les autres paramètres de requête sauf les paramètres de requête de pagination.

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.

Champ Requise Catégorie Descriptif
Taille de la Page Faux Nombre entier Nombre d’événements par page
PageSizeParameterName Faux ficelle Nom du paramètre de requête pour la taille de page
NextPageTokenJsonPath Faux ficelle Chemin JSON du jeton de page suivant dans le corps de la réponse.
NextPageTokenResponseHeader Faux ficelle Si NextPageTokenJsonPath elle est vide, utilisez le jeton dans ce nom d’en-tête pour la page suivante.
NextPageParaName Faux ficelle Détermine le nom de la page suivante dans la requête.
HasNextFlagJsonPath Faux ficelle Définit le chemin d’accès à un attribut d’indicateur HasNextPage lors de la détermination si d’autres pages sont laissées dans la réponse.
NextPageRequestHeader Faux ficelle Détermine le nom de l’en-tête de la page suivante dans la requête.
PaginationInfoPlacement Faux Chaîne Comment les informations de pageage sont remplies. Accepte soit « QueryString » soit « RequestBody »
PagingQueryParamOnly Faux Booléen Si elle est réglée sur true, elle omettra tous les autres paramètres de requête sauf les paramètres de requête de pagination.

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.

Champ Requise Catégorie Descriptif
Taille de la Page Faux Nombre entier Nombre d’événements par page
PageSizeParameterName Faux Chaîne Nom du paramètre de requête pour la taille de page
OffsetParaName Faux Chaîne Nom du paramètre de requête de requête suivant. Le CCF calcule la valeur de décalage pour chaque requête (tous les événements ingérés + 1)
PaginationInfoPlacement Faux Chaîne Comment les informations de pageage sont remplies. Accepte soit « QueryString » soit « RequestBody »
PagingQueryParamOnly Faux Booléen Si elle est réglée sur true, elle omettra tous les autres paramètres de requête sauf les paramètres de requête de pagination.

Exemple :

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

Configurer CountBasedPaging

CountBasedPaging permet au client de spécifier le nombre d’éléments à retourner dans la réponse. Cela est utile pour les API qui prennent en charge la pagination en fonction d’un paramètre count dans le cadre de la charge utile de réponse.

Champ Requise Catégorie Descriptif
pageNumberParaName Vrai Chaîne Nom du paramètre du numéro de page dans la requête HTTP
Taille de la Page Faux Nombre entier Nombre d’événements par page
ZeroBasedIndexing Faux Booléen Indicateur pour indiquer si le nombre est de base zéro
HasNextFlagJsonPath Faux Chaîne Chemin d’accès JSON de l’indicateur dans la charge utile de réponse HTTP pour indiquer qu’il y a plus de pages
TotalResultsJsonPath Faux Chaîne Chemin JSON du nombre total de résultats dans la charge utile de réponse HTTP
PageNumberJsonPath Faux Chaîne Obligatoire si totalResultsJsonPath est fourni. Chemin d’accès JSON du numéro de page dans la charge utile de réponse HTTP
PageCountJsonPath Faux Chaîne Obligatoire si totalResultsJsonPath est fourni. Chemin d’accès JSON du nombre de pages dans la charge utile de réponse HTTP
PaginationInfoPlacement Faux Chaîne Comment les informations de pageage sont remplies. Accepte soit « QueryString » soit « RequestBody »
PagingQueryParamOnly Faux Booléen Si elle est réglée sur true, elle omettra tous les autres paramètres de requête sauf les paramètres de requête de pagination.

Exemple :

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

Configuration DCR

Champ Requise Catégorie Descriptif
DataCollectionEndpoint Vrai Chaîne DCE (point de terminaison de collecte de données) par exemple : https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId Vrai Chaîne ID immuable DCR. Recherchez-le en consultant la réponse de création de DCR ou à l’aide de l’API DCR
StreamName Vrai ficelle Cette valeur est définie streamDeclaration dans la DCR (le préfixe doit commencer par Custom-)

Exemple de connecteur de données CCF

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

{
   "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": ["$"]
      }
   }
}
  • Last updated on