RestApiPoller-tietoyhdistimen viittaus Codeless Connector Frameworkiin

Voit luoda RestApiPoller tietoliittimen Codeless Connector Frameworkin (CCF) avulla käyttämällä tätä artikkelia tietoyhdistimien Microsoft Sentinel REST -ohjelmointirajapinnan täydennysasiakirjana.

Jokainen tietoyhdistin edustaa tiettyä Microsoft Sentinel -tietoliittimen yhteyttä. Yhdellä tietoyhdistimellä voi olla useita yhteyksiä, jotka noutavat tietoja eri päätepisteistä. Voit viimeistellä CCF-tietoliittimen käyttöönottomallin käyttämällä JSON-määritystä, jonka luot tämän artikkelin avulla.

Lisätietoja on artikkelissa Koodittoman liittimen luominen Microsoft Sentinel varten.

Tietoyhdistimien luominen tai päivittäminen

Etsi uusin vakaa tai esikatselun ohjelmointirajapinnan versio viittaamalla create rest-ohjelmointirajapintadokumentteihin tai update -toimintoihin. - ja update -createtoimintojen välinen ero on se, joka update edellyttää etag -arvoa.

PUT Menetelmä:

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

URI-parametrit

Lisätietoja uusimmasta ohjelmointirajapintaversiosta on kohdassa Tietoliittimet: URI-parametrien luominen tai päivittäminen.

Pyynnön leipäteksti

CCF-tietoliittimen pyynnön leipätekstillä RestApiPoller on seuraava rakenne:

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

RestApiPoller

RestApiPoller on ohjelmointirajapinnan kyselyn CCF-tietoyhdistin, jonka avulla voit mukauttaa sivutusta, valtuutusta ja pyyntöjen/vastausten hyötymääriä tietolähteelle.

Todennusmääritys

CCF tukee seuraavia todennustyyppejä:

• Basic
• Ohjelmointirajapinnan avain
• OAuth2
• JWT

Paras käytäntö on käyttää parametreja todennusosiossa tunnistetietojen kiinteän koodauksen sijaan. Lisätietoja on kohdassa Luottamuksellisen syötteen suojaaminen.

Jos haluat luoda käyttöönottomallin, joka käyttää myös parametreja, sinun on vältettävä tämän osion parametreja ylimääräisellä aloitusohjelmalla [. Tämän vaiheen avulla parametrit voivat määrittää arvon sen perusteella, miten käyttäjä on vuorovaikutuksessa liittimen kanssa. Lisätietoja on artikkelissa Mallilausekkeiden ohjausmerkit.

Jotta tunnistetiedot voidaan antaa käyttöliittymästä, -osio edellyttää, connectorUIConfig että annat halutut parametrit kohteessa instructions. Lisätietoja on ohjeaiheessa Koodittoman liittimen sovelluskehyksen tietoyhdistimen määritysviittaus.

Perustodennusta

Tässä on esimerkki perustodennuksesta, joka käyttää kohteessa connectorUIconfigmääritettyjä parametreja:

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

Ohjelmointirajapinnan avain

APIKey todennusesimerkkejä:

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

Tämän esimerkin tulos on salasana, joka on määritetty seuraavassa otsikossa lähetetystä käyttäjän syötteestä: X-MyApp-Auth-Header: Bearer apikey.

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

Tässä esimerkissä käytetään oletusarvoja ja tuloksena on seuraava otsikko: Authorization: . token 123123123

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

Koska ApiKeyName -arvoksi ""on eksplisiittisesti määritetty , tulos on seuraava otsikko: Authorization: . 123123123

OAuth2

Codeless Connector Framework tukee OAuth 2.0 -valtuutuskoodin myöntämistä ja asiakkaan tunnistetietoja. Luottamukselliset ja julkiset asiakkaat käyttävät valtuutuskoodin myöntämistyyppiä käyttöoikeuskoodin vaihtamiseen käyttöoikeustietuetta varten.

Kun käyttäjä palaa asiakkaaseen uudelleenohjauksen URL-osoitteen kautta, sovellus saa valtuutuskoodin URL-osoitteesta ja pyytää sen avulla käyttöoikeustietuetta.

Todennuskoodin työnkulun avulla voit noutaa tietoja käyttäjän käyttöoikeuksien puolesta. Asiakastunnistetietojen avulla voit noutaa tietoja sovelluksen käyttöoikeuksilla. Tietopalvelin myöntää sovelluksen käyttöoikeuden. Koska asiakkaan tunnistetietojen työnkulussa ei ole käyttäjää, valtuutuksen päätepistettä ei tarvita, vain tunnuksen päätepiste.

Tässä on esimerkki OAuth2-avustustyypistä 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"
}

Tässä on esimerkki OAuth2-avustustyypistä 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 (JWT) -todennus tukee tunnusten hankkimista käyttäjänimen ja salasanan tunnistetiedoilla sekä niiden käyttöä ohjelmointirajapintapyynnöissä.

Perusesimerkki

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

Tunnistetiedot POST-leipätekstissä (oletus)

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

Tunnistetiedot otsikoissa (perustodennus)

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

Tunnistetiedot otsikoissa (käyttäjätunnus)

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

Noudata tätä todennustyönkulkua:

1. Lähetä tunnistetiedot saadaksesi TokenEndpoint JWT-tunnuksen käytettäessä userName ja password, IsCredentialsInHeaders käytetään määrittämään, mihin tunnistetiedot lisätään pyynnössä.

   • If IsCredentialsInHeaders: true: Lähettää perustodennuksen otsikon , jossa on username:password.
   • If IsCredentialsInHeaders: false: Lähettää tunnistetiedot leipätekstissä POST .

2. Poimi tunnus käyttämällä JwtTokenJsonPath vastauksen otsikkoa tai vastauksesta.

3. JWT-tunnusten valtuutusotsikko on vakio, ja se on aina Valtuutus.

Pyynnön määritys

Pyyntö-osiossa määritetään, miten CCF-tietoyhdistin lähettää pyyntöjä tietolähteeseen (esimerkiksi ohjelmointirajapinnan päätepisteeseen ja kuinka usein päätepisteeseen lähetetään kysely).

Kun ohjelmointirajapinta vaatii monimutkaisia parametreja, käytä queryParameters tai queryParametersTemplate. Nämä komennot sisältävät joitakin sisäisiä muuttujia.

Esimerkki StartTimeAttributeName

Katso tätä esimerkkiä:

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

Etäpalvelimeen lähetetty kysely on: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Esimerkki QueryTimeIntervalAttributeName

Katso tätä esimerkkiä:

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

Etäpalvelimeen lähetetty kysely on: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Esimerkki RateLimitConfig-määrityksestä

Katso tätä esimerkkiä:

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

Kun vastaus sisältää nopeusrajoitusotsikoita, liitin voi näiden tietojen avulla säätää pyyntönopeuttaan.

Pyydä esimerkkejä, joissa käytetään Microsoft Graphia tietolähteen ohjelmointirajapintana

Tässä esimerkissä lähetetään kyselyt suodatinkyselyparametrilla. Lisätietoja on artikkelissa Microsoft Graph -ohjelmointirajapinnan kyselyparametrit.

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

Edellinen esimerkki lähettää GET pyynnön käyttäjälle https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Aikaleima päivittyy joka queryWindowInMin kerta.

Saat samat tulokset tällä esimerkillä:

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

On olemassa toinen vaihtoehto tilanteissa, joissa tietolähde odottaa kahta kyselyparametria (yksi aloitusajalle ja toinen päättymisajalle).

Esimerkki:

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

Tämä asetus lähettää GET pyynnön kohteeseen https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Jos kyseessä on monimutkainen kysely, käytä .-parametria QueryParametersTemplate. Tässä esimerkissä lähetetään pyyntö, jonka POST leipätekstissä on parametreja:

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

Vastauksen määritys

Määritä, miten tietoyhdistin käsittelee vastauksia seuraavien parametrien avulla:

Vastauksen määritysesimerkkejä

Odotettiin palvelimen vastausta JSON-muodossa. Vastauksessa on pyydettyjä tietoja ominaisuuden arvossa. Vastauksen ominaisuuden tila ilmaisee tietojen käsittelyn vain, jos arvo on success.

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

Tämän esimerkin odotettu vastaus valmistautuu CSV-tiedostoon, jolla ei ole otsikkoa.

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

Sivutusmääritys

Kun tietolähde ei voi lähettää koko vastauksen hyötykuormaa kerralla, CCF-tietoliittimen on tiedettävä, miten se voi vastaanottaa osia tiedoista vastaussivuilla. Valittavat sivutustyypit ovat seuraavat:

Määritä LinkHeader tai PersistentLinkHeader

Yleisin sivutustyyppi on, kun palvelimen tietolähteen ohjelmointirajapinta tarjoaa URL-osoitteet seuraaville ja aiemmille tietosivuille. Lisätietoja Link header - määrityksestä on kohdassa RFC 5988.

LinkHeader sivutus tarkoittaa, että ohjelmointirajapinnan vastaus sisältää jommankumman seuraavista:

• HTTP-vastauksen Link otsikko.
• JSON-polku linkin noutamiseksi vastauksen leipätekstistä.

PersistentLinkHeader-type-sivutus sisältää samat ominaisuudet kuin LinkHeader, mutta linkin otsikko säilyy taustasäilössä. Tämä asetus ottaa käyttöön linkkien sivuttamisen kyselyikkunoissa.

Esimerkiksi jotkin ohjelmointirajapinnat eivät tue kyselyn alkamis- tai päättymisaikoja. Sen sijaan ne tukevat palvelinpuolen kohdistinta. Pysyvien sivutyyppien avulla voit muistaa palvelinpuolen kohdistimen. Lisätietoja on kohdassa Mikä on kohdistin?.

Seuraavassa on joitakin esimerkkejä:

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

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

Määritä NextPageUrl

NextPageUrl-tyypin sivutus tarkoittaa, että ohjelmointirajapinnan vastaus sisältää vastauksen leipätekstissä monimutkaisen linkin, joka on samanlainen kuin LinkHeader, mutta URL-osoite sisältyy vastauksen leipätekstiin otsikon sijaan.

Esimerkki:

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

Määritä NextPageToken tai PersistentToken

NextPageToken-type-sivutus käyttää tunnusta (hajautusarvoa tai kohdistinta), joka edustaa nykyisen sivun tilaa. Tunnus sisältyy ohjelmointirajapinnan vastaukseen, ja asiakas liittää sen seuraavaan pyyntöön seuraavan sivun noutamiseksi. Tätä menetelmää käytetään usein, kun palvelimen on ylläpidettävä pyyntöjen välistä tarkkaa tilaa.

PersistentToken sivutus käyttää tunnusta, joka säilyy palvelinpuolella. Palvelin muistaa asiakkaan viimeisen noudon tunnuksen ja antaa seuraavan tunnuksen myöhemmissä pyynnöissä. Asiakas jatkaa sitä, mihin jäi, vaikka se tekee uusia pyyntöjä myöhemmin.

Esimerkkejä:

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

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

Määritä siirtymä

Offset-type-sivutus määrittää ohitettavien sivujen määrän ja pyyntöön sivua kohden noudettavien tapahtumien määrän rajoituksen. Asiakkaat noutavat tietojoukosta tietyn kohdealueen.

Esimerkki:

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

Määritä countBasedPaging

CountBasedPaging-type-sivutuksen avulla asiakas voi määrittää vastauksessa palautettavien kohteiden määrän. Tämä ominaisuus on hyödyllinen ohjelmointirajapinnoille, jotka tukevat määräparametrin perusteella sivutusta osana vastauksen hyötykuormaa.

Esimerkki:

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

Dcr-määritys

Esimerkki CCF-tietoyhdistimestä

Tässä on esimerkki kaikista CCF-tietoliittimen JSON:n osista:

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