Referens för RestApiPoller-dataanslutning för Codeless Connector Framework

Du kan skapa en RestApiPoller dataanslutning med Codeless Connector Framework (CCF) med hjälp av den här artikeln som ett komplement till dokumentet om Microsoft Sentinel REST API för dataanslutningsprogram.

Varje dataanslutning representerar en specifik anslutning för en Microsoft Sentinel dataanslutning. En dataanslutning kan ha flera anslutningar som hämtar data från olika slutpunkter. Du kan slutföra distributionsmallen för CCF-dataanslutningen med hjälp av JSON-konfigurationen som du skapar med den här artikeln.

Mer information finns i Skapa en kodlös anslutningsapp för Microsoft Sentinel.

Skapa eller uppdatera dataanslutningar

Hitta den senaste stabila versionen eller förhandsversionen av API:et create genom att referera till åtgärderna eller update i REST API-dokumenten. Skillnaden mellan create åtgärderna och update är att update det kräver etag värdet.

PUT Metod:

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

URI-parametrar

Mer information om den senaste API-versionen finns i Dataanslutningar: skapa eller uppdatera URI-parametrar.

Frågebrödtext

Begärandetexten för en RestApiPoller CCF-dataanslutning har följande struktur:

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

RestApiPoller

RestApiPoller är en CCF-dataanslutning för API-poller som du kan använda för att anpassa nyttolaster för sidindelning, auktorisering och begäran/svar för din datakälla.

Autentiseringskonfiguration

CCF stöder följande autentiseringstyper:

• Basic
• API-nyckel
• OAuth2
• JWT

Vi rekommenderar att du använder parametrar i autentiseringsavsnittet i stället för hårdkodade autentiseringsuppgifter. Mer information finns i Skydda konfidentiella indata.

Om du vill skapa distributionsmallen, som även använder parametrar, måste du undvika parametrarna i det här avsnittet med en extra start [. Med det här steget kan parametrarna tilldela ett värde baserat på användarinteraktionen med anslutningsappen. Mer information finns i Escape-tecken för malluttryck.

För att aktivera autentiseringsuppgifterna som ska anges från användargränssnittet connectorUIConfig kräver avsnittet att du anger önskade parametrar i instructions. Mer information finns i Referens för definitioner för dataanslutningsprogram för Codeless Connector Framework.

Grundläggande autentisering

Här är ett exempel på grundläggande autentisering som använder parametrar som definierats i connectorUIconfig:

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

API-nyckel

APIKey autentiseringsexempel:

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

Resultatet av det här exemplet är hemligheten som definieras från användarindata som skickas i följande rubrik: : X-MyApp-Auth-HeaderBearer apikey.

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

I det här exemplet används standardvärdena och resultatet i följande rubrik: : Authorizationtoken 123123123.

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

Eftersom ApiKeyName är uttryckligen inställt på ""är resultatet följande rubrik: : Authorization123123123.

OAuth2

Codeless Connector Framework stöder beviljande av OAuth 2.0-auktoriseringskod och klientautentiseringsuppgifter. Beviljandetypen auktoriseringskod används av konfidentiella och offentliga klienter för att utbyta en auktoriseringskod för en åtkomsttoken.

När användaren återvänder till klienten via omdirigerings-URL:en hämtar programmet auktoriseringskoden från URL:en och använder den för att begära en åtkomsttoken.

Du kan använda autentiseringskodflödet för att hämta data för en användares behörigheter. Du kan använda klientautentiseringsuppgifter för att hämta data med programbehörigheter. Dataservern ger åtkomst till programmet. Eftersom det inte finns någon användare i flödet för klientautentiseringsuppgifter behövs ingen auktoriseringsslutpunkt, bara en tokenslutpunkt.

Här är ett exempel på OAuth2-beviljandetypen 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"
}

Här är ett exempel på OAuth2-beviljandetypen 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-webbtokenautentisering (JWT) stöder hämtning av token via autentiseringsuppgifter för användarnamn och lösenord och använder dem för API-begäranden.

Grundläggande exempel

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

Autentiseringsuppgifter i POST-brödtext (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"
}

Autentiseringsuppgifter i rubriker (grundläggande autentisering)

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

Autentiseringsuppgifter i rubriker (användartoken)

"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ölj det här autentiseringsflödet:

1. Skicka autentiseringsuppgifter till TokenEndpoint för att hämta JWT-token, när du använder userName och password, IsCredentialsInHeaders används för att avgöra var autentiseringsuppgifterna ska placeras i begäran.

   • Om IsCredentialsInHeaders: true: Skickar en grundläggande autentiseringsrubrik med username:password.
   • Om IsCredentialsInHeaders: false: Skickar autentiseringsuppgifter i en POST brödtext.

2. Extrahera token med hjälp JwtTokenJsonPath av eller från svarshuvudet.

3. Auktoriseringshuvudet för JWT-token är en konstant och kommer alltid att vara "Authorization".

Konfiguration av begäranden

Avsnittet för begäran definierar hur CCF-dataanslutningsappen skickar begäranden till din datakälla (till exempel API-slutpunkten och hur ofta slutpunkten ska avsökas).

När API:et kräver komplexa parametrar använder du queryParameters eller queryParametersTemplate. Dessa kommandon innehåller några inbyggda variabler.

StartTimeAttributeName-exempel

Tänk dig det här exemplet:

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

Frågan som skickas till fjärrservern är: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

QueryTimeIntervalAttributeName-exempel

Tänk dig det här exemplet:

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

Frågan som skickas till fjärrservern är: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

RateLimitConfig-exempel

Tänk dig det här exemplet:

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 innehåller hastighetsbegränsningshuvuden kan anslutningsappen använda den här informationen för att justera begärandefrekvensen.

Begära exempel som använder Microsoft Graph som API för datakälla

Det här exemplet frågar efter meddelanden med en filterfrågeparameter. Mer information finns i Microsoft Graph API frågeparametrar.

"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 föregående exempel skickas en GET begäran till https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Tidsstämpeln uppdateras för varje queryWindowInMin gång.

Du får samma resultat med det här exemplet:

"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 finns ett annat alternativ för situationer där datakällan förväntar sig två frågeparametrar (en för starttid och en för sluttid).

Exempel:

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

Det här alternativet skickar en GET begäran till https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

För komplexa frågor använder du QueryParametersTemplate. Det här exemplet skickar en POST begäran med parametrar i brödtexten:

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

Svarskonfiguration

Definiera hur dataanslutningsappen hanterar svar med hjälp av följande parametrar:

Exempel på svarskonfiguration

Ett serversvar i JSON-format förväntas. Svaret har begärda data i egenskapsvärdet. Statusen för svarsegenskapen anger att data endast ska matas in om värdet är success.

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

Det förväntade svaret i det här exemplet förbereder för en CSV utan sidhuvud.

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

Växlingskonfiguration

När datakällan inte kan skicka hela svarsnyttolasten på en gång måste CCF-dataanslutningen veta hur du tar emot delar av data på svarssidorna. Växlingstyperna att välja mellan är:

Konfigurera LinkHeader eller PersistentLinkHeader

Den vanligaste växlingstypen är när ett API för serverdatakälla tillhandahåller URL:er till nästa och föregående datasidor. Mer information om link header-specifikationen finns i RFC 5988.

LinkHeader sidindelning innebär att API-svaret innehåller antingen:

• HTTP-svarshuvudet Link .
• En JSON-sökväg för att hämta länken från svarstexten.

PersistentLinkHeader-type paging har samma egenskaper som LinkHeader, förutom att länkrubriken finns kvar i serverdelslagringen. Det här alternativet aktiverar sidindelningslänkar mellan frågefönster.

Vissa API:er stöder till exempel inte frågestarttider eller sluttider. I stället stöder de en markör på serversidan. Du kan använda beständiga sidtyper för att komma ihåg markören på serversidan. Mer information finns i Vad är en markör?.

Här är några exempel:

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

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

Konfigurera NextPageUrl

NextPageUrl-type paging innebär att API-svaret innehåller en komplex länk i svarstexten som liknar LinkHeader, men URL:en ingår i svarstexten i stället för rubriken.

Exempel:

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

Konfigurera NextPageToken eller PersistentToken

NextPageToken-type pagination använder en token (en hash eller en markör) som representerar tillståndet för den aktuella sidan. Token ingår i API-svaret och klienten lägger till den i nästa begäran om att hämta nästa sida. Den här metoden används ofta när servern behöver upprätthålla det exakta tillståndet mellan begäranden.

PersistentToken sidnumrering använder en token som bevarar serversidan. Servern kommer ihåg den senaste token som klienten hämtade och tillhandahåller nästa token i efterföljande begäranden. Klienten fortsätter där den slutade, även om den gör nya begäranden senare.

Exempel:

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

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

Konfigurera förskjutning

Offset-type pagination anger antalet sidor som ska hoppa över och en gräns för antalet händelser som ska hämtas per sida i begäran. Klienter hämtar ett visst intervall med objekt från datauppsättningen.

Exempel:

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

Konfigurera CountBasedPaging

CountBasedPaging-type pagination gör att klienten kan ange antalet objekt som ska returneras i svaret. Den här funktionen är användbar för API:er som stöder sidnumrering baserat på en antalsparameter som en del av svarsnyttolasten.

Exempel:

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

DCR-konfiguration

Exempel på CCF-dataanslutning

Här är ett exempel på alla komponenter i CCF-dataanslutningsappens 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": ["$"]
      }
   }
}