콘텐츠로 이동

외부 이벤트 모니터 이벤트 수신



POST /api/v1/push-events/{secret}/{subUri}

개요

구성된 외부 이벤트 Webhook을 통해 단일 비즈니스 이벤트를 수신합니다.

호출 전 및 사용 단계

먼저 jsonScript.type=OuterEventChecker인 모니터를 생성하고 활성화한 뒤, 신뢰할 수 있는 상세 정보에서 secret 및 subUri를 가져와 해당 전용 Webhook으로 보고합니다. 이 엔드포인트는 requireSignIn=false이며 DF-API-KEY를 검증하지 않습니다. URL의 secret은 위치 식별/접근 역할을 하므로 자격 증명처럼 보관해야 하며 실제 주소를 공개해서는 안 됩니다. subUri는 단일 경로 세그먼트여야 하고 /를 포함할 수 없으며, 슬래시를 %2F로 작성해도 현재 공개 라우트와 일치하지 않습니다. 새 구성에는 datakit-push와 같은 간단한 값을 권장합니다.

일치하지 않는다고 해서 조용히 무시되는 것은 아닙니다. secret을 알 수 없으면 일반적으로 404가 반환되고, 접미사가 일치하지 않거나 규칙이 비활성화된 경우에는 해당 비즈니스 오류가 반환됩니다. 워크스페이스가 잠긴 경우에도 거부되며, 잠금 상태는 최대 약 10분 동안 캐시될 수 있습니다. event의 고정 필드 이외의 사용자 정의 필드는 문자열만 가능하며, 디멘션, 이미 바인딩된 key:value 태그 키 또는 예약 필드를 덮어쓸 수 없습니다. extraData에는 보조 JSON을 별도로 담습니다.

검증을 통과하면 동기적으로 이벤트 처리 서비스를 호출하여 모니터/그룹/태그 및 채널 컨텍스트를 다운스트림에 함께 전달합니다. 규칙의 isChangeEvent=true인 경우 변경 이벤트 소스로 처리합니다. 성공 응답은 다운스트림 함수 결과를 그대로 감쌉니다. SDK는 HTTP 상태만으로 실패를 일괄 판단하지 않으며, 객체가 아니면서 200이 아니거나 명시적 ok=false인 경우 일반적으로 ft.OuterFuncFailed로 전환됩니다. 반면 객체의 ok가 false가 아닌 경우 업스트림 5xx에서도 최상위 HTTP 200이 반환될 수 있으므로 content의 비즈니스 결과를 반드시 확인해야 합니다. 여기서 이벤트가 모든 조회/알림 페이지에 표시된다는 점을 보장하지 않으며, 이벤트 전역 고유 ID나 멱등 자격 증명도 반환하지 않습니다. 이 API에는 biz_ticket 등의 필드를 기반으로 한 중복 제거 보장이 없으므로, 타임아웃 후에는 이벤트가 이미 생성되었는지 먼저 조회한 뒤 재시도 여부를 결정해야 합니다. OpenAPI의 이 라우트는 AIAPI의 추가 호출 감사 컨텍스트 처리를 수행하지 않습니다.

라우트 매개변수

매개변수명 유형 필수 설명
secret string Y 필수 경로 세그먼트이며 DF-API-KEY가 아닙니다. 저장된 삭제되지 않은 규칙과 정확히 일치해야 합니다.
예: SECRET-PLACEHOLDER
가져오기 또는 입력 방법: 대상 외부 이벤트 모니터 상세 정보의 secret에서 가져옵니다.
subUri string Y 필수 단일 경로 세그먼트이며 대소문자를 정확히 구분하고 슬래시를 포함하지 않습니다. 여러 단계의 URL을 직접 조합하지 않습니다.
예: datakit-push
가져오기 또는 입력 방법: 동일한 규칙의 jsonScript.subUri에서 가져옵니다.

Body 요청 매개변수

매개변수명 유형 필수 설명
event.status string 필수입니다. 프로토콜 소문자를 사용하며 errorEvent/nodata로 대체할 수 없습니다.
예: warning
가져오기 또는 입력 방법: fatal/critical/error/warning/info/ok 중에서 해당 비즈니스 상태를 선택합니다.
event.date integer 선택 사항이며 밀리초/마이크로초가 아닙니다. 생략하면 그대로 다운스트림에 전달하지 않으며 이벤트 시간은 다운스트림에서 결정합니다. 클라이언트가 미래/비정상 시간을 사용할 수 있음을 보장하지 않습니다.
예: 1785427200
가져오기 또는 입력 방법: 외부 이벤트의 실제 발생 시간을 Unix 초 정수로 변환합니다.
event.title string 선택적 문자열입니다. 생략하면 Studio에서 고정 제목을 보충하지 않으며 최종적으로 수신 서비스 프로토콜에 따라 처리됩니다.
예: 生产服务异常
가져오기 또는 입력 방법: 비즈니스 알림 제목에서 가져옵니다.
event.message string 선택적 문자열이며 JSON 배열이 아닙니다. 비밀 키를 포함하지 마십시오.
예: 健康检查返回错误。
가져오기 또는 입력 방법: 외부 감지 결과에서 이벤트를 식별할 수 있는 내용을 입력합니다.
event.dimension_tags json 선택적 객체이며 디멘션 키는 _ 또는 df_로 시작할 수 없습니다. 이 계층에서는 객체 및 키만 검사하며, 값은 이벤트 디멘션에 사용할 수 있는 단순 데이터 유형을 선택해야 하고 사용자 정의 최상위 동일 이름 필드로 중복할 수 없습니다.
예: {"host": "web-example", "service": "production"}
가져오기 또는 입력 방법: 이 이벤트의 실제 호스트/서비스 등 디멘션 필드 및 값을 선택합니다.
event.dimension_tags.디멘션 이름 any 동적 디멘션 값이며 태그 이름 배열이 아닙니다. 키는 사용자 정의 최상위 필드와 이름이 중복될 수 없습니다.
예: web-example
가져오기 또는 입력 방법: 예를 들어 host는 외부 시스템의 해당 리소스 식별자에서 가져옵니다.
event.check_value float 선택적 부동 소수점/숫자이며 문자열로 전달하지 않습니다. 단위는 외부 감지에서 정의하며 Studio는 환산하지 않습니다.
예: 12.5
가져오기 또는 입력 방법: 외부의 실제 감지 수치에서 가져옵니다.
event.비즈니스 필드 string 선택적 사용자 정의 최상위 필드이며 값은 반드시 문자열이어야 합니다. biz_/ext_ 접두사를 권장하며, 키는 _/df_로 시작할 수 없고 dimension_tags 키 또는 이미 바인딩된 콜론 태그의 키와 중복될 수 없으며 예약 필드도 사용할 수 없습니다.
예: ticket-example
가져오기 또는 입력 방법: 예를 들어 biz_ticket은 외부 티켓 또는 요청 식별자에서 가져옵니다.
extraData.사용자 정의 키 any 동적 JSON 값이며 대상 이벤트 데이터 프로토콜을 따릅니다.
예: healthcheck
가져오기 또는 입력 방법: 통합 측의 실제 메타 정보에 따라 정의합니다.
event json Y 필수 JSON 객체이며 이벤트 배열이 아닙니다. status는 조건부 필수입니다. 여기서는 이미 존재하는 외부 감지 결과만 수신하며 임계값 조회를 수행하지 않습니다.
null 허용: False
예: {"date": 1785427200, "status": "warning", "title": "生产服务异常", "message": "健康检查返回错误。", "dimension_tags": {"host": "web-example", "service": "production"}, "check_value": 12.5, "biz_ticket": "ticket-example"}
가져오기 또는 입력 방법: 비즈니스 시스템/알림 플랫폼의 실제 감지 결과에서 하나의 이벤트 객체를 구성합니다.
extraData json 선택적 JSON 객체로 기본값은 {}이며, 다운스트림 이벤트의 df_meta.extra_data로 사용됩니다. event 최상위 필드를 대체하지 않습니다. 통일된 필수 하위 키가 없으며 자격 증명을 넣지 마십시오.
null 허용: False
예: {"source_system": "healthcheck", "request_id": "request-example"}
가져오기 또는 입력 방법: 외부 연동에서 보조 식별 필드를 가져옵니다. 예: 소스 시스템 및 외부 요청 ID.

매개변수 추가 설명

매개변수 설명:

body 요청 매개변수 본문 구조 설명

매개변수명 매개변수 유형 필수 여부 매개변수 설명
event json 예 이벤트 데이터
extraData json 아니요 추가 데이터로 최종적으로 이벤트의 df_meta.extra_data 필드에 추가됩니다. key:value 형식이면 됩니다.

event 요청 매개변수 본문 구조 설명

매개변수명 매개변수 유형 필수 여부 매개변수 설명
date int 아니요 이벤트 시간(단위: 초)
status string 예 이벤트 상태, 선택 가능: fatal, critical, error, warning, info, ok
title string 아니요 이벤트 제목
message string 아니요 이벤트 내용
dimension_tags json 아니요 디멘션 태그, 예:
check_value float 아니요 검사 값
사용자 정의 필드 str 아니요 2024-09-04 사용자 정의 필드로, 이벤트 최상위 필드로 사용되며 제한 조건을 충족해야 합니다.

event.{사용자 정의 필드} 제한 조건 설명

동일한 이름의 필드가 서로 다른 유형으로 보고되어 이후 문제가 발생하는 것을 방지하기 위해 사용자 정의 필드는 다음 제한 조건을 충족해야 합니다:

  1. 필드 값은 문자열 유형이어야 합니다(예: "abc", "123").
  2. 필드 이름은 밑줄 _ 또는 df_로 시작할 수 없습니다.
  3. 필드 이름은 dimension_tags에서 분해된 필드 이름, labels에서 분해된 필드 이름과 중복될 수 없습니다.
  4. 필드 이름은 다음 예약 필드를 사용할 수 없습니다(사용자 정의 필드는 모두 ext_xxx, biz_xxx 등과 같이 직접 정의한 접두사로 시작하여 구분하는 것을 권장합니다):
    • date
    • status
    • source
    • title
    • message
    • dimension_tags
    • check_value
    • time
    • time_us
    • timestamp
    • workspace_uuid
    • workspace_name
    • extra_data
    • create_time

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/push-events/SECRET-PLACEHOLDER/datakit-push' \
  -H 'Content-Type: application/json' \
  --data-raw '{"event":{"date":1785427200,"status":"warning","title":"生产服务异常","message":"健康检查返回错误。","dimension_tags":{"host":"web-example","service":"production"},"check_value":12.5,"biz_ticket":"ticket-example"},"extraData":{"source_system":"healthcheck","request_id":"request-example"}}'

응답

HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content object 또는 기타 JSON 다운스트림 함수 결과를 그대로 감쌉니다. 아래는 기존의 일반적인 응답 필드이며 버전에 따라 필드가 생략될 수 있습니다.
content.data JSON 다운스트림 비즈니스 결과로 일반적으로 {}입니다. 이벤트 ID가 고정적으로 포함되지는 않습니다.
content.error integer 또는 string 다운스트림 비즈니스 결과 코드입니다. 예: 200이며 Studio의 HTTP 상태가 아닙니다.
content.message string 다운스트림 비즈니스 메시지입니다.
content.ok boolean 다운스트림 함수 결과 표시입니다. 명시적 false는 일반적으로 SDK에서 ft.OuterFuncFailed로 변환됩니다.
content.reqCost number 다운스트림 원본 소요 시간 통계 값입니다. Studio는 단위를 정규화하지 않으며 생략될 수 있습니다.
content.reqTime string 다운스트림 요청 시간입니다. 일반적으로 ISO8601 UTC 문자열이며 생략될 수 있습니다.
content.respTime string 다운스트림 응답 시간입니다. 일반적으로 ISO8601 UTC 문자열이며 생략될 수 있습니다.
content.traceId string 다운스트림 실행 추적 식별자로, 최상위 Studio traceId와 다를 수 있습니다.
content.declaration object 비어 있지 않은 객체에만 공통 선언이 추가되며 다른 응답 형태에서는 생략될 수 있습니다.
{
  "code": 200,
  "content": {
    "data": {},
    "error": 200,
    "message": "",
    "ok": true,
    "reqCost": 458,
    "reqTime": "2026-07-30T16:00:00.000Z",
    "respTime": "2026-07-30T16:00:00.458Z",
    "traceId": "FUNC-TRACE-EXAMPLE",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

이 Webhook 엔드포인트는 DF-API-KEY 인증을 수행하지 않습니다. API Key 누락/권한 오류는 이 페이지의 주요 연동 경로로 간주해서는 안 됩니다. 이벤트 검증, 규칙/워크스페이스 상태 및 다운스트림 비즈니스 오류는 이 페이지에서 확인하십시오. 슬래시를 포함한 subUri는 라우트와 일치할 수 없으며, 바로 404가 반환될 수 있고 통일된 JSON 오류 래퍼를 보장하지 않습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 매개변수 파싱 실패 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정하십시오.
400 ft.JsonFormatError JSON Body 최상위가 객체가 아님(예: 배열/문자열) 일부 json 파일 형식 오류 예시에 따라 JSON 객체를 제출해야 하며 checkers 또는 event 배열을 직접 제출할 수 없습니다.
400 ft.ParamsValidateError event 객체 내 status 누락/유효하지 않음, date/check_value/title 등 고정 하위 필드 유형 불일치 매개변수 검증 실패: {} 이 페이지의 단일 이벤트 객체 및 필드 유형에 따라 제출하십시오.
404 ft.NotFoundRuleInspector secret에 대응하는 삭제되지 않은 규칙이 없거나 소속 워크스페이스를 사용할 수 없음 지정된 규칙/검사기를 찾을 수 없음 이미 생성한 외부 이벤트 모니터 상세 정보에서 Webhook 주소를 다시 가져오고 API Key를 secret으로 사용하지 마십시오.
403 ft.WorkspaceIsLocked 대상 워크스페이스가 잠겨 있거나 단기 잠금 캐시가 아직 유효함 워크스페이스가 잠겨 있어 작업할 수 없습니다 관리자가 잠금 해제 상태를 확인하고, 캐시가 최대 약 10분 유지된 후 다시 시도하십시오.
406 ft.OuterEventCheckerWebhookSubUriNotValid 경로 subUri가 해당 규칙에 저장된 값과 다름 외부 이벤트 모니터의 webhook 주소가 유효하지 않습니다. 주소가 올바른지 확인하십시오 신뢰할 수 있는 상세 정보의 전체 Webhook 접미사에 따라 호출하고 대소문자와 경로 세그먼트에 주의하십시오.
406 ft.OuterEventCheckerNotAvailable 규칙이 현재 status=0이 아님(예: 비활성화됨) 외부 이벤트 모니터가 비활성화되었거나 삭제되었습니다 비즈니스에서 허용됨을 확인한 후 권한이 있는 사용자가 활성화한 뒤 다시 보고하십시오. 규칙 삭제 시 일반적으로 먼저 존재하지 않음이 반환됩니다.
404 ft.MonitorNotFound 규칙과 연결된 그룹이 존재하지 않거나 삭제됨 규칙 그룹을 찾을 수 없음 관리자가 과거 규칙 그룹 연결을 확인한 후 수정하십시오.
400 ft.DimensionTagsStartswithError 디멘션 키가 _ 또는 df_로 시작함 dimension_tags key는 df_, _로 시작할 수 없습니다 정상적인 비즈니스 디멘션 키로 변경하십시오.
400 ft.CustomEventFieldValueTypeError 사용자 정의 최상위 필드 값이 문자열이 아님 사용자 정의 필드 값은 문자열이어야 합니다 약속된 문자열로 변환하고 숫자 검사 값은 check_value에 넣으십시오.
400 ft.CustomEventFieldStartswithError 사용자 정의 최상위 키가 _ 또는 df_로 시작함 사용자 정의 필드는 df_, _로 시작할 수 없습니다 biz_/ext_ 비즈니스 접두사를 사용하십시오.
400 ft.CustomEventFieldWithDimensionTagsNotAllowed 사용자 정의 최상위 키가 dimension_tags 키와 같음 사용자 정의 필드 이름은 dimension_tags의 key를 사용할 수 없습니다 한 위치만 유지하거나 비즈니스 필드 이름을 변경하십시오.
400 ft.CustomEventFieldLabelKeyNotAllowed 사용자 정의 필드가 규칙에 바인딩된 key:value 태그의 key와 중복됨 사용자 정의 필드 이름은 해당 모니터의 태그(key:value) 중 key를 사용할 수 없습니다 바인딩된 태그를 확인하고 비즈니스 필드 이름을 변경하십시오.
400 ft.CustomEventFieldNotAllowed 사용자 정의 키가 예약 필드 source/time/time_us/timestamp/workspace_uuid/workspace_name/extra_data/create_time을 사용함 사용자 정의 필드 이름은 예약 필드를 사용할 수 없습니다 비즈니스 접두사를 사용하고 고정 필드는 이 페이지에 규정된 위치에 제출하십시오.
400 ft.OuterFuncFailed 이벤트 처리 함수가 ok=false 또는 JSON이 아닌 실패 결과를 반환함 외부 함수 호출 실패 오류 message와 traceId를 기반으로 다운스트림 처리를 파악하고, 이미 수신되었는지 확인한 후 재시도하십시오.
500 ft.InternalServerError 다운스트림 타임아웃/연결/유효하지 않은 JSON 등 포착되지 않은 예외, 캐시/스토리지 또는 응답 처리 실패 내부 오류 먼저 외부 요청 식별자로 이벤트가 이미 생성되었는지 조회하여 무작정 재전송으로 인한 중복을 피하고 traceId를 제공하십시오.

문서 평가

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