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

Vous pouvez créer un RestApiPoller connecteur de données avec ccf (Codeless Connector Framework) en utilisant cet article en complément de la documentation Microsoft Sentinel API REST pour les connecteurs de données.

Chaque connecteur de données 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. Vous pouvez terminer le modèle de déploiement pour le connecteur de données CCF à l’aide de la configuration JSON que vous générez avec cet article.

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

Création ou mise à jour de connecteurs de données

Recherchez la dernière version stable ou préliminaire de l’API en référençant les create opérations ou update dans la documentation de l’API REST. La différence entre les create opérations et update est que update nécessite la etag valeur .

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 Description
dataConnectorId ID du connecteur de données. Il doit s’agir d’un nom unique identique au name paramètre dans le corps de la requête.
resourceGroupName Nom du groupe de ressources, qui ne respecte pas la casse.
subscriptionId ID de l’abonnement cible.
workspaceName Nom de l’espace de travail, pas l’ID.
Le modèle regex est ^[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 pour 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 est un connecteur de données CCF de pollur d’API que vous pouvez utiliser pour personnaliser la pagination, l’autorisation et les charges utiles de demande/réponse pour votre source de données.

Nom Obligatoire Type Description
name Vrai String Nom unique de la connexion qui correspond au paramètre URI.
kind Vrai String Valeur kind . Ce champ doit être défini sur RestApiPoller.
etag GUID Valeur etag . Ce champ doit être laissé vide pour la création d’un nouveau connecteur. Pour les opérations de mise à jour, etag doit correspondre au connecteur etag existant (GUID).
properties.connectorDefinitionName String Nom de la DataConnectorDefinition ressource 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.
properties.auth Vrai JSON imbriqué Propriétés d’authentification pour l’interrogation des données. Pour plus d’informations, consultez Configuration de l’authentification.
properties.request Vrai JSON imbriqué Charge utile de la requête pour interroger les données, comme le point de terminaison d’API. Pour plus d’informations, consultez Demander la configuration.
properties. response Vrai JSON imbriqué L’objet de réponse et le message imbriqué retournés par l’API lorsqu’elle interroge les données. Pour plus d’informations, consultez Configuration de la réponse.
properties.paging JSON imbriqué Charge utile de pagination lors de l’interrogation des données. Pour plus d’informations, consultez Configuration de la pagination.
properties.dcrConfig JSON imbriqué Paramètres requis lorsque les données sont envoyées à une règle de collecte de données (DCR). Pour plus d’informations, accédez à Configuration DCR.

Configuration de l’authentification

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

Remarque

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

Il est recommandé d’utiliser des paramètres dans la section d’authentification au lieu de coder en dur les informations d’identification. Pour plus d’informations, consultez Sécuriser l’entrée confidentielle.

Pour créer le modèle de déploiement, qui utilise également des paramètres, vous devez placer les paramètres dans une séquence d’échappement dans cette section avec un démarrage [supplémentaire. Cette étape permet aux paramètres d’affecter une valeur en fonction de l’interaction de l’utilisateur avec le connecteur. Pour plus d’informations, consultez Caractères d’échappement d’expressions de modèle.

Pour permettre la saisie des informations d’identification à partir de l’interface utilisateur, la connectorUIConfig section nécessite que vous entrez les paramètres souhaités dans instructions. Pour plus d’informations, consultez Informations de référence sur les définitions de connecteur de données pour l’infrastructure de connecteur sans code.

Authentification de base

Field Obligatoire Type
UserName Vrai String
Password Vrai String

Voici un exemple d’authentification de base qui utilise des paramètres définis dans connectorUIconfig:

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

Clé API

Field Obligatoire Type Description Valeur par défaut
ApiKey Vrai String Clé secrète utilisateur.
ApiKeyName String Nom de l’en-tête d’URI qui contient la ApiKey valeur. Authorization
ApiKeyIdentifier String Valeur de chaîne pour ajouter le jeton. token
IsApiKeyInPostPayload Booléen Valeur qui détermine s’il faut envoyer le secret dans le corps plutôt que dans l’en-tête POST . false

APIKey exemples d’authentification :

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

Le résultat de cet exemple est le secret défini à partir de l’entrée utilisateur envoyée dans l’en-tête suivant : X-MyApp-Auth-HeaderBearer apikey.

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

Cet exemple utilise les valeurs par défaut et produit l’en-tête suivant : Authorizationtoken 123123123.

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

Étant donné que ApiKeyName est explicitement défini sur "", le résultat est l’en-tête suivant : Authorization123123123.

OAuth2

L’infrastructure de connecteur sans code prend en charge l’octroi de code d’autorisation OAuth 2.0 et les informations d’identification du client. Le type d’octroi de code d’autorisation est utilisé par les clients confidentiels et publics pour échanger un code d’autorisation contre 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 à partir de l’URL et l’utilise pour demander un jeton d’accès.

Field Obligatoire Type Description
ClientId Vrai. String ID client.
ClientSecret Vrai. String Clé secrète client.
AuthorizationCode True lorsque la grantType valeur est authorization_code. String Si le type d’octroi est authorization_code, cette valeur de champ est le code d’autorisation retourné par le serveur d’authentification.
Scope True pour le type d’octroi authorization_code .
Facultatif pour le type d’octroi client_credentials .		 String Liste d’étendues séparées par des espaces pour le consentement de l’utilisateur. Pour plus d’informations, consultez Étendues et autorisations OAuth2.
RedirectUri True lorsque la grantType valeur est authorization_code. String L’URL de redirection doit être https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights.
GrantType Vrai. String Type d’octroi. Peut être authorization_code ou client_credentials.
TokenEndpoint Vrai. String URL permettant d’échanger du code avec un jeton valide dans l’octroi authorization_code , ou un ID client et un secret avec un jeton valide dans l’octroi client_credentials .
TokenEndpointHeaders Objet Objet clé/valeur facultatif pour envoyer des en-têtes personnalisés au serveur de jetons.
TokenEndpointQueryParameters Objet Objet clé/valeur facultatif pour envoyer des paramètres de requête personnalisés au serveur de jetons.
AuthorizationEndpoint Vrai. String URL du consentement de l’utilisateur pour le authorization_code flux.
AuthorizationEndpointHeaders Objet Objet clé/valeur facultatif pour envoyer des en-têtes personnalisés au serveur d’authentification.
AuthorizationEndpointQueryParameters Objet Paire clé/valeur facultative utilisée dans une demande de flux de code d’autorisation OAuth2.

Vous pouvez utiliser le flux de code d’authentification pour extraire des données au nom des autorisations d’un utilisateur. Vous pouvez utiliser les informations d’identification du client pour 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’y a aucun utilisateur dans le flux d’informations d’identification du client, aucun point de terminaison d’autorisation n’est nécessaire, uniquement un point de terminaison de jeton.

Voici un exemple de 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"
}

Voici un exemple de 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 JSON Web Token (JWT) prend en charge l’obtention de jetons via des informations d’identification de nom d’utilisateur et de 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 (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"
}

Suivez ce flux d’authentification :

  1. Envoyer des informations d’identification à TokenEndpoint pour obtenir un jeton JWT, lors de l’utilisation userName de et password, IsCredentialsInHeaders est utilisé pour déterminer où placer les informations d’identification dans la requête.

    • If IsCredentialsInHeaders: true: envoie un en-tête d’authentification de base avec username:password.
    • If IsCredentialsInHeaders: false: envoie des informations d’identification dans un POST corps.

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

  3. L’en-tête Authorization pour les jetons JWT est une constante et sera toujours « Authorization ».

Field Obligatoire Type Description
type Vrai String Type. Doit être JwtToken
userName True (si userToken n’est pas utilisé) Objet Paire clé/valeur pour les informations d’identification userName . 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 sont envoyés dans la demande de corps, spécifiez Key et Value.
password 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 .userName Si userName et password sont envoyés dans la demande de corps, spécifiez Key et Value.
userToken True (si userName n’est pas utilisé) String Jeton utilisateur généré par le client pour obtenir le jeton système pour l’authentification.
UserTokenPrepend Faux String Valeur qui indique s’il faut ajouter du texte avant le jeton. La valeur par défaut est Bearer.
NoAccessTokenPrepend Faux Booléen Indicateur d’accès qui indique que le jeton ne doit rien ajouter.
TokenEndpointHttpMethod Faux String Méthode HTTP pour le point de terminaison de jeton. Il peut s’agir de Get ou Post. La valeur par défaut est Post.
TokenEndpoint Vrai String Point de terminaison d’URL utilisé pour obtenir le jeton JWT.
IsCredentialsInHeaders Booléen Valeur qui indique s’il faut envoyer des informations d’identification en tant qu’en-tête d’authentification de base (true) par rapport à un POST corps (false), ignorée lors de l’utilisation userTokende . La valeur par défaut est false.
IsJsonRequest Booléen Valeur qui indique s’il faut envoyer la demande au format JSON (en-tête Content-Type = application/json) ou encodé sous forme (en-tête Content-Type = application/x-www-form-urlencoded). La valeur par défaut est false.
JwtTokenJsonPath String Valeur qui indique la JSONPath valeur à utiliser pour extraire le jeton de la réponse. Par exemple : $.access_token.
JwtTokenInResponseHeader Booléen Valeur qui indique s’il faut extraire le jeton de l’en-tête de réponse par rapport au corps. La valeur par défaut est false.
JwtTokenHeaderName. String Valeur qui indique le nom de l’en-tête lorsque le jeton se trouve dans l’en-tête de réponse. La valeur par défaut est Authorization.
JwtTokenIdentifier String 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.
Headers Objet En-têtes personnalisés à inclure lors de l’envoi de la requête au point de terminaison de jeton.
RequestTimeoutInSeconds Entier Délai d’expiration de la demande en secondes. La valeur par défaut est 100, avec une valeur maximale de 180.

Remarque

Limitations

  • Nécessite l’authentification par nom d’utilisateur et mot de passe pour l’acquisition de jetons
  • Ne prend pas en charge les demandes de jeton basées sur une clé d’API
  • Ne prend pas en charge l’authentification d’en-tête personnalisée (sans nom d’utilisateur et mot de passe)

Configuration de la demande

La section demande définit la façon dont le connecteur de données CCF envoie les demandes à votre source de données (par exemple, le point de terminaison d’API et la fréquence d’interrogation de ce point de terminaison).

Field Obligatoire Type Description
ApiEndpoint Vrai. String Ce champ détermine l’URL du serveur distant et définit le point de terminaison à partir duquel extraire les données.
RateLimitQPS Entier Ce champ définit le nombre d’appels ou de requêtes autorisés en une seconde pour la requête initiale. Elle ne s’applique pas aux demandes paginées. Pour limiter la pagination, définissez PaginatedCallsPerSecondégalement .
PaginatedCallsPerSecond Double (0...1000) Ce champ définit le nombre d’appels par seconde autorisés pour les demandes paginées à l’API RESTful. Il introduit un délai de (1000 / paginatedCallsPerSecond) millisecondes entre chaque appel d’API paginé. Cette limitation s’applique uniquement aux demandes de pagination et est distincte de RateLimitQPS, qui contrôle le taux de requêtes initial. En règle générale, il s’agit de définir la même valeur que RateLimitQPS pour respecter la limite de débit de la source de données pour toutes les requêtes. 0 value signifie qu’aucune limitation de pagination n’est appliquée.
RateLimitConfig Objet Ce champ définit la configuration de limite de débit pour l’API RESTful. Pour plus d’informations, accédez à l’exempleRateLimitConfig.
QueryWindowInMin Entier Ce champ 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 String Ce champ définit la méthode d’API : GET(par défaut) ou POST.
QueryTimeFormat String Ce champ 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 partout où cette variable est utilisée. Les valeurs possibles sont les constantes : UnixTimestamp, UnixTimestampInMillsou toute autre représentation valide de date et d’heure. Par exemple : yyyy-MM-dd, MM/dd/yyyy HH:mm:ss.
La valeur par défaut est ISO 8601 UTC.
RetryCount Entier (1...6) Ce champ définit que les valeurs de 1 à 6 nouvelles tentatives sont autorisées à récupérer après une défaillance. La valeur par défaut est 3.
TimeoutInSeconds Entier (1...180) Ce champ définit le délai d’expiration de la demande en secondes. La valeur par défaut est 20.
IsPostPayloadJson Booléen Ce champ détermine si la POST charge utile est au format JSON. La valeur par défaut est false.
Headers Objet Ce champ inclut des paires clé/valeur qui définissent les en-têtes de requête.
QueryParameters Objet Ce champ inclut des paires clé/valeur qui définissent les paramètres de requête de requête.
StartTimeAttributeName True lorsque la EndTimeAttributeName valeur est définie. String Ce champ définit le nom du paramètre de requête pour l’heure de début de la requête. Pour plus d’informations, accédez à l’exempleStartTimeAttributeName.
EndTimeAttributeName True quand StartTimeAttributeName est défini. String Ce champ définit le nom du paramètre de requête pour l’heure de fin de la requête.
QueryTimeIntervalAttributeName String Ce champ est utilisé si le point de terminaison nécessite un format spécialisé pour interroger les données sur une période donnée. Utilisez cette propriété avec les QueryTimeIntervalPrepend paramètres et QueryTimeIntervalDelimiter . Pour plus d’informations, accédez à l’exempleQueryTimeIntervalAttributeName.
QueryTimeIntervalPrepend True quand QueryTimeIntervalAttributeName est défini. String Référence QueryTimeIntervalAttributeName.
QueryTimeIntervalDelimiter True quand QueryTimeIntervalAttributeName est défini. String Référence QueryTimeIntervalAttributeName.
QueryParametersTemplate String Ce champ fait référence au modèle de requête à utiliser lors de la transmission de paramètres dans des scénarios avancés.

Par exemple : "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}".
InitialCheckpointTimeUtc DateTime (UTC) Spécifie l’heure de début de la requête pour le tout premier sondage lorsqu’il n’existe aucun point de contrôle stocké. Une fois qu’un point de contrôle est conservé après le premier sondage réussi, cette valeur est ignorée. Ce paramètre prend effet uniquement lorsque la configuration de la demande du connecteur définit un paramètre de requête au début (par startTimeAttributeName exemple, ou le {_QueryWindowStartTime} jeton de remplacement) sans paramètre d’heure de fin correspondant. Elle n’a aucun effet sur les connecteurs qui s’appuient uniquement sur des curseurs ou des jetons de pagination. Format : ISO 8601 UTC datetime (par exemple, 2024-01-15T00:00:00Z).

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

Variable intégrée À utiliser dans queryParameters À utiliser dans queryParametersTemplate
_QueryWindowStartTime Oui Oui
_QueryWindowEndTime Oui Oui
_APIKeyName Non Oui
_APIKey Non Oui

Exemple StartTimeAttributeName

Prenons l’exemple suivant :

  • 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 l’exemple suivant :

  • 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 l’exemple suivant :

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 taux de requêtes.

Exemples de requêtes qui utilisent 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 Paramètres de requête Microsoft API 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.

Vous obtenez les mêmes résultats 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}"
  }
}

Il existe une autre option pour les situations où la source de données attend deux 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",
}

Cette option envoie une GET requête à 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 envoie une POST requête avec des paramètres dans le corps :

"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 la réponse

Définissez la façon dont votre connecteur de données gère les réponses à l’aide des paramètres suivants :

Field Obligatoire Type Description
EventsJsonPaths Vrai Liste de chaînes Définit le chemin d’accès au message dans la réponse JSON. Une expression de chemin JSON spécifie un chemin d’accès à un élément, ou à un ensemble d’éléments, dans une structure JSON.
SuccessStatusJsonPath String 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 l’être.
SuccessStatusValue String Définit le chemin d’accès à la valeur du message de réussite dans le json de réponse.
IsGzipCompressed Booléen Détermine si la réponse est compressée dans un fichier GZIP.
format Vrai String Détermine si le format est json, csvou xml.
CompressionAlgo String Définit l’algorithme de compressions, ou multi-gzipdeflate. Pour l’algorithme de compression GZIP, configurez IsGzipCompressed sur True au lieu de définir une valeur pour ce paramètre.
CsvDelimiter String Référence si le format de réponse est CSV et que vous souhaitez modifier le délimiteur CSV par défaut de ",".
HasCsvBoundary Booléen Indique si les données CSV ont une limite.
HasCsvHeader Booléen Indique si les données CSV ont un en-tête. La valeur par défaut est True.
CsvEscape String Définit un 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 Fait référence à un cas spécial dans lequel le serveur distant retourne un objet au lieu d’une liste d’événements où chaque propriété inclut des données.

Remarque

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

Exemples de configuration de réponse

Une réponse du serveur au format JSON est attendue. La réponse contient les données demandées dans la valeur de propriété. La propriété response status 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 la pagination

Lorsque la source de données ne peut pas envoyer la charge utile de réponse entière à la fois, 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 suivante et précédente ?
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 pagination signifie que la réponse de l’API inclut les éléments suivants :

  • En-tête Link de réponse HTTP.
  • Chemin JSON permettant de récupérer le lien à partir du corps de la réponse.

PersistentLinkHeaderLa pagination -type a les mêmes propriétés que , sauf que LinkHeaderl’en-tête de lien est conservé dans le stockage principal. Cette option active les liens de pagination entre les fenêtres de requête.

Par exemple, certaines API ne prennent pas en charge les heures de début ou de fin des requêtes. Au lieu de cela, ils prennent en charge un curseur côté serveur. Vous pouvez utiliser des types de page persistants pour mémoriser le curseur côté serveur. Pour plus d’informations, consultez Qu’est-ce qu’un curseur ?.

Remarque

Une seule requête pour le connecteur peut s’exécuter avec PersistentLinkHeader pour éviter les conditions de concurrence sur le curseur côté serveur. Ce problème peut affecter la latence.

Field Obligatoire Type Description
LinkHeaderTokenJsonPath Faux String 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 json suivant : { nextPage: "foo", value: [{data}]}, la LinkHeaderTokenJsonPath valeur est $.nextPage.
PageSize Faux Entier Utilisez cette propriété pour déterminer le nombre d’événements par page.
PageSizeParameterName Faux String Utilisez ce nom de paramètre de requête pour indiquer la taille de la page.
PagingInfoPlacement Faux String Utilisez cette propriété pour déterminer comment les informations de pagination sont remplies. Accepte ou QueryStringRequestBody.
PagingQueryParamOnly Faux Booléen Utilisez cette propriété pour spécifier les paramètres de requête. Si la valeur est true, elle omet tous les autres paramètres de requête, à l’exception des 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-type 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.

Field Obligatoire Type Description
PageSize Faux Entier Nombre d’événements par page.
PageSizeParameterName Faux String Nom du paramètre de requête pour la taille de page.
NextPageUrl Faux String Champ utilisé uniquement si le connecteur est destiné à l’API Coralogix.
NextPageUrlQueryParameters Faux Objet Paires clé/valeur qui ajoutent un paramètre de requête personnalisé à chaque requête pour la page suivante.
NextPageParaName Faux String Nom de la page suivante dans la demande.
HasNextFlagJsonPath Faux String Chemin d’accès à l’attribut d’indicateur HasNextPage .
NextPageRequestHeader Faux String Nom d’en-tête de page suivant dans la requête.
NextPageUrlQueryParametersTemplate Faux String Champ utilisé uniquement si le connecteur est destiné à l’API Coralogix.
PagingInfoPlacement Faux String Champ qui détermine la façon dont les informations de pagination sont remplies. Accepte ou QueryStringRequestBody.
PagingQueryParamOnly Faux Booléen Champ qui détermine les paramètres de requête. Si la valeur est true, elle omet tous les autres paramètres de requête, à l’exception des 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-type pagination utilise un jeton (un hachage ou un 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 conserver l’état exact entre les requêtes.

PersistentToken la pagination utilise un jeton qui persiste 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.

Field Obligatoire Type Description
PageSize Faux Entier Nombre d’événements par page.
PageSizeParameterName Faux String Nom du paramètre de requête pour la taille de page.
NextPageTokenJsonPath Faux String Chemin JSON du jeton de page suivant dans le corps de la réponse.
NextPageTokenResponseHeader Faux String Champ qui spécifie que si NextPageTokenJsonPath est vide, utilisez le jeton dans ce nom d’en-tête pour la page suivante.
NextPageParaName Faux String Champ qui détermine le nom de la page suivante dans la demande.
HasNextFlagJsonPath Faux String Champ qui définit le chemin d’accès à un HasNextPage attribut d’indicateur lors de la détermination de l’existence de pages supplémentaires dans la réponse.
NextPageRequestHeader Faux String Champ qui détermine le nom d’en-tête de page suivant dans la demande.
PagingInfoPlacement Faux String Champ qui détermine la façon dont les informations de pagination sont remplies. Accepte ou QueryStringRequestBody.
PagingQueryParamOnly Faux Booléen Champ qui détermine les paramètres de requête. Si la valeur est true, elle omet tous les autres paramètres de requête, à l’exception des 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 le décalage

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

Field Obligatoire Type Description
PageSize Faux Entier Nombre d’événements par page.
PageSizeParameterName Faux String Nom du paramètre de requête pour la taille de page.
OffsetParaName Faux String Nom du paramètre de requête de requête suivante. Le CCF calcule la valeur de décalage pour chaque requête (tous les événements ingérés + 1).
PagingInfoPlacement Faux String Champ qui détermine la façon dont les informations de pagination sont remplies. Accepte ou QueryStringRequestBody.
PagingQueryParamOnly Faux Booléen Champ qui détermine les paramètres de requête. Si la valeur est true, elle omet tous les autres paramètres de requête, à l’exception des paramètres de requête de pagination.

Exemple :

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

Configurer CountBasedPaging

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

Field Obligatoire Type Description
pageNumberParaName Vrai String Nom du paramètre du numéro de page dans la requête HTTP.
PageSize Faux Entier Nombre d’événements par page.
ZeroBasedIndexing Faux Booléen Indicateur qui indique que le nombre est basé sur zéro.
HasNextFlagJsonPath Faux String Chemin d’accès JSON de l’indicateur dans la charge utile de réponse HTTP qui indique qu’il y a plus de pages.
TotalResultsJsonPath Faux String Chemin JSON du nombre total de résultats dans la charge utile de réponse HTTP.
PageNumberJsonPath Faux String Chemin d’accès JSON du numéro de page dans la charge utile de réponse HTTP. Obligatoire si totalResultsJsonPath est fourni.
PageCountJsonPath Faux String Chemin d’accès JSON du nombre de pages dans la charge utile de réponse HTTP. Obligatoire si totalResultsJsonPath est fourni.
PagingInfoPlacement Faux String Champ qui détermine la façon dont les informations de pagination sont remplies. Accepte ou QueryStringRequestBody.
PagingQueryParamOnly Faux Booléen Champ qui détermine les paramètres de requête. Si la valeur est true, elle omet tous les autres paramètres de requête, à l’exception des 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 de DCR

Field Obligatoire Type Description
DataCollectionEndpoint Vrai String Point de terminaison de collecte de données (DCE). Par exemple : https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId Vrai String ID immuable DCR. Recherchez-la en consultant la réponse de création de DCR ou en utilisant l’API DCR.
StreamName Vrai String 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