Codeless Connector Framework에 대한 RestApiPoller 데이터 커넥터 참조

이 문서를 데이터 커넥터용 Microsoft Sentinel REST API 문서의 보완으로 사용하여 CCF(Codeless Connector Framework)를 사용하여 데이터 커넥터를 만들 RestApiPoller 수 있습니다.

각 데이터 커넥터는 Microsoft Sentinel 데이터 커넥터의 특정 연결을 나타냅니다. 하나의 데이터 커넥터에는 여러 연결이 있을 수 있으며, 이 연결은 서로 다른 엔드포인트에서 데이터를 가져옵니다. 이 문서를 사용하여 빌드한 JSON 구성을 사용하여 CCF 데이터 커넥터에 대한 배포 템플릿을 완료할 수 있습니다.

자세한 내용은 Microsoft Sentinel 대한 코드리스 커넥터 만들기를 참조하세요.

데이터 커넥터 만들기 또는 업데이트

REST API 문서에서 또는 작업을 참조하여 create 안정적인 최신 또는 update 미리 보기 API 버전을 찾습니다. 와 작업의 차이점은 create 값이 update 필요하다는 것입니다etag.update

PUT 메서드:

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

URI 매개 변수

최신 API 버전에 대한 자세한 내용은 데이터 커넥터: URI 매개 변수 만들기 또는 업데이트를 참조하세요.

요청 본문

CCF 데이터 커넥터에 RestApiPoller 대한 요청 본문에는 다음과 같은 구조가 있습니다.

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

RestApiPoller

RestApiPoller 는 데이터 원본에 대한 페이징, 권한 부여 및 요청/응답 페이로드를 사용자 지정하는 데 사용할 수 있는 API 폴러 CCF 데이터 커넥터입니다.

인증 구성

CCF는 다음 인증 유형을 지원합니다.

• 기본
• API 키
• OAuth2
• Jwt

모범 사례로 하드 코딩 자격 증명 대신 인증 섹션에서 매개 변수를 사용합니다. 자세한 내용은 기밀 입력 보안을 참조하세요.

매개 변수를 사용하는 배포 템플릿을 만들려면 이 섹션의 매개 변수를 추가로 시작하여 [이스케이프해야 합니다. 이 단계를 통해 매개 변수는 커넥터와의 사용자 상호 작용에 따라 값을 할당할 수 있습니다. 자세한 내용은 템플릿 식 이스케이프 문자를 참조하세요.

UI connectorUIConfig 에서 자격 증명을 입력할 수 있도록 하려면 섹션에서 에 원하는 매개 변수 instructions를 입력해야 합니다. 자세한 내용은 코드리스 커넥터 프레임워크에 대한 데이터 커넥터 정의 참조를 참조하세요.

기본 인증

다음은 에 정의된 매개 변수를 사용하는 기본 인증의 예입니다.connectorUIconfig

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

API 키

APIKey 인증 예제:

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

이 예제의 결과는 헤더로 전송된 사용자 입력에서 정의된 비밀입니다. : X-MyApp-Auth-HeaderBearer apikey.

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

이 예제에서는 기본값을 사용하고 헤더를 생성합니다. : Authorizationtoken 123123123.

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

ApiKeyName 는 명시적으로 로 설정되므로 ""결과는 헤더: Authorization123123123입니다.

OAuth2

코드리스 커넥터 프레임워크는 OAuth 2.0 권한 부여 코드 부여 및 클라이언트 자격 증명을 지원합니다. 권한 부여 코드 부여 유형은 기밀 및 퍼블릭 클라이언트에서 액세스 토큰에 대한 권한 부여 코드를 교환하는 데 사용됩니다.

사용자가 리디렉션 URL을 통해 클라이언트로 돌아온 후 애플리케이션은 URL에서 권한 부여 코드를 가져와 액세스 토큰을 요청하는 데 사용합니다.

인증 코드 흐름을 사용하여 사용자의 권한을 대신하여 데이터를 가져올 수 있습니다. 클라이언트 자격 증명을 사용하여 애플리케이션 권한이 있는 데이터를 가져올 수 있습니다. 데이터 서버는 애플리케이션에 대한 액세스 권한을 부여합니다. 클라이언트 자격 증명 흐름에 사용자가 없으므로 권한 부여 엔드포인트가 필요하지 않고 토큰 엔드포인트만 필요합니다.

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

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

JWT(JSON 웹 토큰) 인증은 사용자 이름 및 암호 자격 증명을 통해 토큰을 가져오고 API 요청에 사용할 수 있도록 지원합니다.

기본 예제

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

POST 본문의 자격 증명(기본값)

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

헤더의 자격 증명(기본 인증)

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

헤더의 자격 증명(사용자 토큰)

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

다음 인증 흐름을 따릅니다.

1. 및 를 TokenEndpoint 사용할 userNamepasswordIsCredentialsInHeaders 때 JWT 토큰을 가져오기 위해 에 자격 증명을 보내면 요청에 자격 증명을 넣을 위치를 결정하는 데 사용됩니다.

   • 경우 IsCredentialsInHeaders: true: 를 사용하여 기본 인증 헤더를 username:password보냅니다.
   • 경우 IsCredentialsInHeaders: false: 본문에 자격 증명을 POST 보냅니다.

2. 응답 헤더에서 또는 을 사용하여 JwtTokenJsonPath 토큰을 추출합니다.

3. JWT 토큰에 대한 권한 부여 헤더는 상수이며 항상 "권한 부여"가 됩니다.

요청 구성

요청 섹션에서는 CCF 데이터 커넥터가 데이터 원본에 요청을 보내는 방법(예: API 엔드포인트 및 해당 엔드포인트를 폴링하는 빈도)을 정의합니다.

API에 복잡한 매개 변수가 필요한 경우 또는 queryParametersTemplate를 사용합니다queryParameters. 이러한 명령에는 몇 가지 기본 제공 변수가 포함됩니다.

StartTimeAttributeName 예제

다음 예제를 고려해 보세요.

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

원격 서버로 전송되는 쿼리는 입니다 https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

QueryTimeIntervalAttributeName 예제

다음 예제를 고려해 보세요.

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

원격 서버로 전송되는 쿼리는 입니다 https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

RateLimitConfig 예제

다음 예제를 고려해 보세요.

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

응답에 속도 제한 헤더가 포함된 경우 커넥터는 이 정보를 사용하여 요청 속도를 조정할 수 있습니다.

Microsoft Graph를 데이터 원본 API로 사용하는 요청 예제

다음은 필터 쿼리 매개 변수를 사용하여 메시지를 쿼리하는 예제입니다. 자세한 내용은 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 "
}

이전 예제에서는 에 요청을 https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000보냅니다GET. 타임스탬프는 매번 queryWindowInMin 업데이트됩니다.

다음 예제를 사용하여 동일한 결과를 얻을 수 있습니다.

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

데이터 원본에 두 개의 쿼리 매개 변수(시작 시간 및 종료 시간에 대한 매개 변수)가 필요한 상황에 대한 또 다른 옵션이 있습니다.

예:

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

이 옵션은 에 요청을 https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000보냅니다GET.

복잡한 쿼리의 경우 를 사용합니다 QueryParametersTemplate. 이 예제에서는 본문에 매개 변수가 POST 있는 요청을 보냅니다.

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

응답 구성

다음 매개 변수를 사용하여 데이터 커넥터가 응답을 처리하는 방법을 정의합니다.

응답 구성 예제

JSON 형식의 서버 응답이 필요합니다. 응답에는 요청된 데이터가 속성 값에 있습니다. 응답 속성 상태 값success이 인 경우에만 데이터를 수집하도록 나타냅니다.

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

이 예제의 예상 응답은 헤더가 없는 CSV를 준비합니다.

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

페이징 구성

데이터 원본이 전체 응답 페이로드를 한 번에 모두 보낼 수 없는 경우 CCF 데이터 커넥터는 응답 페이지에서 데이터의 일부를 받는 방법을 알고 있어야 합니다. 선택할 페이징 유형은 다음과 같습니다.

LinkHeader 또는 PersistentLinkHeader 구성

가장 일반적인 페이징 유형은 서버 데이터 원본 API가 데이터의 다음 페이지와 이전 페이지에 대한 URL을 제공하는 경우입니다. 링크 헤더 사양에 대한 자세한 내용은 을 참조하세요RFC 5988.

LinkHeader 페이징은 API 응답에 다음 중 하나가 포함됨을 의미합니다.

• HTTP 응답 헤더입니다 Link .
• 응답 본문에서 링크를 검색하는 JSON 경로입니다.

PersistentLinkHeader-type 페이징은 링크 헤더가 백 엔드 스토리지에 유지되는 것을 제외하고 와 동일한 속성을 LinkHeader가집니다. 이 옵션을 사용하면 쿼리 창에서 링크를 페이징할 수 있습니다.

예를 들어 일부 API는 쿼리 시작 시간 또는 종료 시간을 지원하지 않습니다. 대신 서버 쪽 커서를 지원 합니다. 영구 페이지 형식을 사용하여 서버 쪽 커서를 기억할 수 있습니다. 자세한 내용은 커서란?을 참조하세요.

다음은 몇 가지 예입니다.

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

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

NextPageUrl 구성

NextPageUrl-type 페이징은 API 응답이 응답 본문과 유사한 LinkHeader복잡한 링크를 포함하지만 URL이 헤더 대신 응답 본문에 포함됨을 의미합니다.

예:

"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 또는 PersistentToken 구성

NextPageToken-type 페이지 매김은 현재 페이지의 상태를 나타내는 토큰(해시 또는 커서)을 사용합니다. 토큰은 API 응답에 포함되며 클라이언트는 다음 요청에 토큰을 추가하여 다음 페이지를 가져옵니다. 이 메서드는 서버가 요청 간의 정확한 상태를 유지해야 하는 경우에 자주 사용됩니다.

PersistentToken 페이지 매김은 서버 쪽을 유지하는 토큰을 사용합니다. 서버는 클라이언트가 검색한 마지막 토큰을 기억하고 후속 요청에서 다음 토큰을 제공합니다. 클라이언트는 나중에 새 요청을 하는 경우에도 중단된 위치를 계속합니다.

예제:

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

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

오프셋 구성

Offset-type 페이지 매김은 건너뛸 페이지 수와 요청의 페이지당 검색할 이벤트 수 제한을 지정합니다. 클라이언트는 데이터 집합에서 특정 범위의 항목을 가져옵니다.

예:

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

CountBasedPaging 구성

CountBasedPaging-type 페이지 매김을 사용하면 클라이언트가 응답에서 반환할 항목 수를 지정할 수 있습니다. 이 기능은 응답 페이로드의 일부로 count 매개 변수를 기반으로 페이지 매김을 지원하는 API에 유용합니다.

예:

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

DCR 구성

CCF 데이터 커넥터 예제

CCF 데이터 커넥터 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": ["$"]
      }
   }
}