RestApiPoller-datakoblingsreferanse for Codeless Connector Framework

Du kan opprette en RestApiPoller datakobling med Codeless Connector Framework (CCF) ved hjelp av denne artikkelen som et tillegg til Microsoft Sentinel REST-API for datakoblingsdokumenter.

Hver datakobling representerer en bestemt tilkobling til en Microsoft Sentinel datakobling. Én datakobling kan ha flere tilkoblinger, som henter data fra forskjellige endepunkter. Du kan fullføre distribusjonsmalen for CCF-datakoblingen ved hjelp av JSON-konfigurasjonen du bygger med denne artikkelen.

Hvis du vil ha mer informasjon, kan du se Opprette en kodeløs kobling for Microsoft Sentinel.

Opprette eller oppdatere datakoblinger

Finn den nyeste API-versjonen for stabil eller forhåndsversjon ved å create referere til eller update operasjoner i REST-API-dokumentene. Forskjellen mellom create og update operasjonene er at update det etag krever verdien.

PUT Metoden:

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

URI-parametere

Hvis du vil ha mer informasjon om den nyeste API-versjonen, kan du se Datakoblinger: opprette eller oppdatere URI-parametere.

Forespørselstekst

Forespørselsteksten for en RestApiPoller CCF-datakobling har følgende struktur:

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

RestApiPoller

RestApiPoller er en KOPIF-datakobling for API-poller som du kan bruke til å tilpasse nyttelaster for sideveksling, autorisasjon og forespørsel/svar for datakilden.

Godkjenningskonfigurasjon

CCF støtter følgende godkjenningstyper:

• Basic
• API-nøkkel
• OAuth2
• JWT

Som en anbefalt fremgangsmåte kan du bruke parametere i godkjenningsdelen i stedet for hardkodingslegitimasjon. Hvis du vil ha mer informasjon, kan du se Sikre konfidensielle inndata.

Hvis du vil opprette distribusjonsmalen, som også bruker parametere, må du fjerne parameterne i denne inndelingen med en ekstra start [. Dette trinnet gjør det mulig for parameterne å tilordne en verdi basert på brukersamhandlingen med koblingen. Hvis du vil ha mer informasjon, kan du se Escape-tegn for maluttrykk.

Hvis du vil at legitimasjonen skal angis fra brukergrensesnittet, krever inndelingen connectorUIConfig at du angir de ønskede parameterne i instructions. Hvis du vil ha mer informasjon, kan du se definisjonsreferansen for Data connector for Codeless Connector Framework.

Enkel godkjenning

Her er et eksempel på enkel godkjenning som bruker parametere definert i connectorUIconfig:

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

API-nøkkel

APIKey eksempler på godkjenning:

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

Resultatet av dette eksemplet er hemmeligheten som er definert fra brukerinndataene som sendes i følgende topptekst: X-MyApp-Auth-Header: Bearer apikey.

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

Dette eksemplet bruker standardverdiene og resultatene i følgende topptekst: Authorization: token 123123123.

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

Fordi ApiKeyName det er angitt eksplisitt til "", er resultatet følgende topptekst: Authorization: 123123123.

OAuth2

Codeless Connector Framework støtter OAuth 2.0 godkjenningskodetilskudd og klientlegitimasjon. Godkjenningskodetildelingstypen brukes av konfidensielle og offentlige klienter til å utveksle en godkjenningskode for et tilgangstoken.

Når brukeren returnerer til klienten via nettadressen for omadressering, får programmet godkjenningskoden fra nettadressen og bruker den til å be om et tilgangstoken.

Du kan bruke godkjenningskodeflyt til å hente data på vegne av en brukers tillatelser. Du kan bruke klientlegitimasjon til å hente data med programtillatelser. Dataserveren gir tilgang til programmet. Fordi det ikke finnes noen bruker i klientlegitimasjonsflyten, er det ikke nødvendig med godkjenningsendepunkt, bare et tokenendepunkt.

Her er et eksempel på OAuth2-tildelingstypen 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"
}

Her er et eksempel på OAuth2-tildelingstypen 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 -godkjenning (JWT) støtter henting av tokener via brukernavn og passordlegitimasjon og bruk av dem for API-forespørsler.

Grunnleggende eksempel

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

Legitimasjon i POST-brødtekst (standard)

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

Legitimasjon i topptekster (enkel godkjenning)

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

Legitimasjon i overskrifter (brukertoken)

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

Følg denne godkjenningsflyten:

1. Send legitimasjon til for å TokenEndpoint hente JWT-token, når du bruker userName og password, IsCredentialsInHeaders brukes til å bestemme hvor legitimasjonen skal plasseres i forespørselen.

   • Hvis IsCredentialsInHeaders: true: Sender et grunnleggende godkjenningshode med username:password.
   • Hvis IsCredentialsInHeaders: false: Sender legitimasjon i en POST brødtekst.

2. Trekk ut tokenet ved hjelp JwtTokenJsonPath av eller fra svarhodet.

3. Autorisasjonshodet for JWT-tokener er en konstant og vil alltid være «Autorisasjon».

Be om konfigurasjon

Forespørselsdelen definerer hvordan CCF-datakoblingen sender forespørsler til datakilden (for eksempel API-endepunktet og hvor ofte det skal avspørre dette endepunktet).

Når API-en krever komplekse parametere, kan du bruke queryParameters eller queryParametersTemplate. Disse kommandoene inkluderer noen innebygde variabler.

StartTimeAttributeName-eksempel

Vurder dette eksemplet:

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

Spørringen som sendes til den eksterne serveren, er: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Eksempel på QueryTimeIntervalAttributeName

Vurder dette eksemplet:

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

Spørringen som sendes til den eksterne serveren, er: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Eksempel på RateLimitConfig

Vurder dette eksemplet:

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

Når svaret inkluderer topptekster for satsgrenser, kan koblingen bruke denne informasjonen til å justere forespørselsfrekvensen.

Forespørselseksempler som bruker Microsoft Graph som datakilde-API

Dette eksemplet spør meldinger med en filterspørringsparameter. Hvis du vil ha mer informasjon, kan du se spørringsparametere for Microsoft Graph API.

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

Det forrige eksemplet sender en GET forespørsel til https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Tidsangivelsen oppdateres for hver queryWindowInMin gang.

Du oppnår de samme resultatene med dette eksemplet:

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

Det finnes et annet alternativ for situasjoner der datakilden forventer to spørringsparametere (én for starttidspunkt og én for sluttidspunkt).

Eksempel:

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

Dette alternativet sender en GET forespørsel til https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Bruk for komplekse spørringer QueryParametersTemplate. Dette eksemplet sender en POST forespørsel med parametere i brødteksten:

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

Svarkonfigurasjon

Definer hvordan datakoblingen håndterer svar ved hjelp av følgende parametere:

Eksempler på svarkonfigurasjon

Det forventes et serversvar i JSON-format. Svaret har de forespurte dataene i egenskapsverdien. Statusen for svaregenskapen angir at dataene bare skal tas inn hvis verdien er success.

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

Det forventede svaret i dette eksemplet forbereder en CSV uten topptekst.

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

Sidevekslingskonfigurasjon

Når datakilden ikke kan sende hele nyttelasten for svar samtidig, må CCF-datakoblingen vite hvordan du mottar deler av dataene på svarsider. Sidevekslingstypene du kan velge mellom, er:

Konfigurer LinkHeader eller PersistentLinkHeader

Den vanligste sidevekslingstypen er når en serverdatakilde-API gir nettadresser til neste og tidligere sider med data. Hvis du vil ha mer informasjon om spesifikasjonen For koblingshode , kan du se RFC 5988.

LinkHeader sideveksling betyr at API-svaret inkluderer enten:

• Link HTTP-svarhodet.
• En JSON-bane for å hente koblingen fra svarteksten.

PersistentLinkHeader-type sideveksling har de samme egenskapene som LinkHeader, bortsett fra at koblingshodet vedvarer i baklageret. Dette alternativet aktiverer sidevekslingskoblinger på tvers av spørringsvinduer.

Noen API-er støtter for eksempel ikke starttidspunkter eller sluttidspunkt for spørringer. I stedet støtter de en markør på serversiden. Du kan bruke faste sidetyper til å huske markøren på serversiden. Hvis du vil ha mer informasjon, kan du se Hva er en markør?.

Her er noen eksempler:

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

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

Konfigurer NextPageUrl

NextPageUrl-type sideveksling betyr at API-svaret inneholder en kompleks kobling i svarteksten som ligner LinkHeaderpå , men nettadressen er inkludert i svarteksten i stedet for toppteksten.

Eksempel:

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

Konfigurer NextPageToken eller PersistentToken

NextPageToken-type paginering bruker et token (en hash eller en markør) som representerer tilstanden til gjeldende side. Tokenet er inkludert i API-svaret, og klienten tilføyer det til neste forespørsel om å hente neste side. Denne metoden brukes ofte når serveren må opprettholde den nøyaktige tilstanden mellom forespørsler.

PersistentToken Paginering bruker et token som vedvarer serversiden. Serveren husker det siste tokenet klienten hentet, og angir neste token i etterfølgende forespørsler. Klienten fortsetter der den slapp, selv om den foretar nye forespørsler senere.

Eksempler:

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

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

Konfigurer forskyvning

Offset-type paginering angir antall sider som skal hoppes over, og en grense for antall hendelser som skal hentes per side i forespørselen. Klienter henter et bestemt elementområde fra datasettet.

Eksempel:

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

Konfigurer CountBasedPaging

CountBasedPaging-type paginering gjør at klienten kan angi antall elementer som skal returneres i svaret. Denne muligheten er nyttig for API-er som støtter paginering basert på en tellingsparameter som en del av nyttelasten for svar.

Eksempel:

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

DCR-konfigurasjon

Eksempel på CCF-datakobling

Her er et eksempel på alle komponentene i CCF-datakoblingen 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": ["$"]
      }
   }
}