RestApiPoller-gegevensconnector voor het Codeless Connector Framework

U kunt een RestApiPoller gegevensconnector maken met het Codeless Connector Framework (CCF) met behulp van dit artikel als aanvulling op de documenten Microsoft Sentinel REST API voor gegevensconnectors.

Elke gegevensconnector vertegenwoordigt een specifieke verbinding van een Microsoft Sentinel-gegevensconnector. Eén gegevensconnector kan meerdere verbindingen hebben, waarmee gegevens van verschillende eindpunten worden opgehaald. U kunt de implementatiesjabloon voor de CCF-gegevensconnector voltooien met behulp van de JSON-configuratie die u met dit artikel maakt.

Zie Een connector zonder code maken voor Microsoft Sentinel voor meer informatie.

Gegevensconnectors maken of bijwerken

Zoek de nieuwste stabiele of preview-API-versie door te verwijzen naar de create bewerkingen of update in de REST API-documenten. Het verschil tussen de create bewerkingen en update is dat update de etag waarde is vereist.

PUT Methode:

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

URI-parameters

Zie Gegevensconnectors: URI-parameters maken of bijwerken voor meer informatie over de nieuwste API-versie.

Naam	Beschrijving
`dataConnectorId`	De gegevensconnector-id. Het moet een unieke naam zijn die hetzelfde is als de `name` parameter in de aanvraagbody.
`resourceGroupName`	De naam van de resourcegroep, niet hoofdlettergevoelig.
`subscriptionId`	De id van het doelabonnement.
`workspaceName`	De naam van de werkruimte, niet de id. Het regex-patroon is `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`.
`api-version`	De API-versie die voor deze bewerking moet worden gebruikt.

Aanvraagtekst

De aanvraagtekst voor een RestApiPoller CCF-gegevensconnector heeft de volgende structuur:

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

RestApiPoller

RestApiPoller is een API poller CCF-gegevensconnector die u kunt gebruiken om paging, autorisatie en nettoladingen voor aanvragen/antwoorden voor uw gegevensbron aan te passen.

Naam	Vereist	Type	Beschrijving
`name`	Waar	Tekenreeks	De unieke naam van de verbinding die overeenkomt met de URI-parameter.
`kind`	Waar	Tekenreeks	De `kind` waarde. Dit veld moet worden ingesteld op `RestApiPoller`.
`etag`		GUID	De `etag` waarde. Dit veld moet leeg zijn om een nieuwe connector te kunnen maken. Voor updatebewerkingen `etag` moet overeenkomen met de bestaande connector `etag` (GUID).
`properties.connectorDefinitionName`		Tekenreeks	De naam van de `DataConnectorDefinition` resource die de gebruikersinterfaceconfiguratie van de gegevensconnector definieert. Ga naar Definitie van gegevensconnector voor meer informatie.
`properties.auth`	Waar	Geneste JSON	De verificatie-eigenschappen voor het pollen van de gegevens. Ga naar Verificatieconfiguratie voor meer informatie.
`properties.request`	Waar	Geneste JSON	De nettolading van de aanvraag voor het pollen van de gegevens, zoals het API-eindpunt. Ga voor meer informatie naar Configuratie aanvragen.
`properties. response`	Waar	Geneste JSON	Het antwoordobject en het geneste bericht dat de API retourneert wanneer de gegevens worden gepeild. Ga naar Antwoordconfiguratie voor meer informatie.
`properties.paging`		Geneste JSON	De nettolading voor paginering bij het pollen van de gegevens. Ga voor meer informatie naar Paging-configuratie.
`properties.dcrConfig`		Geneste JSON	De vereiste parameters wanneer de gegevens worden verzonden naar een regel voor gegevensverzameling (DCR). Ga naar DCR-configuratie voor meer informatie.

Verificatieconfiguratie

De CCF ondersteunt de volgende verificatietypen:

Basic
API-sleutel
OAuth2
JWT

Opmerking

CCF OAuth2-implementatie biedt geen ondersteuning voor referenties voor clientcertificaten.

Als aanbevolen procedure gebruikt u parameters in de verificatiesectie in plaats van referenties vast te coderen. Zie Vertrouwelijke invoer beveiligen voor meer informatie.

Als u de implementatiesjabloon wilt maken, die ook parameters gebruikt, moet u de parameters in deze sectie met een extra start [uitvoeren. Met deze stap kunnen de parameters een waarde toewijzen op basis van de interactie van de gebruiker met de connector. Zie Escape-tekens voor sjabloonexpressies voor meer informatie.

Als u wilt dat de referenties vanuit de gebruikersinterface worden ingevoerd, moet u in de connectorUIConfig sectie de gewenste parameters invoeren in instructions. Zie Naslaginformatie over gegevensconnectordefinities voor het Codeless Connector Framework voor meer informatie.

Basisverificatie

Veld	Vereist	Type
`UserName`	Waar	Tekenreeks
`Password`	Waar	Tekenreeks

Hier volgt een voorbeeld van basisverificatie die gebruikmaakt van parameters die zijn gedefinieerd in connectorUIconfig:

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

API-sleutel

Veld	Vereist	Type	Beschrijving	Standaardwaarde
`ApiKey`	Waar	Tekenreeks	Geheime sleutel van de gebruiker.
`ApiKeyName`		Tekenreeks	Naam van de URI-header die de `ApiKey` waarde bevat.	`Authorization`
`ApiKeyIdentifier`		Tekenreeks	Tekenreekswaarde om het token voor te maken.	`token`
`IsApiKeyInPostPayload`		Booleaanse waarde	Waarde die bepaalt of het geheim in de `POST` hoofdtekst moet worden verzonden in plaats van de koptekst.	`false`

APIKey verificatievoorbeelden:

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

Het resultaat van dit voorbeeld is het geheim dat is gedefinieerd op basis van de gebruikersinvoer die is verzonden in de volgende header: X-MyApp-Auth-Header: Bearer apikey.

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

In dit voorbeeld worden de standaardwaarden gebruikt en wordt de volgende header weergegeven: Authorization: token 123123123.

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

Omdat ApiKeyName expliciet is ingesteld op "", is het resultaat de volgende header: Authorization: 123123123.

OAuth2

Het Codeless Connector Framework ondersteunt het verlenen van OAuth 2.0-autorisatiecode en clientreferenties. Het type autorisatiecodetoekenning wordt gebruikt door vertrouwelijke en openbare clients om een autorisatiecode uit te wisselen voor een toegangstoken.

Nadat de gebruiker via de omleidings-URL terugkeert naar de client, haalt de toepassing de autorisatiecode op van de URL en gebruikt deze om een toegangstoken aan te vragen.

Veld	Vereist	Type	Beschrijving
`ClientId`	Waar.	Tekenreeks	De client-id.
`ClientSecret`	Waar.	Tekenreeks	Het clientgeheim.
`AuthorizationCode`	Waar wanneer de `grantType` waarde is `authorization_code`.	Tekenreeks	Als het toekenningstype is, is deze veldwaarde de autorisatiecode die door de verificatieserver is `authorization_code`geretourneerd.
`Scope`	Waar voor het toekenningstype `authorization_code` . Optioneel voor het toekenningstype `client_credentials` .	Tekenreeks	Een door spaties gescheiden lijst met bereiken voor gebruikerstoestemming. Zie OAuth2-bereiken en -machtigingen voor meer informatie.
`RedirectUri`	Waar wanneer de `grantType` waarde is `authorization_code`.	Tekenreeks	De URL voor omleiding moet zijn `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`.
`GrantType`	Waar.	Tekenreeks	Het toekenningstype. Kan of `client_credentials`zijn`authorization_code`.
`TokenEndpoint`	Waar.	Tekenreeks	De URL voor het uitwisselen van code met een geldig token in de `authorization_code` toekenning of een client-id en geheim met een geldig token in de `client_credentials` toekenning.
`TokenEndpointHeaders`		Object	Een optioneel sleutel-/waardeobject voor het verzenden van aangepaste headers naar de tokenserver.
`TokenEndpointQueryParameters`		Object	Een optioneel sleutel-/waardeobject voor het verzenden van aangepaste queryparameters naar de tokenserver.
`AuthorizationEndpoint`	Waar.	Tekenreeks	De URL voor gebruikerstoestemming voor de `authorization_code` stroom.
`AuthorizationEndpointHeaders`		Object	Een optioneel sleutel-/waardeobject voor het verzenden van aangepaste headers naar de verificatieserver.
`AuthorizationEndpointQueryParameters`		Object	Een optioneel sleutel-waardepaar dat wordt gebruikt in een OAuth2-autorisatiecodestroomaanvraag.

U kunt de verificatiecodestroom gebruiken om gegevens op te halen namens de machtigingen van een gebruiker. U kunt clientreferenties gebruiken om gegevens op te halen met toepassingsmachtigingen. De gegevensserver verleent toegang tot de toepassing. Omdat er geen gebruiker in de clientreferentiestroom is, is er geen autorisatie-eindpunt nodig, alleen een tokeneindpunt.

Hier volgt een voorbeeld van het OAuth2-toekenningstype authorization_code :

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

Hier volgt een voorbeeld van het OAuth2-toekenningstype 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

JSON Web Token -verificatie (JWT) ondersteunt het verkrijgen van tokens via gebruikersnaam- en wachtwoordreferenties en het gebruik ervan voor API-aanvragen.

Basisvoorbeeld

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

Referenties in POST-hoofdtekst (standaard)

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

Referenties in headers (basisverificatie)

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

Referenties in headers (gebruikerstoken)

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

Volg deze verificatiestroom:

Referenties verzenden naar TokenEndpoint om het JWT-token te verkrijgen bij gebruik van userName en password, IsCredentialsInHeaders wordt gebruikt om te bepalen waar referenties in de aanvraag moeten worden geplaatst.
- If IsCredentialsInHeaders: true: verzendt een basisverificatieheader met username:password.
- If IsCredentialsInHeaders: false: hiermee worden referenties in een hoofdtekst POST verzonden.
Pak het token uit met of JwtTokenJsonPath uit de antwoordheader.
De autorisatieheader voor de JWT-tokens is een constante en is altijd 'Autorisatie'.

Veld	Vereist	Type	Beschrijving
`type`	Waar	Tekenreeks	Het type. Moet `JwtToken`
`userName`	Waar (als `userToken` niet wordt gebruikt)	Object	Het sleutel-waardepaar voor de `userName` referentie. Als `userName` en `password` worden verzonden in de headeraanvraag, geeft u de `value` eigenschap op met de gebruikersnaam. Als `userName` en `password` worden verzonden in de hoofdtekstaanvraag, geeft u `Key` en op `Value`.
`password`	Waar (als `userToken` niet wordt gebruikt)	Object	Het sleutel-waardepaar voor de wachtwoordreferentie. Als `userName` en `password` worden verzonden in de headeraanvraag, geeft u de `value` eigenschap op met de `userName`. Als `userName` en `password` worden verzonden in de hoofdtekstaanvraag, geeft u `Key` en op `Value`.
`userToken`	Waar (als `userName` niet wordt gebruikt)	Tekenreeks	Het gebruikerstoken dat door de client wordt gegenereerd om het systeemtoken voor verificatie op te halen.
`UserTokenPrepend`	False	Tekenreeks	De waarde die aangeeft of tekst vóór het token moet worden voorbereid. Standaardinstelling: `Bearer`.
`NoAccessTokenPrepend`	False	Booleaanse waarde	Een toegangsvlag die aangeeft dat het token niets mag voorbereiden.
`TokenEndpointHttpMethod`	False	Tekenreeks	De HTTP-methode voor het tokeneindpunt. Dit kan of `Post`zijn`Get`. De standaardwaarde is `Post`.
`TokenEndpoint`	Waar	Tekenreeks	Het URL-eindpunt dat wordt gebruikt om het JWT-token te verkrijgen.
`IsCredentialsInHeaders`		Booleaanse waarde	De waarde die aangeeft of referenties moeten worden verzonden als een basisverificatieheader (`true`) versus een `POST` hoofdtekst (`false`), genegeerd bij gebruik van `userToken`. De standaardwaarde is `false`.
`IsJsonRequest`		Booleaanse waarde	De waarde die aangeeft of de aanvraag moet worden verzonden in JSON (header `Content-Type = application/json`) versus formuliergecodeerd (header `Content-Type = application/x-www-form-urlencoded`). De standaardwaarde is `false`.
`JwtTokenJsonPath`		Tekenreeks	De waarde die de `JSONPath` waarde aangeeft die moet worden gebruikt om het token uit het antwoord te extraheren. Bijvoorbeeld: `$.access_token`.
`JwtTokenInResponseHeader`		Booleaanse waarde	De waarde die aangeeft of het token moet worden geëxtraheerd uit de antwoordheader versus de hoofdtekst. De standaardwaarde is `false`.
`JwtTokenHeaderName`.		Tekenreeks	De waarde die de naam van de header aangeeft wanneer het token zich in de antwoordheader bevindt. De standaardwaarde is `Authorization`.
`JwtTokenIdentifier`		Tekenreeks	De id die wordt gebruikt om de JWT te extraheren uit een tokentekenreeks met een voorvoegsel.
`QueryParameters`		Object	De aangepaste queryparameters die moeten worden opgenomen bij het verzenden van de aanvraag naar het tokeneindpunt.
`Headers`		Object	De aangepaste headers die moeten worden opgenomen bij het verzenden van de aanvraag naar het tokeneindpunt.
`RequestTimeoutInSeconds`		Geheel getal	De time-out van de aanvraag in seconden. De standaardwaarde is `100`, met een maximumwaarde van `180`.

Opmerking

Beperkingen

Verificatie van gebruikersnaam en wachtwoord vereist voor het verkrijgen van tokens
Biedt geen ondersteuning voor API-tokenaanvragen op basis van sleutels
Biedt geen ondersteuning voor aangepaste headerverificatie (zonder gebruikersnaam en wachtwoord)

Aanvraagconfiguratie

In de aanvraagsectie wordt gedefinieerd hoe de CCF-gegevensconnector aanvragen naar uw gegevensbron verzendt (bijvoorbeeld het API-eindpunt en hoe vaak dat eindpunt moet worden gepeild).

Veld	Vereist	Type	Beschrijving
`ApiEndpoint`	Waar.	Tekenreeks	Dit veld bepaalt de URL voor de externe server en definieert het eindpunt waaruit gegevens moeten worden opgehaald.
`RateLimitQPS`		Geheel getal	Dit veld definieert het aantal aanroepen of query's dat in een seconde is toegestaan voor de eerste aanvraag. Deze is niet van toepassing op gepagineerde aanvragen. Als u paginering wilt beperken, stelt u ook in `PaginatedCallsPerSecond`.
`PaginatedCallsPerSecond`		Dubbel (0...1000)	Dit veld definieert het aantal aanroepen per seconde dat is toegestaan voor gepagineerde aanvragen voor de RESTful-API. Het introduceert een vertraging van `(1000 / paginatedCallsPerSecond)` milliseconden tussen elke gepagineerde API-aanroep. Deze beperking is alleen van toepassing op pagineringsaanvragen en staat los van `RateLimitQPS`, waarmee de initiële aanvraagsnelheid wordt bepaald. Dit wordt doorgaans dezelfde waarde ingesteld als `RateLimitQPS` om de frequentielimiet van de gegevensbron voor alle aanvragen te respecteren. `0` waarde betekent dat er geen pagineringsbeperking wordt toegepast.
`RateLimitConfig`		Object	Dit veld definieert de configuratie van de frequentielimiet voor de RESTful-API. Ga naar voorbeeld voor `RateLimitConfig` meer informatie.
`QueryWindowInMin`		Geheel getal	Dit veld definieert het beschikbare queryvenster in minuten. Het minimum is 1 minuut. De standaardwaarde is 5 minuten.
`HttpMethod`		Tekenreeks	Dit veld definieert de API-methode: `GET`(standaard) of `POST`.
`QueryTimeFormat`		Tekenreeks	Dit veld definieert de datum- en tijdnotatie die het eindpunt (externe server) verwacht. De CCF gebruikt de huidige datum en tijd overal waar deze variabele wordt gebruikt. Mogelijke waarden zijn de constanten: `UnixTimestamp`, `UnixTimestampInMills`of een andere geldige weergave van datum en tijd. Bijvoorbeeld: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss`. De standaardwaarde is `ISO 8601 UTC`.
`RetryCount`		Geheel getal (1...6)	Dit veld definieert dat waarden van `1` naar `6` nieuwe pogingen mogen worden hersteld na een fout. De standaardwaarde is `3`.
`TimeoutInSeconds`		Geheel getal (1...180)	Dit veld definieert de time-out van de aanvraag in seconden. De standaardwaarde is `20`.
`IsPostPayloadJson`		Booleaanse waarde	Dit veld bepaalt of de `POST` nettolading de JSON-indeling heeft. De standaardwaarde is `false`.
`Headers`		Object	Dit veld bevat sleutel-waardeparen waarmee de aanvraagheaders worden gedefinieerd.
`QueryParameters`		Object	Dit veld bevat sleutel-waardeparen waarmee de queryparameters van de aanvraag worden gedefinieerd.
`StartTimeAttributeName`	Waar wanneer de `EndTimeAttributeName` waarde is ingesteld.	Tekenreeks	Dit veld definieert de naam van de queryparameter voor de begintijd van de query. Ga naar voorbeeld voor `StartTimeAttributeName` meer informatie.
`EndTimeAttributeName`	Waar wanneer `StartTimeAttributeName` is ingesteld.	Tekenreeks	Dit veld definieert de naam van de queryparameter voor de eindtijd van de query.
`QueryTimeIntervalAttributeName`		Tekenreeks	Dit veld wordt gebruikt als het eindpunt een speciale indeling vereist voor het uitvoeren van query's op de gegevens in een tijdsbestek. Gebruik deze eigenschap met de `QueryTimeIntervalPrepend` parameters en `QueryTimeIntervalDelimiter` . Ga naar voorbeeld voor `QueryTimeIntervalAttributeName` meer informatie.
`QueryTimeIntervalPrepend`	Waar wanneer `QueryTimeIntervalAttributeName` is ingesteld.	Tekenreeks	Verwijzing `QueryTimeIntervalAttributeName`.
`QueryTimeIntervalDelimiter`	Waar wanneer `QueryTimeIntervalAttributeName` is ingesteld.	Tekenreeks	Verwijzing `QueryTimeIntervalAttributeName`.
`QueryParametersTemplate`		Tekenreeks	Dit veld verwijst naar de querysjabloon die moet worden gebruikt bij het doorgeven van parameters in geavanceerde scenario's. Bijvoorbeeld: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`.
`InitialCheckpointTimeUtc`		DateTime (UTC)	Hiermee geeft u de begintijd van de query voor de eerste poll wanneer er geen opgeslagen controlepunt bestaat. Zodra een controlepunt is behouden na de eerste geslaagde poll, wordt deze waarde genegeerd. Deze instelling wordt alleen van kracht wanneer de aanvraagconfiguratie van de connector een begintijdqueryparameter (zoals `startTimeAttributeName` of het `{_QueryWindowStartTime}` vervangende token) definieert zonder een bijbehorende eindtijdparameter. Dit heeft geen invloed op connectors die uitsluitend afhankelijk zijn van pagineringscursors of tokens. Indeling: ISO 8601 UTC datetime (bijvoorbeeld `2024-01-15T00:00:00Z`).

Wanneer de API complexe parameters vereist, gebruikt u queryParameters of queryParametersTemplate. Deze opdrachten bevatten enkele ingebouwde variabelen.

Ingebouwde variabele	Voor gebruik in `queryParameters`	Voor gebruik in `queryParametersTemplate`
`_QueryWindowStartTime`	Ja	Ja
`_QueryWindowEndTime`	Ja	Ja
`_APIKeyName`	Nee	Ja
`_APIKey`	Nee	Ja

Voorbeeld van StartTimeAttributeName

Bekijk dit voorbeeld:

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

De query die naar de externe server wordt verzonden, is: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Voorbeeld van QueryTimeIntervalAttributeName

Bekijk dit voorbeeld:

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

De query die naar de externe server wordt verzonden, is: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Voorbeeld van RateLimitConfig

Bekijk dit voorbeeld:

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

Wanneer het antwoord frequentielimietheaders bevat, kan de connector deze informatie gebruiken om de aanvraagsnelheid aan te passen.

Voorbeelden aanvragen die Microsoft Graph gebruiken als de gegevensbron-API

In dit voorbeeld worden berichten met een filterqueryparameter opgevraagd. Zie Queryparameters van Microsoft Graph API voor meer informatie.

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

In het vorige voorbeeld wordt een GET aanvraag verzonden naar https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. De tijdstempel wordt voor elke queryWindowInMin keer bijgewerkt.

U bereikt dezelfde resultaten met dit voorbeeld:

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

Er is een andere optie voor situaties waarin de gegevensbron twee queryparameters verwacht (één voor begintijd en één voor eindtijd).

Voorbeeld:

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

Met deze optie wordt een GET aanvraag verzonden naar https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Gebruik QueryParametersTemplatevoor complexe query's . In dit voorbeeld wordt een POST aanvraag met parameters in de hoofdtekst verzonden:

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

Antwoordconfiguratie

Definieer hoe uw gegevensconnector antwoorden verwerkt met behulp van de volgende parameters:

Veld	Vereist	Type	Beschrijving
`EventsJsonPaths`	Waar	Lijst met tekenreeksen	Hiermee definieert u het pad naar het bericht in de antwoord-JSON. Een JSON-padexpressie geeft een pad naar een element of een set elementen in een JSON-structuur op.
`SuccessStatusJsonPath`		Tekenreeks	Definieert het pad naar het succesbericht in de antwoord-JSON. Wanneer deze parameter is gedefinieerd, moet de `SuccessStatusValue` parameter ook worden gedefinieerd.
`SuccessStatusValue`		Tekenreeks	Hiermee definieert u het pad naar de waarde van het succesbericht in de antwoord-JSON.
`IsGzipCompressed`		Booleaanse waarde	Bepaalt of het antwoord is gecomprimeerd in een GZIP-bestand.
`format`	Waar	Tekenreeks	Bepaalt of de notatie , `csv`of `xml`is`json`.
`CompressionAlgo`		Tekenreeks	Definieert het algoritme voor compressies, ofwel `multi-gzip` of `deflate`. Voor het GZIP-compressie-algoritme configureert `IsGzipCompressed` u om `True` in plaats van een waarde in te stellen voor deze parameter.
`CsvDelimiter`		Tekenreeks	Verwijzingen als de antwoordindeling CSV is en u het standaard-CSV-scheidingsteken van `","`wilt wijzigen.
`HasCsvBoundary`		Booleaanse waarde	Geeft aan of de CSV-gegevens een grens hebben.
`HasCsvHeader`		Booleaanse waarde	Geeft aan of de CSV-gegevens een header hebben. De standaardwaarde is `True`.
`CsvEscape`		Tekenreeks	Hiermee definieert u een escape-teken voor een veldgrens. De standaardwaarde is `"` Een CSV met kopteksten `id,name,avg` en een rij met gegevens met spaties, zoals `1,"my name",5.5` , vereist bijvoorbeeld de `"` veldgrens.
`ConvertChildPropertiesToArray`		Booleaanse waarde	Verwijst naar een speciaal geval waarin de externe server een object retourneert in plaats van een lijst met gebeurtenissen waarbij elke eigenschap gegevens bevat.

Opmerking

Het csv-indelingstype wordt geparseerd door de RFC4180 specificatie.

Voorbeelden van antwoordconfiguratie

Er wordt een serverantwoord in JSON-indeling verwacht. Het antwoord bevat de aangevraagde gegevens in de eigenschapswaarde. De status van de antwoordeigenschap geeft aan dat de gegevens alleen moeten worden opgenomen als de waarde is success.

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

Het verwachte antwoord in dit voorbeeld bereidt zich voor op een CSV zonder header.

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

Pagingconfiguratie

Wanneer de gegevensbron niet de volledige nettolading van het antwoord in één keer kan verzenden, moet de CCF-gegevensconnector weten hoe delen van de gegevens op antwoordpagina's moeten worden ontvangen. De wisseltypen waaruit u kunt kiezen, zijn:

Pagingtype	Beslissingsfactor
`LinkHeader` `PersistentLinkHeader` `NextPageUrl`	Bevat het API-antwoord koppelingen naar de volgende en vorige pagina's?
`NextPageToken` `PersistentToken`	Heeft het API-antwoord een token of cursor voor de volgende en vorige pagina's?
`Offset`	Ondersteunt het API-antwoord een parameter voor het aantal objecten dat moet worden overgeslagen tijdens het pageren?
`CountBasedPaging`	Ondersteunt het API-antwoord een parameter voor het aantal objecten dat moet worden geretourneerd?

LinkHeader of PersistentLinkHeader configureren

Het meest voorkomende pagingtype is wanneer een gegevensbron-API van de server URL's levert aan de volgende en vorige pagina's met gegevens. Zie voor meer informatie over de koppelingskopspecificatieRFC 5988.

LinkHeader paging betekent dat het API-antwoord een van de volgende opties bevat:

De Link HTTP-antwoordheader.
Een JSON-pad om de koppeling op te halen uit de hoofdtekst van het antwoord.

PersistentLinkHeader-type paging heeft dezelfde eigenschappen als LinkHeader, behalve dat de koppelingskop behouden blijft in de back-endopslag. Met deze optie kunt u koppelingen tussen queryvensters pagijnen.

Sommige API's bieden bijvoorbeeld geen ondersteuning voor begin- of eindtijden van query's. In plaats daarvan ondersteunen ze een cursor aan de serverzijde. U kunt permanente paginatypen gebruiken om de cursor aan de serverzijde te onthouden. Zie Wat is een cursor? voor meer informatie.

Opmerking

Er kan slechts één query voor de connector worden uitgevoerd om PersistentLinkHeader raceomstandigheden op de cursor aan de serverzijde te voorkomen. Dit probleem kan van invloed zijn op de latentie.

Veld	Vereist	Type	Beschrijving
`LinkHeaderTokenJsonPath`	False	Tekenreeks	Gebruik deze eigenschap om aan te geven waar de waarde in de hoofdtekst van het antwoord moet worden opgehaald. Als de gegevensbron bijvoorbeeld de volgende JSON retourneert: `{ nextPage: "foo", value: [{data}]}`, is `$.nextPage`de `LinkHeaderTokenJsonPath` waarde .
`PageSize`	False	Geheel getal	Gebruik deze eigenschap om het aantal gebeurtenissen per pagina te bepalen.
`PageSizeParameterName`	False	Tekenreeks	Gebruik deze naam van de queryparameter om de paginagrootte aan te geven.
`PagingInfoPlacement`	False	Tekenreeks	Gebruik deze eigenschap om te bepalen hoe paging-informatie wordt ingevuld. Accepteert of `QueryStringRequestBody`.
`PagingQueryParamOnly`	False	Booleaanse waarde	Gebruik deze eigenschap om queryparameters op te geven. Als deze optie is ingesteld op true, worden alle andere queryparameters, behalve wisselqueryparameters, weggelaten.

Dit zijn enkele voorbeelden:

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

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

NextPageUrl configureren

NextPageUrl-type paging betekent dat het API-antwoord een complexe koppeling bevat in de antwoordtekst, vergelijkbaar met LinkHeader, maar de URL wordt opgenomen in de antwoordtekst in plaats van de header.

Veld	Vereist	Type	Beschrijving
`PageSize`	False	Geheel getal	Het aantal gebeurtenissen per pagina.
`PageSizeParameterName`	False	Tekenreeks	De naam van de queryparameter voor het paginaformaat.
`NextPageUrl`	False	Tekenreeks	Veld dat alleen wordt gebruikt als de connector voor de Coralogix-API is.
`NextPageUrlQueryParameters`	False	Object	Sleutel-waardeparen die een aangepaste queryparameter toevoegen aan elke aanvraag voor de volgende pagina.
`NextPageParaName`	False	Tekenreeks	De naam van de volgende pagina in de aanvraag.
`HasNextFlagJsonPath`	False	Tekenreeks	Het pad naar het `HasNextPage` kenmerk vlag.
`NextPageRequestHeader`	False	Tekenreeks	De naam van de volgende paginakoptekst in de aanvraag.
`NextPageUrlQueryParametersTemplate`	False	Tekenreeks	Veld dat alleen wordt gebruikt als de connector voor de Coralogix-API is.
`PagingInfoPlacement`	False	Tekenreeks	Veld dat bepaalt hoe paging-informatie wordt ingevuld. Accepteert of `QueryStringRequestBody`.
`PagingQueryParamOnly`	False	Booleaanse waarde	Veld waarmee queryparameters worden bepaald. Als deze optie is ingesteld op true, worden alle andere queryparameters, behalve wisselqueryparameters, weggelaten.

Voorbeeld:

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

NextPageToken of PersistentToken configureren

NextPageToken-type paginering maakt gebruik van een token (een hash of een cursor) die de status van de huidige pagina aangeeft. Het token is opgenomen in het API-antwoord en de client voegt het toe aan de volgende aanvraag om de volgende pagina op te halen. Deze methode wordt vaak gebruikt wanneer de server de exacte status tussen aanvragen moet behouden.

PersistentToken paginering maakt gebruik van een token dat de serverzijde blijft behouden. De server onthoudt het laatste token dat de client heeft opgehaald en geeft het volgende token op in volgende aanvragen. De client gaat verder waar hij gebleven was, zelfs als er later nieuwe aanvragen worden ingediend.

Veld	Vereist	Type	Beschrijving
`PageSize`	False	Geheel getal	Aantal gebeurtenissen per pagina.
`PageSizeParameterName`	False	Tekenreeks	Queryparameternaam voor het paginaformaat.
`NextPageTokenJsonPath`	False	Tekenreeks	JSON-pad voor het token van de volgende pagina in de antwoordtekst.
`NextPageTokenResponseHeader`	False	Tekenreeks	Veld dat aangeeft dat als `NextPageTokenJsonPath` leeg is, het token in deze koptekstnaam voor de volgende pagina gebruikt.
`NextPageParaName`	False	Tekenreeks	Veld dat de naam van de volgende pagina in de aanvraag bepaalt.
`HasNextFlagJsonPath`	False	Tekenreeks	Veld dat het pad naar een `HasNextPage` markeringskenmerk definieert bij het bepalen of er meer pagina's in het antwoord worden overgelaten.
`NextPageRequestHeader`	False	Tekenreeks	Veld dat de naam van de volgende paginakoptekst in de aanvraag bepaalt.
`PagingInfoPlacement`	False	Tekenreeks	Veld dat bepaalt hoe paging-informatie wordt ingevuld. Accepteert of `QueryStringRequestBody`.
`PagingQueryParamOnly`	False	Booleaanse waarde	Veld waarmee queryparameters worden bepaald. Als deze optie is ingesteld op true, worden alle andere queryparameters, behalve wisselqueryparameters, weggelaten.

Voorbeelden:

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

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

Offset configureren

Offset-type paginering geeft het aantal pagina's aan dat moet worden overgeslagen en een limiet voor het aantal gebeurtenissen dat per pagina in de aanvraag moet worden opgehaald. Clients halen een specifiek bereik met items op uit de gegevensset.

Veld	Vereist	Type	Beschrijving
`PageSize`	False	Geheel getal	Aantal gebeurtenissen per pagina.
`PageSizeParameterName`	False	Tekenreeks	Queryparameternaam voor het paginaformaat.
`OffsetParaName`	False	Tekenreeks	De naam van de volgende aanvraagqueryparameter. De CCF berekent de offsetwaarde voor elke aanvraag (alle opgenomen gebeurtenissen + 1).
`PagingInfoPlacement`	False	Tekenreeks	Veld dat bepaalt hoe paging-informatie wordt ingevuld. Accepteert of `QueryStringRequestBody`.
`PagingQueryParamOnly`	False	Booleaanse waarde	Veld waarmee queryparameters worden bepaald. Als deze optie is ingesteld op true, worden alle andere queryparameters, behalve wisselqueryparameters, weggelaten.

Voorbeeld:

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

CountBasedPaging configureren

CountBasedPaging-type paginering stelt de client in staat om het aantal items op te geven dat in het antwoord moet worden geretourneerd. Deze mogelijkheid is handig voor API's die paginering ondersteunen op basis van een count-parameter als onderdeel van de nettolading van het antwoord.

Veld	Vereist	Type	Beschrijving
`pageNumberParaName`	Waar	Tekenreeks	Parameternaam van het paginanummer in de HTTP-aanvraag.
`PageSize`	False	Geheel getal	Aantal gebeurtenissen per pagina.
`ZeroBasedIndexing`	False	Booleaanse waarde	Vlag die aangeeft dat het aantal is gebaseerd op nul.
`HasNextFlagJsonPath`	False	Tekenreeks	Het JSON-pad van de vlag in de nettolading van het HTTP-antwoord dat aangeeft dat er meer pagina's zijn.
`TotalResultsJsonPath`	False	Tekenreeks	Het JSON-pad van het totale aantal resultaten in de nettolading van het HTTP-antwoord.
`PageNumberJsonPath`	False	Tekenreeks	Het JSON-pad van het paginanummer in de nettolading van het HTTP-antwoord. Vereist indien `totalResultsJsonPath` opgegeven.
`PageCountJsonPath`	False	Tekenreeks	Het JSON-pad van het aantal pagina's in de nettolading van het HTTP-antwoord. Vereist indien `totalResultsJsonPath` opgegeven.
`PagingInfoPlacement`	False	Tekenreeks	Veld dat bepaalt hoe paging-informatie wordt ingevuld. Accepteert of `QueryStringRequestBody`.
`PagingQueryParamOnly`	False	Booleaanse waarde	Veld waarmee queryparameters worden bepaald. Als deze optie is ingesteld op true, worden alle andere queryparameters, behalve wisselqueryparameters, weggelaten.

Voorbeeld:

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

DCR-configuratie

Veld	Vereist	Type	Beschrijving
`DataCollectionEndpoint`	Waar	Tekenreeks	Eindpunt voor gegevensverzameling (DCE). Bijvoorbeeld: `https://example.ingest.monitor.azure.com`.
`DataCollectionRuleImmutableId`	Waar	Tekenreeks	De onveranderbare DCR-id. U kunt deze vinden door het DCR-antwoord voor maken te bekijken of door de DCR-API te gebruiken.
`StreamName`	Waar	Tekenreeks	Deze waarde is de `streamDeclaration` gedefinieerd in de DCR. Het voorvoegsel moet beginnen met `Custom-`.

Voorbeeld van CCF-gegevensconnector

Hier volgt een voorbeeld van alle onderdelen van de JSON van de CCF-gegevensconnector:

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

Feedback

Is deze pagina nuttig?

Last updated on 2026-04-23

RestApiPoller-gegevensconnector voor het Codeless Connector Framework

Gegevensconnectors maken of bijwerken

URI-parameters

Aanvraagtekst

RestApiPoller

Verificatieconfiguratie

Basisverificatie

API-sleutel

OAuth2

JWT

Basisvoorbeeld

Referenties in POST-hoofdtekst (standaard)

Referenties in headers (basisverificatie)

Referenties in headers (gebruikerstoken)

Aanvraagconfiguratie

Voorbeeld van StartTimeAttributeName

Voorbeeld van QueryTimeIntervalAttributeName

Voorbeeld van RateLimitConfig

Voorbeelden aanvragen die Microsoft Graph gebruiken als de gegevensbron-API

Antwoordconfiguratie

Voorbeelden van antwoordconfiguratie

Pagingconfiguratie

LinkHeader of PersistentLinkHeader configureren

NextPageUrl configureren

NextPageToken of PersistentToken configureren

Offset configureren

CountBasedPaging configureren

DCR-configuratie

Voorbeeld van CCF-gegevensconnector

Feedback

Aanvullende resources