RestApiPoller-dataconnectorreference til Codeless Connector Framework

Du kan oprette en RestApiPoller dataconnector med CCF (Codeless Connector Framework) ved hjælp af denne artikel som et supplement til dokumentation til Microsoft Sentinel REST API til dataconnectors.

Hver dataconnector repræsenterer en bestemt forbindelse for en Microsoft Sentinel dataconnector. En dataconnector kan have flere forbindelser, som henter data fra forskellige slutpunkter. Du kan fuldføre installationsskabelonen for CCF-dataconnectoren ved hjælp af den JSON-konfiguration, du bygger med denne artikel.

Du kan få flere oplysninger under Opret en kodeløs connector til Microsoft Sentinel.

Oprettelse eller opdatering af dataconnectors

Find den nyeste stabile API-version eller prøveversion ved at referere til handlingernecreate eller update i REST API-dokumentationen. Forskellen mellem handlingerne create og update er, at kræver update værdien etag .

PUT Metode:

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

URI-parametre

Du kan få flere oplysninger om den nyeste API-version under Dataconnectors: opret eller opdater URI-parametre.

Brødtekst i anmodning

Anmodningens brødtekst for en RestApiPoller CCF-dataconnector har følgende struktur:

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

RestApiPoller

RestApiPoller er en CCF-API-poller-dataconnector, som du kan bruge til at tilpasse nyttedata for sideinddeling, godkendelse og anmodning/svar for datakilden.

Godkendelseskonfiguration

CCF understøtter følgende godkendelsestyper:

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

Som bedste praksis kan du bruge parametre i godkendelsessektionen i stedet for hard-coding-legitimationsoplysninger. Du kan få flere oplysninger under Sikker fortroligt input.

Hvis du vil oprette installationsskabelonen, som også bruger parametre, skal du undslippe parametrene i dette afsnit med en ekstra start [. Dette trin giver parametrene mulighed for at tildele en værdi baseret på brugerens interaktion med connectoren. Du kan få flere oplysninger under Escape-tegn for skabelonudtryk.

Hvis du vil aktivere de legitimationsoplysninger, der skal angives fra brugergrænsefladen, kræver sektionen, connectorUIConfig at du angiver de ønskede parametre i instructions. Du kan få flere oplysninger under Definitioner af dataconnectorer i Codeless Connector Framework.

Basisgodkendelse

Her er et eksempel på basisgodkendelse, der bruger parametre, der er defineret i connectorUIconfig:

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

API-nøgle

APIKey eksempler på godkendelse:

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

Resultatet af dette eksempel er den hemmelighed, der er defineret ud fra det brugerinput, der sendes i følgende header: X-MyApp-Auth-Header: Bearer apikey.

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

I dette eksempel bruges standardværdierne og resultaterne i følgende overskrift: Authorization: token 123123123.

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

Da ApiKeyName eksplicit er angivet til "", er resultatet følgende header: Authorization: 123123123.

OAuth2

Codeless Connector Framework understøtter tildeling af OAuth 2.0-godkendelseskode og klientlegitimationsoplysninger. Tildelingstypen Godkendelseskode bruges af fortrolige og offentlige klienter til at udveksle en godkendelseskode for et adgangstoken.

Når brugeren vender tilbage til klienten via URL-adressen til omdirigering, henter programmet godkendelseskoden fra URL-adressen og bruger den til at anmode om et adgangstoken.

Du kan bruge et godkendelseskodeflow til at hente data på vegne af en brugers tilladelser. Du kan bruge klientlegitimationsoplysninger til at hente data med programtilladelser. Dataserveren giver adgang til programmet. Da der ikke er nogen bruger i flowet for klientlegitimationsoplysninger, er der ikke behov for et godkendelsesslutpunkt, men kun et tokenslutpunkt.

Her er et eksempel på tildelingstypen OAuth2 authorization_code :

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

Her er et eksempel på tildelingstypen OAuth2 client_credentials :

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

JWT

JSON Web Token-godkendelse (JWT) understøtter hentning af tokens via legitimationsoplysningerne for brugernavn og adgangskode og bruger dem til API-anmodninger.

Grundlæggende 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"
}

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

Legitimationsoplysninger i headere (basisgodkendelse)

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

Legitimationsoplysninger i headere (brugertoken)

"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 dette godkendelsesforløb:

1. Send legitimationsoplysninger for at TokenEndpoint hente JWT-tokenet, når du bruger userName og password, bruges til at bestemme, IsCredentialsInHeaders hvor legitimationsoplysningerne skal placeres i anmodningen.

   • Hvis IsCredentialsInHeaders: true: Sender en grundlæggende godkendelsesheader med username:password.
   • If IsCredentialsInHeaders: false: Sender legitimationsoplysninger i en POST brødtekst.

2. Udtræk tokenet ved hjælp JwtTokenJsonPath af eller fra svarheaderen.

3. Autorisationsheaderen for JWT-tokens er en konstant og vil altid være "Autorisation".

Anmodningskonfiguration

Anmodningsafsnittet definerer, hvordan CCF-dataconnectoren sender anmodninger til din datakilde (f.eks. API-slutpunktet, og hvor ofte det pågældende slutpunkt skal forespørge).

Når API'en kræver komplekse parametre, skal du bruge queryParameters eller queryParametersTemplate. Disse kommandoer omfatter nogle indbyggede variabler.

Eksempel på StartTimeAttributeName

Overvej dette eksempel:

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

Forespørgslen, der sendes til fjernserveren, er: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Eksempel på QueryTimeIntervalAttributeName

Overvej dette eksempel:

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

Forespørgslen, der sendes til fjernserveren, er: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Eksempel på RateLimitConfig

Overvej dette eksempel:

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 indeholder overskrifter med hastighedsgrænser, kan connectoren bruge disse oplysninger til at justere anmodningshastigheden.

Anmod om eksempler, der bruger Microsoft Graph som datakilde-API

Dette eksempel forespørger meddelelser med en filterforespørgselsparameter. Du kan få flere oplysninger under Forespørgselsparametre 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 "
}

I det forrige eksempel sendes en GET anmodning til https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Tidsstemplet opdateres for hver queryWindowInMin gang.

Du opnår de samme resultater med dette eksempel:

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

Der er en anden mulighed for situationer, hvor datakilden forventer to forespørgselsparametre (én for starttidspunktet og én for sluttidspunktet).

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

Denne indstilling sender en GET anmodning til https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

I forbindelse med komplekse forespørgsler skal du bruge QueryParametersTemplate. I dette eksempel sendes en POST anmodning med parametre 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}))\"}"
}

Svarkonfiguration

Definer, hvordan din dataconnector håndterer svar ved hjælp af følgende parametre:

Eksempler på svarkonfiguration

Der forventes et serversvar i JSON-format. Svaret indeholder de ønskede data i egenskabsværdien. Svaregenskabens status angiver kun, at dataene skal indtages, hvis værdien er success.

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

Det forventede svar i dette eksempel forbereder en CSV-fil uden header.

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

Konfiguration af sideopdeling

Når datakilden ikke kan sende hele svarets nyttedata på én gang, skal CCF-dataconnectoren vide, hvordan dele af dataene modtages på svarsider. De sideinddelingstyper, du kan vælge imellem, er:

Konfigurer LinkHeader eller PersistentLinkHeader

Den mest almindelige sideinddelingstype er, når en API til en serverdatakilde leverer URL-adresser til de næste og forrige sider med data. Du kan få flere oplysninger om specifikationen for linkheader under RFC 5988.

LinkHeader sideopdeling betyder, at API-svaret omfatter enten:

• Link HTTP-svarheaderen.
• En JSON-sti til at hente linket fra svarets brødtekst.

PersistentLinkHeader-type-sideinddeling har de samme egenskaber som LinkHeader, bortset fra at linkheaderen bevares i back end-lageret. Denne indstilling aktiverer sideinddelingslinks på tværs af forespørgselsvinduer.

Nogle API'er understøtter f.eks. ikke start- eller sluttidspunkter for forespørgsler. De understøtter i stedet en markør på serversiden. Du kan bruge faste sidetyper til at huske markøren på serversiden. Du kan få flere oplysninger under Hvad er en markør?.

Her er nogle eksempler:

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

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

Konfigurer NextPageUrl

NextPageUrl-type sideinddeling betyder, at API-svaret indeholder et komplekst link i svarteksten, der ligner LinkHeader, men URL-adressen er inkluderet i svarets brødtekst i stedet for headeren.

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 sideinddeling bruger et token (en hash eller en markør), der repræsenterer tilstanden for den aktuelle side. Tokenet er inkluderet i API-svaret, og klienten føjer det til den næste anmodning for at hente den næste side. Denne metode bruges ofte, når serveren skal bevare den nøjagtige tilstand mellem anmodninger.

PersistentToken sideinddeling bruger et token, der bevares på serversiden. Serveren husker det sidste token, som klienten hentede, og angiver det næste token i efterfølgende anmodninger. Klienten fortsætter, hvor den slap, også selvom den foretager nye anmodninger senere.

Eksempler:

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

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

Konfigurer forskydning

Offset-type sideinddeling angiver det antal sider, der skal springes over, og en grænse for det antal hændelser, der skal hentes pr. side i anmodningen. Klienter henter et bestemt interval af elementer fra datasættet.

Eksempel:

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

Konfigurer CountBasedPaging

CountBasedPaging-type-sideinddeling gør det muligt for klienten at angive det antal elementer, der skal returneres i svaret. Denne mulighed er nyttig for API'er, der understøtter sideinddeling baseret på en optællingsparameter som en del af svarnyttedata.

Eksempel:

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

DCR-konfiguration

Eksempel på CCF-dataconnector

Her er et eksempel på alle komponenterne i JSON til CCF-dataconnectoren:

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