Naslaginformatie over restApiPoller-gegevensconnector voor het Codeless Connector Framework

Als u een RestApiPoller gegevensconnector wilt maken met het Codeless Connector Framework (CCF), gebruikt u deze verwijzing als aanvulling op de Documentatie voor Microsoft Sentinel REST API voor gegevensconnectors .

Elk dataConnector vertegenwoordigt een specifieke verbinding van een Microsoft Sentinel-gegevensconnector. Eén gegevensconnector kan meerdere verbindingen hebben, waardoor gegevens van verschillende eindpunten worden opgehaald. De JSON-configuratie die met dit referentiedocument is gebouwd, wordt gebruikt om de implementatiesjabloon voor de CCF-gegevensconnector te voltooien.

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

Gegevensconnectors - Maken of bijwerken

Raadpleeg de bewerking Maken of Bijwerken in de REST API-documenten om de nieuwste stabiele of preview-API-versie te vinden. Het verschil tussen het maken en de updatebewerking is dat voor de 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 id van de gegevensconnector moet een unieke naam zijn en is hetzelfde 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. Regex-patroon: `^[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 aanvraagbody voor een RestApiPoller CCF-gegevensconnector heeft de volgende structuur:

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

RestApiPoller

RestApiPoller vertegenwoordigt een API Poller CCF-gegevensconnector waar u paging-, autorisatie- en aanvraag-/antwoordpayloads voor uw gegevensbron aanpast.

Naam	Vereist	Typologie	Beschrijving
naam	Waar	tekenreeks	De unieke naam van de verbinding die overeenkomt met de URI-parameter
soort	Waar	tekenreeks	Moet `RestApiPoller` zijn
etag		GUID (Globaal Unieke Identificatiecode)	Laat leeg voor het maken van nieuwe connectors. Voor updatebewerkingen moet de etag overeenkomen met de etag (GUID) van de bestaande connector.
properties.connectorDefinitionName		tekenreeks	De naam van de DataConnectorDefinition-resource die de ui-configuratie van de gegevensconnector definieert. Zie Definitie van gegevensconnector voor meer informatie.
Eigenschappen.Auth	Waar	Geneste JSON	Beschrijft de verificatie-eigenschappen voor het peilen van de gegevens. Zie de verificatieconfiguratie voor meer informatie.
Eigenschappen.verzoek	Waar	Geneste JSON	Beschrijft de nettolading van de aanvraag voor het peilen van de gegevens, zoals het API-eindpunt. Zie de aanvraagconfiguratie voor meer informatie.
Eigenschappen.antwoord	Waar	Geneste JSON	Beschrijft het antwoordobject en geneste bericht dat wordt geretourneerd door de API bij het peilen van de gegevens. Zie de antwoordconfiguratie voor meer informatie.
Eigenschappen.Paging		Geneste JSON	Beschrijft de nettolading van paginering bij het peilen van de gegevens. Zie de pagingconfiguratie voor meer informatie.
Eigenschappen.dcrConfig		Geneste JSON	Vereiste parameters wanneer de gegevens worden verzonden naar een DCR (Data Collection Rule). Zie DCR-configuratie voor meer informatie.

Verificatieconfiguratie

De CCF ondersteunt de volgende verificatietypen:

Basisch
APIKey
OAuth2
JWT

Notitie

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

Als best practice gebruikt u parameters in de sectie verificatie in plaats van hardcoderingsreferenties. Zie Vertrouwelijke invoer beveiligen voor meer informatie.

Als u de implementatiesjabloon wilt maken die ook parameters gebruikt, moet u de parameters in deze sectie escapen met een extra begin [. Hierdoor kunnen de parameters een waarde toewijzen op basis van de interactie van de gebruiker met de connector. Zie Sjabloonexpressies escape-tekens voor meer informatie.

Als u de referenties wilt inschakelen die moeten worden ingevoerd vanuit de gebruikersinterface, vereist connectorUIConfig de instructions sectie de gewenste parameters. Zie de naslaginformatie over definities van gegevensconnector voor het Codeless Connector Framework voor meer informatie.

Basisverificatie

Veld	Vereist	Typologie
Gebruikersnaam	Waar	tekenreeks
Wachtwoord	Waar	tekenreeks

Voorbeeld van basisverificatie met parameters die zijn gedefinieerd in connectorUIconfig:

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

APIKey

Veld	Vereist	Typologie	Beschrijving	Standaardwaarde
ApiKey	Waar	tekenreeks	gebruikersgeheimsleutel
ApiKeyName		tekenreeks	naam van de URI-header met de ApiKey-waarde	`Authorization`
ApiKeyIdentifier		tekenreeks	tekenreekswaarde om het token vooraf te laten gaan	`token`
IsApiKeyInPostPayload		booleaan	geheim verzenden in POST-hoofdtekst in plaats van koptekst	`false`

Voorbeelden van APIKey-verificatie:

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

Dit voorbeeld resulteert in het geheim dat is gedefinieerd op basis van 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: Autorisatie: token 123123123

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

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

OAuth2

Het Codeless Connector Framework ondersteunt OAuth 2.0-autorisatiecodetoekenningen en clientreferenties. Het toekenningstype Autorisatiecode wordt gebruikt door vertrouwelijke en openbare clients om een autorisatiecode voor een toegangstoken in te wisselen. Nadat de gebruiker via de omleidings-URL naar de client terugkeert, krijgt de toepassing de autorisatiecode van de URL en gebruikt deze om een toegangstoken aan te vragen.

Veld	Vereist	Typologie	Beschrijving
ClientId-	Waar	Snaar / Touwtje	De client-id
ClientSecret	Waar	Snaar / Touwtje	Het clientgeheim
AuthorizationCode	Waar wanneer grantType = `authorization_code`	Snaar / Touwtje	Als het toekenningstype deze veldwaarde is `authorization_code` , wordt de autorisatiecode geretourneerd door de verificatie-service.
Omvang	Waar voor `authorization_code` toekenningstype optioneel voor `client_credentials` toekenningstype	Snaar / Touwtje	Een door spaties gescheiden lijst met bereiken voor toestemming van de gebruiker. Zie OAuth2-bereiken en -machtigingen voor meer informatie.
RedirectUri	Waar wanneer grantType = `authorization_code`	Snaar / Touwtje	URL voor omleiding moet zijn `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	Waar	Snaar / Touwtje	`authorization_code` of `client_credentials`
TokenEndpoint	Waar	Snaar / Touwtje	URL voor het uitwisselen van code met een geldig token in `authorization_code` grant of client-id en geheim met geldig token in `client_credentials` grant.
TokenEndpointHeaders		Voorwerp	Een optioneel sleutelwaardeobject voor het verzenden van aangepaste headers naar tokenserver
TokenEndpointQueryParameters		Voorwerp	Een optioneel sleutelwaardeobject voor het verzenden van aangepaste queryparameters naar tokenserver
AutorisatieEindpunt	Waar	Snaar / Touwtje	URL voor gebruikerstoestemming voor `authorization_code` stroom
AuthorizationEndpointHeaders		Voorwerp	Een optioneel sleutelwaardeobject voor het verzenden van aangepaste headers naar de verificatieserver
AutorisatieEindpuntQueryParameters		Voorwerp	Een optioneel sleutelwaardepaar dat wordt gebruikt in de OAuth2-autorisatiecodestroomaanvraag

De verificatiecodestroom is bedoeld voor het ophalen van gegevens namens de machtigingen van een gebruiker en clientreferenties is voor het ophalen van gegevens met toepassingsmachtigingen. De gegevensserver verleent toegang tot de toepassing. Omdat er geen gebruiker is in de clientreferentiestroom, is er geen autorisatie-eindpunt nodig, alleen een tokeneindpunt.

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

Voorbeeld: 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 referenties voor gebruikersnaam/wachtwoord 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"
}

Verificatiestroom:

Referenties verzenden om TokenEndpoint JWT-token te verkrijgen
- Als IsCredentialsInHeaders: true: Verzendt de header Basisverificatie met gebruikersnaam:wachtwoord
- Als IsCredentialsInHeaders: false: referenties verzendt in POST-hoofdtekst
Token extraheren met of JwtTokenJsonPath uit antwoordheader
Token gebruiken in volgende API-aanvragen met ApiKeyName header

Eigenschappen:

Veld	Vereist	Typologie	Beschrijving
type	Waar	Snaar / Touwtje	Moet `JwtToken` zijn
gebruikersnaam	Waar (als userToken niet wordt gebruikt)	Voorwerp	Sleutel-waardepaar voor gebruikersnaamreferenties. Als `userName` en `password` worden verzonden in de headeraanvraag, geeft u de `value` eigenschap op met de gebruikersnaam. Als `userName` en `password` verzonden in de hoofdtekstaanvraag, geeft u de `Key` en `Value`
wachtwoord	Waar (als userToken niet wordt gebruikt)	Voorwerp	Sleutel-waardepaar voor wachtwoordreferenties. Als `userName` en `password` worden verzonden in de headeraanvraag, geeft u de `value` eigenschap op met de gebruikersnaam. Als `userName` en `password` verzonden in de hoofdtekstaanvraag, geeft u de `Key` en `Value`
userToken	Waar (als userName niet wordt gebruikt)	Snaar / Touwtje	Gebruikerstoken gegenereerd door de client om het systeemtoken voor verificatie op te halen
UserTokenPrepend	Onwaar	Snaar / Touwtje	Tekst vooraf laten gaan voor het token. Voorbeeld: `Bearer`
NoAccessTokenPrepend	Onwaar	Booleaanse waarde	Toegangsvlag om aan te geven dat token niet mag worden voorbereid
TokenEndpointHttpMethod	Onwaar	Snaar / Touwtje	Tokeneindpunt van de HTTP-methode. Kan of `GetPost`. Standaardwaarde: `Post`
TokenEndpoint	Waar	Snaar / Touwtje	URL-eindpunt voor het verkrijgen van het JWT-token
IsCredentialsInHeaders		Booleaanse waarde	Referenties verzenden als Basic Auth-header (`true`) versus POST-hoofdtekst (`false`). Standaardwaarde: `false`
IsJsonRequest		Booleaanse waarde	Aanvraag verzenden als JSON (header `Content-Type = application/json`) versus form-encoded (header `Content-Type = application/x-www-form-urlencoded`). Standaardwaarde: `false`
JwtTokenJsonPath		Snaar / Touwtje	JSONPath voor het extraheren van het token uit het antwoord (bijvoorbeeld '`$.access_token`')
JwtTokenInResponseHeader		Booleaanse waarde	Token extraheren uit de antwoordheader versus hoofdtekst. Standaardwaarde: `false`
JwtTokenHeaderName		Snaar / Touwtje	Headernaam wanneer het token zich in de antwoordheader bevindt. Standaard: "`Authorization`"
JwtTokenIdentifier		Snaar / Touwtje	Id die wordt gebruikt om de JWT te extraheren uit een tokentekenreeks met voorvoegsel
QueryParameters		Voorwerp	Aangepaste queryparameters die moeten worden opgenomen bij het verzenden van de aanvraag naar het tokeneindpunt
Kopteksten		Voorwerp	Aangepaste headers die moeten worden opgenomen bij het verzenden van de aanvraag naar het tokeneindpunt
RequestTimeoutInSeconds		Geheel getal	Time-out aanvragen in seconden. Standaard: `100`, Max `180`

Verificatiestroom:

Referenties verzenden om TokenEndpoint JWT-token te verkrijgen
- Als IsCredentialsInHeaders: true: Verzendt de header Basisverificatie met gebruikersnaam:wachtwoord
- Als IsCredentialsInHeaders: false: referenties verzendt in POST-hoofdtekst
Token extraheren met of JwtTokenJsonPath uit antwoordheader
Token gebruiken in volgende API-aanvragen met ApiKeyName header

Notitie

Limitations:

Vereist gebruikersnaam-/wachtwoordverificatie voor het verkrijgen van tokens
Biedt geen ondersteuning voor api-sleuteltokenaanvragen
Aangepaste headerverificatie (zonder gebruikersnaam/wachtwoord) wordt niet ondersteund

Aanvraagconfiguratie

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

Veld	Vereist	Typologie	Beschrijving
ApiEndpoint	Waar	Snaar / Touwtje	URL voor externe server. Hiermee definieert u het eindpunt waaruit gegevens moeten worden opgehaald.
RateLimitQPS		Geheel getal	Hiermee definieert u het aantal aanroepen of query's dat in een seconde is toegestaan.
RateLimitConfig		Voorwerp	Definieert de snelheidslimietconfiguratie voor de RESTful API. Zie voorbeeld.
QueryWindowInMin		Geheel getal	Hiermee definieert u het beschikbare queryvenster in minuten. Minimaal 1 minuut. Standaard is dit 5 minuten.
HttpMethod		Snaar / Touwtje	Definieert de API-methode: `GET`(standaard) of `POST`
QueryTimeFormat		Snaar / Touwtje	Hiermee definieert u de datum- en tijdnotatie die het eindpunt (externe server) verwacht. De CCF gebruikt de huidige datum en tijd waar deze variabele ook wordt gebruikt. Mogelijke waarden zijn de constanten: `UnixTimestamp`of `UnixTimestampInMills` een andere geldige weergave van datum/tijd, bijvoorbeeld: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss` standaard is ISO 8601 UTC
RetryCount		Geheel getal (1...6)	Hiermee definieert u `1` nieuwe `6` pogingen die zijn toegestaan om te herstellen na een fout. Standaard is `3`.
Time-outInSeconds		Geheel getal (1...180)	Hiermee definieert u de time-out van de aanvraag, in seconden. Standaard is `20`
IsPostPayloadJson		Booleaanse waarde	Bepaalt of de POST-nettolading de JSON-indeling heeft. Standaard is `false`
Kopteksten		Voorwerp	Sleutel-waardeparen die de aanvraagheaders definiëren.
QueryParameters		Voorwerp	Sleutel-waardeparen waarmee de queryparameters van de aanvraag worden gedefinieerd.
StartTimeAttributeName	Waar wanneer `EndTimeAttributeName` is ingesteld	Snaar / Touwtje	Hiermee definieert u de naam van de queryparameter voor de begintijd van de query. Zie voorbeeld.
EndTimeAttributeName	Waar wanneer `StartTimeAttributeName` is ingesteld	Snaar / Touwtje	Hiermee definieert u de naam van de queryparameter voor de eindtijd van de query.
QueryTimeIntervalAttributeName		Snaar / Touwtje	Als voor het eindpunt een gespecialiseerde indeling is vereist voor het uitvoeren van query's op de gegevens in een tijdsbestek, gebruikt u deze eigenschap met de `QueryTimeIntervalPrepend` en de `QueryTimeIntervalDelimiter` parameters. Zie voorbeeld.
QueryTimeIntervalPrepend	Waar wanneer `QueryTimeIntervalAttributeName` is ingesteld	Snaar / Touwtje	Zie `QueryTimeIntervalAttributeName`
QueryTimeIntervalDelimiter	Waar wanneer `QueryTimeIntervalAttributeName` is ingesteld	Snaar / Touwtje	Zie `QueryTimeIntervalAttributeName`
QueryParametersTemplate		Snaar / Touwtje	Querysjabloon die moet worden gebruikt bij het doorgeven van parameters in geavanceerde scenario's. br>bijvoorbeeld: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

Wanneer voor de API complexe parameters zijn vereist, gebruikt u de queryParameters of queryParametersTemplate die enkele ingebouwde variabelen bevat.

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

Kijk eens naar 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

Kijk eens naar 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}

RateLimitConfig-voorbeeld

Kijk eens naar 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 de respons rate limit headers bevat, kan de connector deze informatie gebruiken om zijn request rate aan te passen.

Voorbeelden aanvragen met Behulp van Microsoft Graph als gegevensbron-API

In dit voorbeeld worden berichten met een filterqueryparameter opgevraagd. Zie Microsoft Graph API-queryparameters 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 telkens queryWindowInMin bijgewerkt.

Dezelfde resultaten worden bereikt 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}"
  }
}

Een andere optie is wanneer de gegevensbron twee queryparameters verwacht, één voor de begintijd en één voor de 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",
}

Hiermee 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 volgende voorbeeld wordt een POST aanvraag met parameters in de hoofdtekst verzonden.

Voorbeeld:

"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 de reactieafhandeling van uw gegevensconnector met de volgende parameters:

Veld	Vereist	Typologie	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 op in een JSON-structuur
SuccessStatusJsonPath		Snaar / Touwtje	Definieert het pad naar het succesbericht in de antwoord-JSON. Wanneer deze parameter is gedefinieerd, moet ook de `SuccessStatusValue` parameter worden gedefinieerd.
SuccessStatusValue		Snaar / Touwtje	Definieert het pad naar de waarde van het geslaagde bericht in de antwoord-JSON
IsGzipCompressed		Booleaanse waarde	Bepaalt of het antwoord is gecomprimeerd in een gzip-bestand
	Waar	Snaar / Touwtje	`json`of `csvxml`
CompressionAlgo		Snaar / Touwtje	Het algoritme voor compressies, ofwel `multi-gzipdeflate`. Voor gzip-compressie-algoritme hoeft u alleen maar te configureren `IsGzipCompressed` in `True` plaats van een waarde in te stellen voor deze parameter.
CsvDelimiter		Snaar / Touwtje	Als de antwoordindeling CSV is en u het standaard-CSV-scheidingsteken van `","`
HasCsvBoundary		Booleaanse waarde	Aangeven of CSV-gegevens een grens hebben
HasCsvHeader		Booleaanse waarde	Geef aan of CSV-gegevens een koptekst hebben, de standaardwaarde is `True`
CsvEscape		Snaar / Touwtje	Escape-teken voor een veldgrens, standaard is `"` Een CSV met kopteksten `id,name,avg` en een rij met gegevens die spaties bevatten, zoals `1,"my name",5.5` de `"` veldgrens is vereist.
ConvertChildPropertiesToArray		Booleaanse waarde	Speciaal geval waarin de externe server een object retourneert in plaats van een lijst met gebeurtenissen waarin elke eigenschap gegevens bevat.

Notitie

Het type CSV-indeling wordt geparseerd door de RFC4180 specificatie.

Voorbeelden van antwoordconfiguratie

Er wordt een serverantwoord met JSON-indeling verwacht, met de aangevraagde gegevens in de eigenschapswaarde. De status van de antwoordeigenschap geeft aan dat de gegevens alleen moeten worden opgenomen als de waarde issuccess.

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

Configuratie van paging

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

Pagingstype	beslissingsfactor
LinkHeader PersistentLinkHeader NextPageUrl	Bevat het API-antwoord koppelingen naar volgende en vorige pagina's?
NextPageToken PersistentToken	Heeft het API-antwoord een token of cursor voor de volgende en vorige pagina's?
Afstand	Ondersteunt het API-antwoord een parameter voor het aantal objecten dat moet worden overgeslagen bij het wisselen?
CountBasedPaging	Ondersteunt het API-antwoord een parameter voor het aantal objecten dat moet worden geretourneerd?

LinkHeader of PersistentLinkHeader configureren

Het meest voorkomende pagieringstype is wanneer een SERVERgegevensbron-API URL's levert aan de volgende en vorige pagina's met gegevens. Zie RFC 5988 voor meer informatie over de specificatie van de koppelingsheader.

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

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

PersistentLinkHeader paging heeft dezelfde eigenschappen als LinkHeader, behalve de koppelingsheader blijft behouden in back-endopslag. Met deze optie kunt u pagingkoppelingen tussen queryvensters inschakelen. Sommige API's bieden bijvoorbeeld geen ondersteuning voor begin- of eindtijden van query's. In plaats daarvan ondersteunen ze een cursor aan de serverzijde. Permanente paginatypen kunnen worden gebruikt om de cursor aan de serverzijde te onthouden. Zie Wat is een cursor? voor meer informatie.

Notitie

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

Veld	Vereist	Typologie	Beschrijving
LinkHeaderTokenJsonPath	Onwaar	Snaar / Touwtje	Gebruik deze eigenschap om aan te geven waar de waarde moet worden opgehaald in de hoofdtekst van het antwoord. Als de gegevensbron bijvoorbeeld de volgende JSON retourneert, `{ nextPage: "foo", value: [{data}]}` is dat `LinkHeaderTokenJsonPath$.nextPage`
Pagesize	Onwaar	Geheel getal	Hoeveel gebeurtenissen per pagina
PageSizeParameterName	Onwaar	Snaar / Touwtje	Naam van queryparameter voor het paginaformaat
PagingInfoPlacement	Onwaar	Snaar / Touwtje	Hoe paging-informatie wordt ingevuld. Accepteert zowel "QueryString" als "RequestBody"
PagingQueryParamOnly	Onwaar	Booleaanse waarde	Als deze op waar staat, worden alle andere queryparameters behalve pagingqueryparameters weggelaten.

Hieronder volgen een aantal voorbeelden:

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

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

NextPageUrl configureren

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

Veld	Vereist	Typologie	Beschrijving
Pagesize	Onwaar	Geheel getal	Hoeveel gebeurtenissen per pagina
PageSizeParameterName	Onwaar	Snaar / Touwtje	Naam van queryparameter voor het paginaformaat
NextPageUrl	Onwaar	Snaar / Touwtje	Alleen als de connector voor Coralogix-API is
NextPageUrlQueryParameters	Onwaar	Waardeparen van objectsleutels: aangepaste queryparameter toevoegen aan elke aanvraag voor de volgende pagina
NextPageParaName	Onwaar	Snaar / Touwtje	Bepaalt de naam van de volgende pagina in de aanvraag.
HasNextFlagJsonPath	Onwaar	Snaar / Touwtje	Hiermee definieert u het pad naar het vlagkenmerk HasNextPage
NextPageRequestHeader	Onwaar	Snaar / Touwtje	Bepaalt de naam van de volgende paginakoptekst in de aanvraag.
NextPageUrlQueryParametersTemplate	Onwaar	Snaar / Touwtje	Alleen als de connector voor Coralogix-API is
PagingInfoPlacement	Onwaar	Snaar / Touwtje	Hoe paging-informatie wordt ingevuld. Accepteert zowel "QueryString" als "RequestBody"
PagingQueryParamOnly	Onwaar	Booleaanse waarde	Als deze op waar staat, worden alle andere queryparameters behalve pagingqueryparameters 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 paginering maakt gebruik van een token (een hash of een cursor) die de status van de huidige pagina vertegenwoordigt. 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 onderhouden.

PersistentToken paginering maakt gebruik van een token dat de serverzijde persistent maakt. De server onthoudt het laatste token dat door de client is opgehaald en levert het volgende token in volgende aanvragen. De client gaat verder waar het was gebleven, zelfs als er later nieuwe aanvragen worden ingediend.

Veld	Vereist	Typologie	Beschrijving
Pagesize	Onwaar	Geheel getal	Hoeveel gebeurtenissen per pagina
PageSizeParameterName	Onwaar	tekenreeks	Naam van queryparameter voor het paginaformaat
NextPageTokenJsonPath	Onwaar	tekenreeks	JSON-pad voor het volgende paginatoken in de hoofdtekst van het antwoord.
NextPageTokenResponseHeader	Onwaar	tekenreeks	Als `NextPageTokenJsonPath` dit leeg is, gebruikt u het token in deze headernaam voor de volgende pagina.
NextPageParaName	Onwaar	tekenreeks	Bepaalt de naam van de volgende pagina in de aanvraag.
HasNextFlagJsonPath	Onwaar	tekenreeks	Definieert het pad naar een HasNextPage-vlagkenmerk bij het bepalen of er meer pagina's in het antwoord staan.
NextPageRequestHeader	Onwaar	tekenreeks	Bepaalt de naam van de volgende paginakoptekst in de aanvraag.
PagingInfoPlacement	Onwaar	Snaar / Touwtje	Hoe paging-informatie wordt ingevuld. Accepteert zowel "QueryString" als "RequestBody"
PagingQueryParamOnly	Onwaar	Booleaanse waarde	Als deze op waar staat, worden alle andere queryparameters behalve pagingqueryparameters weggelaten.

Voorbeelden:

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

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

Verschuiving configureren

Offset paginering geeft het aantal pagina's op 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 van items op uit de gegevensset.

Veld	Vereist	Typologie	Beschrijving
Pagesize	Onwaar	Geheel getal	Hoeveel gebeurtenissen per pagina
PageSizeParameterName	Onwaar	Snaar / Touwtje	Naam van queryparameter voor het paginaformaat
OffsetParaName	Onwaar	Snaar / Touwtje	De naam van de volgende aanvraagqueryparameter. De CCF berekent de offsetwaarde voor elke aanvraag (alle opgenomen gebeurtenissen + 1)
PagingInfoPlacement	Onwaar	Snaar / Touwtje	Hoe paging-informatie wordt ingevuld. Accepteert zowel "QueryString" als "RequestBody"
PagingQueryParamOnly	Onwaar	Booleaanse waarde	Als deze op waar staat, worden alle andere queryparameters behalve pagingqueryparameters weggelaten.

Voorbeeld:

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

CountBasedPaging configureren

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

Veld	Vereist	Typologie	Beschrijving
pageNumberParaName	Waar	Snaar / Touwtje	Parameternaam van paginanummer in HTTP-aanvraag
Pagesize	Onwaar	Geheel getal	Hoeveel gebeurtenissen per pagina
ZeroBasedIndexing	Onwaar	Booleaanse waarde	Vlag om aan te geven of aantal nul is gebaseerd
HasNextFlagJsonPath	Onwaar	Snaar / Touwtje	JSON-pad van vlag in nettolading http-antwoord om aan te geven dat er meer pagina's zijn
TotalResultsJsonPath	Onwaar	Snaar / Touwtje	JSON-pad van het totale aantal resultaten in nettolading http-antwoord
PageNumberJsonPath	Onwaar	Snaar / Touwtje	Vereist als totalResultsJsonPath is opgegeven. JSON-pad van paginanummer in nettolading http-antwoord
PageCountJsonPath	Onwaar	Snaar / Touwtje	Vereist als totalResultsJsonPath is opgegeven. JSON-pad van het aantal pagina's in nettolading http-antwoord
PagingInfoPlacement	Onwaar	Snaar / Touwtje	Hoe paging-informatie wordt ingevuld. Accepteert zowel "QueryString" als "RequestBody"
PagingQueryParamOnly	Onwaar	Booleaanse waarde	Als deze op waar staat, worden alle andere queryparameters behalve pagingqueryparameters weggelaten.

Voorbeeld:

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

DCR-configuratie

Veld	Vereist	Typologie	Beschrijving
DataCollectionEndpoint	Waar	Snaar / Touwtje	DCE (eindpunt voor gegevensverzameling) bijvoorbeeld: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	Waar	Snaar / Touwtje	De onveranderbare DCR-id. Zoek het door het dcr-antwoord te bekijken of de DCR-API te gebruiken
StreamName	Waar	tekenreeks	Deze waarde is de `streamDeclaration` gedefinieerde in de DCR (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 2025-10-31

Delen via

Naslaginformatie over restApiPoller-gegevensconnector voor het Codeless Connector Framework

Gegevensconnectors - Maken of bijwerken

URI-parameters

Aanvraagtekst

RestApiPoller

Verificatieconfiguratie

Basisverificatie

APIKey

OAuth2

JWT

Aanvraagconfiguratie

Voorbeeld van StartTimeAttributeName

Voorbeeld van QueryTimeIntervalAttributeName

RateLimitConfig-voorbeeld

Voorbeelden aanvragen met Behulp van Microsoft Graph als gegevensbron-API

Antwoordconfiguratie

Voorbeelden van antwoordconfiguratie

Configuratie van paging

LinkHeader of PersistentLinkHeader configureren

NextPageUrl configureren

NextPageToken of PersistentToken configureren

Verschuiving configureren

CountBasedPaging configureren

DCR-configuratie

Voorbeeld van CCF-gegevensconnector

Feedback

Aanvullende resources