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

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

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

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

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

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

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 매개 변수 만들기 또는 업데이트를 참조 하세요.

속성	설명
dataConnectorId	데이터 커넥터 ID는 고유한 이름이어야 하며 요청 본문의 `name` 매개 변수와 동일합니다.
resourceGroupName	대/소문자를 구분하지 않는 리소스 그룹의 이름입니다.
구독 ID	대상 구독의 ID입니다.
workspaceName	ID가 아닌 작업 영역의 이름입니다. Regex 패턴: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	이 작업에 사용할 API 버전입니다.

요청 본문

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

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

RestApiPoller

RestApiPoller 는 데이터 원본에 대한 페이징, 권한 부여 및 요청/응답 페이로드를 사용자 지정하는 API Poller CCF 데이터 커넥터를 나타냅니다.

속성	필수	유형	설명
이름	진실	문자열	URI 매개 변수와 일치하는 연결의 고유 이름
종류	진실	문자열	`RestApiPoller`이어야 합니다.
etag		GUID	새 커넥터를 만들기 위해 비워 둡니다. 업데이트 작업의 경우 etag는 기존 커넥터의 etag(GUID)와 일치해야 합니다.
properties.connectorDefinitionName		문자열	데이터 커넥터의 UI 구성을 정의하는 DataConnectorDefinition 리소스의 이름입니다. 자세한 내용은 데이터 커넥터 정의를 참조 하세요.
속성.인증	진실	중첩된 JSON	데이터 폴링을 위한 인증 속성을 설명합니다. 자세한 내용은 인증 구성을 참조하세요.
속성.요청	진실	중첩된 JSON	API 엔드포인트와 같은 데이터 폴링을 위한 요청 페이로드를 설명합니다. 자세한 내용은 요청 구성을 참조하세요.
속성.응답	진실	중첩된 JSON	데이터를 폴링할 때 API에서 반환된 응답 개체 및 중첩 메시지를 설명합니다. 자세한 내용은 응답 구성을 참조하세요.
속성.페이징		중첩된 JSON	데이터를 폴링할 때 페이지 매김 페이로드를 설명합니다. 자세한 내용은 페이징 구성을 참조하세요.
속성.dcrConfig		중첩된 JSON	데이터가 DCR(데이터 수집 규칙)으로 전송되는 경우 필수 매개 변수입니다. 자세한 내용은 DCR 구성을 참조하세요.

인증 구성

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

기본
APIKey
OAuth2
JWT

참고 항목

CCF OAuth2 구현은 클라이언트 인증서 자격 증명을 지원하지 않습니다.

자격 증명을 하드 코딩하는 대신 인증 섹션에서 매개 변수를 사용하는 것이 가장 좋습니다. 자세한 내용은 보안 기밀 입력을 참조 하세요.

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

UI에서 자격 증명을 입력할 수 있도록 하려면 섹션에 connectorUIConfig 원하는 매개 변수가 필요합니다 instructions . 자세한 내용은 Codeless Connector Framework에 대한 데이터 커넥터 정의 참조를 참조하세요.

기본 인증

필드	필수	유형
사용자 이름	진실	문자열
암호	진실	문자열

다음에서 connectorUIconfig정의된 매개 변수를 사용하는 기본 인증 예제:

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

APIKey

필드	필수	유형	설명	기본값
아이피키	진실	문자열	사용자 비밀 키
ApiKeyName		문자열	ApiKey 값을 포함하는 Uri 헤더의 이름	`Authorization`
ApiKeyIdentifier		문자열	토큰 앞에 추가할 문자열 값	`token`
IsApiKeyInPostPayload		부울 값	헤더 대신 POST 본문에 비밀 보내기	`false`

APIKey 인증 예제:

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

이 예제에서는 X-MyApp-Auth-Header: Bearer 헤더에 전송된 사용자 입력에서 정의된 비밀을 생성합니다. apikey

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

이 예제에서는 기본값을 사용하고 다음과 같은 헤더를 생성합니다. 권한 부여: 토큰 123123123

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

ApiKeyName 명시적으로 설정""되므로 결과는 다음 헤더입니다. 권한 부여: 123123123

OAuth2

Codeless Connector Framework는 OAuth 2.0 권한 부여 코드 부여 및 클라이언트 자격 증명을 지원합니다. 인증 코드 부여 형식은 기밀 및 공용 클라이언트가 액세스 토큰에 대한 인증 코드를 교환하는 데 사용됩니다. 사용자가 리디렉션 URL을 통해 클라이언트로 돌아온 후 애플리케이션은 URL에서 인증 코드를 가져와 이를 사용하여 액세스 토큰을 요청합니다.

필드	필수	유형	설명
ClientId	진실	문자열	클라이언트 ID
ClientSecret	진실	문자열	클라이언트 암호
AuthorizationCode	true when grantType = `authorization_code`	문자열	권한 부여 유형이 `authorization_code` 면 이 필드 값은 인증 서비스에서 반환된 권한 부여 코드가 됩니다.
범위	허용 유형에 대해 `authorization_code` True입니다. 권한 부여 유형에 대한 `client_credentials` 선택 사항	문자열	사용자 동의에 대한 공간으로 구분된 범위 목록입니다. 자세한 내용은 OAuth2 범위 및 사용 권한을 참조 하세요.
RedirectUri	true when grantType = `authorization_code`	문자열	리디렉션 URL은 이어야 합니다. `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	진실	문자열	`authorization_code` 또는 `client_credentials`
TokenEndpoint	진실	문자열	권한 부여에서 `authorization_code` 유효한 토큰 또는 클라이언트 ID 및 비밀과 유효한 토큰을 부여하여 코드를 교환하는 `client_credentials` URL입니다.
TokenEndpointHeaders		객체	토큰 서버에 사용자 지정 헤더를 보낼 선택적 키 값 개체입니다.
TokenEndpointQueryParameters		객체	토큰 서버에 사용자 지정 쿼리 매개 변수를 보내는 선택적 키 값 개체입니다.
인증엔드포인트	진실	문자열	흐름에 대한 사용자 동의 URL `authorization_code`
AuthorizationEndpointHeaders		객체	사용자 지정 헤더를 인증 서버로 보내는 선택적 키 값 개체
인증 엔드포인트 쿼리 매개변수		객체	OAuth2 권한 부여 코드 흐름 요청에 사용되는 선택적 키 값 쌍

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

예: 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 Web Token) 인증은 사용자 이름/암호 자격 증명을 통해 토큰을 가져오고 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"
}

인증 흐름:

JWT 토큰을 가져오기 위한 TokenEndpoint 자격 증명 보내기
- If IsCredentialsInHeaders: true: username:password를 사용하여 기본 인증 헤더를 보냅니다.
- If IsCredentialsInHeaders: false: POST 본문에서 자격 증명을 보냅니다.
응답 헤더를 사용 JwtTokenJsonPath 하거나 응답 헤더에서 토큰 추출
헤더를 사용하여 후속 API 요청 ApiKeyName 에서 토큰 사용

속성:

필드	필수	유형	설명
type	진실	문자열	`JwtToken`이어야 합니다.
userName	True( userToken 을 사용하지 않는 경우)	객체	사용자 이름 자격 증명의 키-값 쌍입니다. `userName` 헤더 요청에서 전송되는 경우 `password` 사용자 이름으로 속성을 지정 `value` 합니다. 본문 요청으로 전송된 `userName` 경우 `password` 다음을 지정합니다`Key`.`Value`
암호	True( userToken 을 사용하지 않는 경우)	객체	암호 자격 증명의 키-값 쌍입니다. `userName` 헤더 요청에서 전송되는 경우 `password` 사용자 이름으로 속성을 지정 `value` 합니다. 본문 요청으로 전송된 `userName` 경우 `password` 다음을 지정합니다`Key`.`Value`
userToken	True( userName을 사용하지 않는 경우)	문자열	인증을 위해 시스템 토큰을 가져오기 위해 클라이언트에서 생성한 사용자 토큰
UserTokenPrepend	거짓	문자열	토큰 앞에 텍스트를 추가합니다. 예: `Bearer`
NoAccessTokenPrepend	거짓	불리언 (Boolean)	토큰 앞에 추가하면 안 함을 나타내는 액세스 플래그
TokenEndpointHttpMethod	거짓	문자열	토큰 엔드포인트에 대한 HTTP 메서드입니다. `Get` 또는 `Post`일 수 있습니다. 기본값: `Post`
TokenEndpoint	진실	문자열	JWT 토큰을 가져오는 URL 엔드포인트
IsCredentialsInHeaders		불리언 (Boolean)	자격 증명을 기본 인증 헤더(`true`) 및 POST 본문(`false`)으로 보냅니다. 기본값: `false`
IsJsonRequest		불리언 (Boolean)	요청을 JSON(헤더 `Content-Type = application/json`) 및 폼 인코딩(헤더 `Content-Type = application/x-www-form-urlencoded`)으로 보냅니다. 기본값: `false`
JwtTokenJsonPath		문자열	응답에서 토큰을 추출하는 JSONPath(예: "`$.access_token`")
JwtTokenInResponseHeader		불리언 (Boolean)	응답 헤더와 본문에서 토큰을 추출합니다. 기본값: `false`
JwtTokenHeaderName		문자열	토큰이 응답 헤더에 있을 때의 헤더 이름입니다. 기본값: "`Authorization`"
JwtTokenIdentifier		문자열	접두사 토큰 문자열에서 JWT를 추출하는 데 사용되는 식별자
QueryParameters		객체	토큰 엔드포인트에 요청을 보낼 때 포함할 사용자 지정 쿼리 매개 변수
헤더		객체	토큰 엔드포인트에 요청을 보낼 때 포함할 사용자 지정 헤더
RequestTimeoutInSeconds		정수	요청 시간 제한(초)입니다. 기본값: `100`, 최대 `180`

인증 흐름:

JWT 토큰을 가져오기 위한 TokenEndpoint 자격 증명 보내기
- If IsCredentialsInHeaders: true: username:password를 사용하여 기본 인증 헤더를 보냅니다.
- If IsCredentialsInHeaders: false: POST 본문에서 자격 증명을 보냅니다.
응답 헤더를 사용 JwtTokenJsonPath 하거나 응답 헤더에서 토큰 추출
헤더를 사용하여 후속 API 요청 ApiKeyName 에서 토큰 사용

참고 항목

Limitations:

토큰 획득을 위해 사용자 이름/암호 인증 필요
API 키 기반 토큰 요청을 지원하지 않습니다.
사용자 지정 헤더 인증(사용자 이름/암호 없음)은 지원되지 않습니다.

구성 요청

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

필드	필수	유형	설명
ApiEndpoint	진실	문자열	원격 서버의 URL입니다. 데이터를 가져올 엔드포인트를 정의합니다.
RateLimitQPS		정수	초당 허용되는 호출 또는 쿼리 수를 정의합니다.
RateLimitConfig		객체	RESTful API의 속도 제한 구성을 정의합니다. 예제를 참조하세요.
QueryWindowInMin		정수	사용 가능한 쿼리 창을 분 단위로 정의합니다. 최소값은 1분입니다. 기본값은 5분입니다.
HttpMethod		문자열	API 메서드 `GET`(기본값) 또는 `POST`
QueryTimeFormat		문자열	엔드포인트(원격 서버)가 예상하는 날짜 및 시간 형식을 정의합니다. CCF는 이 변수가 사용되는 모든 위치에서 현재 날짜 및 시간을 사용합니다. 가능한 값은 상수입니다`UnixTimestampUnixTimestampInMills`. 또는 날짜 시간의 다른 유효한 표현(예: `yyyy-MM-dd`< a0/>)입니다.`MM/dd/yyyy HH:mm:ss` 기본값은 ISO 8601 UTC입니다.
RetryCount		정수(1...6)	`1` 오류에서 복구할 `6` 수 있는 재시도를 정의합니다. 기본값은 `3`입니다.
TimeoutInSeconds		정수(1...180)	요청 시간 초과를 초 단위로 정의합니다. 기본값은 `20`
IsPostPayloadJson		불리언 (Boolean)	POST 페이로드가 JSON 형식인지 여부를 결정합니다. 기본값은 `false`
헤더		객체	요청 헤더를 정의하는 키 값 쌍입니다.
QueryParameters		객체	요청 쿼리 매개 변수를 정의하는 키 값 쌍입니다.
StartTimeAttributeName	True이면 설정됩니다.`EndTimeAttributeName`	문자열	쿼리 시작 시간에 대한 쿼리 매개 변수 이름을 정의합니다. 예제를 참조하세요.
EndTimeAttributeName	True이면 설정됩니다.`StartTimeAttributeName`	문자열	쿼리 종료 시간에 대한 쿼리 매개 변수 이름을 정의합니다.
QueryTimeIntervalAttributeName		문자열	엔드포인트에 시간 프레임의 데이터를 쿼리하기 위한 특수 형식이 필요한 경우 이 속성과 매개 변수를 `QueryTimeIntervalPrependQueryTimeIntervalDelimiter` 사용합니다. 예제를 참조하세요.
QueryTimeIntervalPrepend	True이면 설정됩니다.`QueryTimeIntervalAttributeName`	문자열	`QueryTimeIntervalAttributeName`를 참조하세요.
QueryTimeIntervalDelimiter	True이면 설정됩니다.`QueryTimeIntervalAttributeName`	문자열	`QueryTimeIntervalAttributeName`를 참조하세요.
QueryParametersTemplate		문자열	고급 시나리오에서 매개 변수를 전달할 때 사용할 쿼리 템플릿입니다. br>예: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

API에 복잡한 매개 변수가 필요한 경우 일부 기본 제공 변수를 queryParameters 사용하거나 queryParametersTemplate 포함합니다.

기본 제공 변수	에서 사용할 수 있습니다. `queryParameters`	에서 사용할 수 있습니다. `queryParametersTemplate`
`_QueryWindowStartTime`	예	예
`_QueryWindowEndTime`	예	예
`_APIKeyName`	아니요	예
`_APIKey`	아니요	예

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

이전 예제에서는 요청을 .에 GEThttps://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000보냅니다. 매번 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}"
  }
}

또 다른 옵션은 데이터 원본에 2개의 쿼리 매개 변수가 예상되는 경우입니다. 하나는 시작 시간용이고 다른 하나는 종료 시간에 대한 매개 변수입니다.

예시:

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

그러면 다음으로 요청을 보냅니다.GEThttps://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

복잡한 쿼리의 경우 .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}))\"}"
}

응답 구성

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

필드	필수	유형	설명
EventsJsonPaths	진실	문자열 목록	응답 JSON의 메시지 경로를 정의합니다. JSON 경로 표현식은 JSON 구조에서 요소 또는 요소 집합에 대한 경로를 지정합니다.
SuccessStatusJsonPath		문자열	응답 JSON에서 성공 메시지의 경로를 정의합니다. 이 매개 변수가 정의 `SuccessStatusValue` 되면 매개 변수도 정의되어야 합니다.
SuccessStatusValue		문자열	응답 JSON에서 성공 메시지 값에 대한 경로를 정의합니다.
IsGzipCompressed		불리언 (Boolean)	응답이 gzip 파일에서 압축되는지 여부를 확인합니다.
format	진실	문자열	`json` 또는 `csv` 또는 `xml`
CompressionAlgo		문자열	압축 알고리즘 중 하나 `multi-gzip` 또는 `deflate`. gzip 압축 알고리즘의 경우 이 매개 변수의 값을 설정하는 대신 구성 `IsGzipCompressedTrue` 하기만 하면 됩니다.
CsvDelimiter		문자열	응답 형식이 CSV이고 기본 CSV 구분 기호를 변경하려는 경우 `","`
HasCsvBoundary		불리언 (Boolean)	CSV 데이터에 경계가 있는지 여부를 나타냅니다.
HasCsvHeader		불리언 (Boolean)	CSV 데이터에 헤더가 있는지 여부를 나타냅니다. 기본값은 다음과 같습니다. `True`
CsvEscape		문자열	필드 경계의 이스케이프 문자, 기본값은 `"` 예를 들어 헤더 `id,name,avg` 가 있는 CSV와 같은 `1,"my name",5.5` 공백이 포함된 데이터 행에는 필드 경계가 `"` 필요합니다.
ConvertChildPropertiesToArray		불리언 (Boolean)	원격 서버가 각 속성에 데이터가 있는 이벤트 목록 대신 개체를 반환하는 특수한 경우입니다.

참고 항목

CSV 형식 형식은 RFC4180 사양에 따라 구문 분석됩니다.

응답 구성 예제

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

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

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

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

페이징 구성

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

페이징 유형	의사 결정 요소
LinkHeader PersistentLinkHeader NextPageUrl	API 응답에 다음 및 이전 페이지에 대한 링크가 있나요?
NextPageToken PersistentToken	API 응답에 다음 및 이전 페이지에 대한 토큰 또는 커서가 있나요?
오프셋	API 응답은 페이징할 때 건너뛸 개체 수에 대한 매개 변수를 지원하나요?
CountBasedPaging	API 응답이 반환할 개체 수에 대한 매개 변수를 지원하나요?

LinkHeader 또는 PersistentLinkHeader 구성

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

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

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

PersistentLinkHeader 페이징에는 링크 헤더가 백 엔드 스토리지에 유지되는 것을 제외하고 동일한 속성 LinkHeader이 있습니다. 이 옵션을 사용하면 쿼리 창에서 링크를 페이징할 수 있습니다. 예를 들어 일부 API는 쿼리 시작 시간 또는 종료 시간을 지원하지 않습니다. 대신 서버 쪽 커서를 지원합니다. 영구 페이지 형식을 사용하여 서버 쪽 커서를 기억할 수 있습니다. 자세한 내용은 커서란?을 참조하세요.

참고 항목

서버 쪽 커서의 경합 상태를 방지하기 위해 PersistentLinkHeader를 사용하여 커넥터에 대해 실행되는 쿼리는 하나만 있을 수 있습니다. 이는 대기 시간에 영향을 줄 수 있습니다.

필드	필수	유형	설명
LinkHeaderTokenJsonPath	거짓	문자열	응답 본문에서 값을 가져올 위치를 나타내려면 이 속성을 사용합니다. 예를 들어 데이터 원본이 다음 JSON `{ nextPage: "foo", value: [{data}]}LinkHeaderTokenJsonPath` 을 반환하는 경우 다음이 됩니다. `$.nextPage`
페이지 크기	거짓	정수	페이지당 이벤트 수
PageSizeParameterName	거짓	문자열	페이지 크기에 대한 쿼리 매개 변수 이름
페이징 정보 배치	거짓	문자열	페이징 정보가 어떻게 채워지는지. "QueryString" 또는 "RequestBody" 중 하나를 받습니다
PagingQueryParamOnly	거짓	불리언 (Boolean)	true로 설정하면 페이징 쿼리 매개변수를 제외한 모든 쿼리 매개변수를 생략합니다.

다음 몇 가지 예를 참조하세요.

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

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

NextPageUrl 구성

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

필드	필수	유형	설명
페이지 크기	거짓	정수	페이지당 이벤트 수
PageSizeParameterName	거짓	문자열	페이지 크기에 대한 쿼리 매개 변수 이름
NextPageUrl	거짓	문자열	커넥터가 Coralogix API용인 경우에만
NextPageUrlQueryParameters	거짓	개체 키 값 쌍 – 다음 페이지에 대한 각 요청에 사용자 지정 쿼리 매개 변수 추가
NextPageParaName	거짓	문자열	요청에서 다음 페이지 이름을 결정합니다.
HasNextFlagJsonPath	거짓	문자열	HasNextPage 플래그 특성의 경로를 정의합니다.
NextPageRequestHeader	거짓	문자열	요청에서 다음 페이지 헤더 이름을 결정합니다.
NextPageUrlQueryParametersTemplate	거짓	문자열	커넥터가 Coralogix API용인 경우에만
페이징 정보 배치	거짓	문자열	페이징 정보가 어떻게 채워지는지. "QueryString" 또는 "RequestBody" 중 하나를 받습니다
PagingQueryParamOnly	거짓	불리언 (Boolean)	true로 설정하면 페이징 쿼리 매개변수를 제외한 모든 쿼리 매개변수를 생략합니다.

예시:

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

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

필드	필수	유형	설명
페이지 크기	거짓	정수	페이지당 이벤트 수
PageSizeParameterName	거짓	문자열	페이지 크기에 대한 쿼리 매개 변수 이름
NextPageTokenJsonPath	거짓	문자열	응답 본문의 다음 페이지 토큰에 대한 JSON 경로입니다.
NextPageTokenResponseHeader	거짓	문자열	비어 있는 경우 `NextPageTokenJsonPath` 다음 페이지의 이 헤더 이름에 있는 토큰을 사용합니다.
NextPageParaName	거짓	문자열	요청에서 다음 페이지 이름을 결정합니다.
HasNextFlagJsonPath	거짓	문자열	응답에 더 많은 페이지가 남아 있는지 확인할 때 HasNextPage 플래그 특성의 경로를 정의합니다.
NextPageRequestHeader	거짓	문자열	요청에서 다음 페이지 헤더 이름을 결정합니다.
페이징 정보 배치	거짓	문자열	페이징 정보가 어떻게 채워지는지. "QueryString" 또는 "RequestBody" 중 하나를 받습니다
PagingQueryParamOnly	거짓	불리언 (Boolean)	true로 설정하면 페이징 쿼리 매개변수를 제외한 모든 쿼리 매개변수를 생략합니다.

예:

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

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

오프셋 구성

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

필드	필수	유형	설명
페이지 크기	거짓	정수	페이지당 이벤트 수
PageSizeParameterName	거짓	문자열	페이지 크기에 대한 쿼리 매개 변수 이름
OffsetParaName	거짓	문자열	다음 요청 쿼리 매개 변수 이름입니다. CCF는 각 요청의 오프셋 값을 계산합니다(수집된 모든 이벤트 + 1).
페이징 정보 배치	거짓	문자열	페이징 정보가 어떻게 채워지는지. "QueryString" 또는 "RequestBody" 중 하나를 받습니다
PagingQueryParamOnly	거짓	불리언 (Boolean)	true로 설정하면 페이징 쿼리 매개변수를 제외한 모든 쿼리 매개변수를 생략합니다.

예시:

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

CountBasedPaging 구성

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

필드	필수	유형	설명
pageNumberParaName	진실	문자열	HTTP 요청의 페이지 번호 매개 변수 이름
페이지 크기	거짓	정수	페이지당 이벤트 수
ZeroBasedIndexing	거짓	불리언 (Boolean)	개수가 0부터 시작하는지 여부를 나타내는 플래그
HasNextFlagJsonPath	거짓	문자열	더 많은 페이지가 있음을 나타내는 HTTP 응답 페이로드의 플래그 JSON 경로
TotalResultsJsonPath	거짓	문자열	HTTP 응답 페이로드의 총 결과 수에 대한 JSON 경로
PageNumberJsonPath	거짓	문자열	totalResultsJsonPath가 제공되는 경우 필요합니다. HTTP 응답 페이로드의 페이지 번호 JSON 경로
PageCountJsonPath	거짓	문자열	totalResultsJsonPath가 제공되는 경우 필요합니다. HTTP 응답 페이로드의 페이지 수 JSON 경로
페이징 정보 배치	거짓	문자열	페이징 정보가 어떻게 채워지는지. "QueryString" 또는 "RequestBody" 중 하나를 받습니다
PagingQueryParamOnly	거짓	불리언 (Boolean)	true로 설정하면 페이징 쿼리 매개변수를 제외한 모든 쿼리 매개변수를 생략합니다.

예시:

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

DCR 구성

필드	필수	유형	설명
DataCollectionEndpoint	진실	문자열	DCE(데이터 수집 엔드포인트) 예: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	진실	문자열	DCR 변경할 수 없는 ID입니다. DCR 만들기 응답을 보거나 DCR API를 사용하여 찾습니다.
StreamName	진실	문자열	이 값은 DCR에 정의된 값입니다 `streamDeclaration` (접두사는 Custom-으로 시작해야 합니다.)

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-11

다음을 통해 공유

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

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

URI 매개 변수

요청 본문

RestApiPoller

인증 구성

기본 인증

APIKey

OAuth2

JWT

구성 요청

StartTimeAttributeName 예제

QueryTimeIntervalAttributeName 예제

RateLimitConfig 예시

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

응답 구성

응답 구성 예제

페이징 구성

LinkHeader 또는 PersistentLinkHeader 구성

NextPageUrl 구성

NextPageToken 또는 PersistentToken 구성

오프셋 구성

CountBasedPaging 구성

DCR 구성

CCF 데이터 커넥터 예제

피드백

추가 리소스