콘텐츠로 이동

가져오기



POST /api/v1/pipeline/import

개요

Pipeline 템플릿을 일괄 생성하고 기본값 교체 확인과 구문 검증을 처리합니다.

호출 전 및 사용 단계

내보낸 pipelines 배열을 사용하고 대상 워크스페이스 기준으로 소스를 확인합니다. 동일 카테고리 이름이 이미 존재하거나 동일 카테고리/type의 정확한 source와 충돌하는 항목은 바로 건너뛰며 덮어쓰지 않습니다. fail_count에는 건너뛴 수가 포함되므로 모두 오류로 이해해서는 안 됩니다. * 또는 ?가 포함된 소스는 정확한 충돌 비교에 참여하지 않습니다. 동일 배치의 동일 카테고리 동일 이름 후보는 컴파일 전 검사에서 거부됩니다. 동일 배치에서 동일 카테고리/type의 여러 항목에 asDefault=1을 지정하지 마세요.

confirm이 반환되면 전체 배치가 기록되지 않으며, 확인 후 isForce=true로 재시도합니다. 강제 기본값 교체는 모든 후보의 구문 검증이 통과된 후로 지연됩니다. 모든 후보 스크립트는 공통 의존성 뷰에서 컴파일되며 뒤에 있는 후보를 참조할 수 있습니다. 구문 검증에 실패하면 전체 배치가 제출되지 않습니다. 현재 가져오기는 isDisable을 적용하지 않으므로 성공적으로 생성된 항목은 기본적으로 활성화됩니다. 이전 버전 번호는 보존하지 않습니다. rum/llm 가져오기는 템플릿 source 관계를 따르며, 단일 생성의 extend 데카르트 재구성을 사용하지 않습니다. 동일 버전의 내보낸 템플릿을 직접 사용하고 내부 연관 관계를 직접 구성하지 않는 것을 권장합니다.

examples의 각 항목은 개별 JSON 값을 인코딩하며, testData는 이전 형식으로 전체 배열을 인코딩합니다. 현재 가져오기는 공개 add의 샘플 배열/항목별 20KiB 검증을 완전히 재사용하지 않으므로 호출자는 여전히 샘플의 크기와 유형을 제어해야 합니다. 내부 템플릿 필드는 항목별로 강제되지 않으며, 잘못된 형식은 500을 반환할 수 있습니다.

저장 시 구문을 동기 검증하고 구성/버전을 업데이트합니다. 실제 수집 또는 중앙 처리의 적용 여부는 후속 구성 조회 및 데이터 흐름에 따라 달라집니다. 과거 데이터를 재실행하지 않으며 파싱 샘플 결과를 반환하지 않습니다. 수정 전에 상세 정보를 백업하고, 오류/시간 초과 후에는 현재 버전을 먼저 다시 읽은 뒤 재시도하세요.

요청 헤더

파라미터 이름 타입 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터 이름 타입 필수 설명
pipelines[*] json 새 템플릿을 생성하며 이미 존재하는 동일 이름 또는 소스를 덮어쓰지 않습니다. 나열되지 않은 필드에 의존해서는 안 됩니다.
예: {"name": "production_parser", "type": "local", "category": "logging", "asDefault": 0, "enableByLogBackup": 0, "source": ["nginx"], "isDisable": false, "content": "YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==", "examples": [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}], "dataType": "json", "extend": {"loggingIndex": "default"}}
가져오기 또는 입력 방법: 내보낸 템플릿을 기준으로 대상 이름과 소스를 교체합니다.
pipelines[*].name string 필수이며 최대 256 계산 단위(ASCII/반각 가타카나 1, 기타 문자 2)입니다. 영문자, 숫자, 밑줄, 중국어 U+4e00..9fa5 및 하이픈을 허용합니다. 비어 있지 않게 지정하는 것을 권장합니다. 동일 category에서는 local/central이 다르거나 기존 항목이 비활성화되어 있어도 중복을 허용하지 않습니다. 입력 로그의 source가 아닙니다.
예: production_parser
가져오기 또는 입력 방법: 비즈니스에서 사용자 정의한 파일 이름으로, 먼저 Pipeline 목록에서 동일 카테고리의 삭제되지 않은 이름을 확인합니다.
pipelines[*].type string 필수이며 local/central입니다. 신서틱 테스트 dialtesting의 생성/수정은 central만 가능합니다. 워크스페이스 버전에 따라 central이 제한될 수 있습니다. 수정하면 기존 실행 유형이 교체됩니다.
예: local
가져오기 또는 입력 방법: 로컬 수집기에서 처리하면 local, 플랫폼 중앙에서 처리하면 central을 선택하고 실제 데이터 진입점을 확인합니다.
pipelines[*].category string 필수이며 lineage/logging/object/custom_object/network/tracing/rum/llm/agent_monitor/security/keyevent/metric/profiling/dialtesting/cloud_billing입니다. billing은 이전 버전 호환 값입니다. 수정 시 카테고리를 변경할 수 있으며 스크립트, source 및 extend를 함께 확인해야 합니다.
예: logging
가져오기 또는 입력 방법: 대상 데이터 도메인 및 수집 구성에 따라 선택합니다.
pipelines[*].source array 선택 사항이며 기본값은 []입니다. 수정 시 생략하면 모든 소스 관계가 제거됩니다. * 또는 ?가 포함된 소스는 정확한 유일성 충돌 검사에 참여하지 않으며, 일치하는 모든 항목의 런타임 동작이 보장되지는 않습니다. 일반 정확한 소스는 동일 category/type 내에서 다른 삭제되지 않은 Pipeline이 점유할 수 없습니다. rum/llm 생성/수정에서는 이 배열을 무시하고 extend.appID와 measurement를 사용합니다.
예: ["nginx"]
가져오기 또는 입력 방법: 해당 수집 데이터의 source 또는 소스 선택기에서 값을 가져오며 Pipeline 이름이 아닙니다. 로그는 실제 로그 source를 참고할 수 있습니다.
pipelines[*].source[*] string 비어 있지 않은 문자열을 권장하며 배열은 항목별로 엄격하게 검증되지 않습니다. 관련 없는 데이터 도메인을 섞지 마세요.
예: nginx
가져오기 또는 입력 방법: 단일 실제 소스 식별자 또는 수집 측에서 지원하는 와일드카드 패턴입니다.
pipelines[*].content string 필수 base64 문자열이며 생성 시 디코딩 결과가 비어 있지 않아야 합니다. 디코딩된 스크립트 전체는 UI 문자 수 ≤1048576 및 UTF8 바이트 ≤1048576을 동시에 충족해야 합니다. BMP 비ASCII는 2, 보조 문자는 4로 계산합니다. 둘 중 하나라도 초과하면 ft.ContextExceedLimit입니다. 저장 시 샘플 없이 동기 컴파일하고 동일 카테고리의 활성화된 스크립트 참조를 검사합니다. 성공이 실제 데이터 디버깅 통과 또는 적용 완료를 의미하지는 않습니다.
예: YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==
가져오기 또는 입력 방법: 먼저 UTF8 Pipeline 스크립트를 작성한 다음 표준 base64로 인코딩합니다. 예시의 디코딩 결과는 add_key("env", "production")입니다.
pipelines[*].dataType string 선택 사항이며 기본값은 line_protocol입니다. line_protocol/json/message를 지원합니다. 수정 시 생략하면 line_protocol로 복원됩니다. category가 아닙니다. 빈 문자열이 호환된다고 선언되어 있더라도 지원되는 값을 명확히 선택해야 합니다.
예: json
가져오기 또는 입력 방법: testData 샘플과 스크립트 입력에 따라 선택합니다.
pipelines[*].asDefault integer 선택 사항이며 기본값은 0입니다. 0/1만 지정하는 것을 권장합니다. 이미 기본값이 있고 isForce가 없으면 HTTP 200으로 confirm 배열을 반환하며, 이번 대상 구성은 저장되지 않으므로 생성/수정 성공으로 간주하지 않습니다.
예: 0
가져오기 또는 입력 방법: 동일 category/type의 폴백 규칙으로 사용하려면 1, 아니면 0입니다.
pipelines[*].enableByLogBackup integer 선택 사항이며 기본값은 0입니다. 0/1을 권장합니다. 이 플래그를 저장한다고 해서 기존 전송 데이터가 자동으로 재실행되는 것은 보장되지 않습니다.
예: 0
가져오기 또는 입력 방법: 규칙이 전송 데이터를 처리해야 하면 1로 설정하고, 실제 데이터 전송 체인에서 지원 여부를 확인합니다.
pipelines[*].extend json 선택 사항이며 기본값은 {}입니다. 수정 시 전체를 교체하며 병합하지 않습니다. rum/llm은 appID×measurement 조합으로 소스 관계를 생성합니다. 알 수 없는 하위 필드는 공개 검증에서 거부됩니다.
예: {"loggingIndex": "default"}
가져오기 또는 입력 방법: 카테고리 및 기존 상세 정보에 따라 아래 선언 필드를 구성합니다.
pipelines[*].extend.appID array rum/llm에서는 measurement와 함께 비어 있지 않은 배열을 제공해야 합니다. 둘 다 비어 있으면 전용 소스가 없을 수 있습니다. appID는 있으나 measurement가 없으면 필수 파라미터 누락 오류가 발생합니다.
예: ["appid_example"]
가져오기 또는 입력 방법: 해당 RUM/LLM 애플리케이션 관리에서 실제 appId를 가져옵니다.
pipelines[*].extend.measurement array rum/llm에서는 appID와 데카르트 조합을 수행합니다. measurement는 있으나 appID가 없으면 필수 파라미터 누락 오류가 발생합니다. 저장 시 각 애플리케이션/measurement에 실제 데이터가 있는지는 검증하지 않습니다.
예: ["view"]
가져오기 또는 입력 방법: 해당 애플리케이션의 실제 데이터에 있는 measurement(예: RUM view/action 등)에서 가져오며 실제 카테고리에 맞게 입력합니다.
pipelines[*].extend.loggingIndex string 선택 사항인 로그 인덱스 응답 표시 필드입니다. 기본적으로 값을 채우지 않으며 수정 시 생략하면 extend와 함께 삭제됩니다. source 배열이 아닙니다.
예: default
가져오기 또는 입력 방법: 로그 인덱스 목록에서 적용 가능한 인덱스 식별자를 가져옵니다.
pipelines[*].extend.ifAiCreate boolean 선택 사항인 응답 표시 필드이며 AI 작업을 트리거하지 않습니다.
예: false
가져오기 또는 입력 방법: AI 지원으로 생성되었는지 기록합니다. 이 표시가 필요 없으면 생략할 수 있습니다.
pipelines[*].extend.aiTargetStructure string 선택 사항인 문자열이며 저장 및 응답 표시만 수행합니다. 이 API는 스크립트를 생성하지 않습니다.
예:
가져오기 또는 입력 방법: AI 생성 시의 대상 구조 설명이며 필요 없으면 생략할 수 있습니다.
pipelines[*].extend.exampleSource string 선택 사항인 응답 표시 필드이며 source 연관을 대체하지 않습니다.
예: nginx
가져오기 또는 입력 방법: 샘플 소스 표시 값이며 실제 source와 대응해야 합니다.
pipelines[*].extend.exampleType string 선택 사항인 응답 표시 문자열이며 서버에서 고정 열거형을 제공하지 않습니다.
예: custom
가져오기 또는 입력 방법: 샘플 유형 표시 값으로 클라이언트 비즈니스에서 정의합니다.
pipelines[*].extend.appID[*] string 비어 있지 않은 문자열을 권장합니다.
예: appid_example
가져오기 또는 입력 방법: 애플리케이션 구성에서 단일 appId를 가져옵니다.
pipelines[*].extend.measurement[*] string 비어 있지 않은 문자열을 권장합니다.
예: view
가져오기 또는 입력 방법: 실제 measurement 원본 이름입니다.
pipelines[*].isDisable boolean 내보내기 시의 원래 상태입니다. 현재 공개 import는 이 플래그를 적용하지 않으며 가져오기 후 기본적으로 활성화됩니다.
예: false
가져오기 또는 입력 방법: 내보낸 템플릿의 해당 필드에서 가져옵니다. 구성 의미는 이 페이지의 설명과 같습니다.
pipelines[*].examples array<object> 이전 testData보다 우선합니다. 객체/문자열의 유효한 JSON 인코딩을 제공하는 것을 권장합니다. 유효하지 않은 JSON의 디코딩된 내용은 원본 텍스트 대신 null로 저장될 수 있습니다.
예: [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}]
가져오기 또는 입력 방법: 각 샘플을 먼저 JSON 값으로 직렬화한 다음 UTF8 base64로 인코딩합니다.
pipelines[*].examples[*] json 비어 있지 않은 객체를 권장합니다.
예: {"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}
가져오기 또는 입력 방법: 단일 {data:base64} 객체입니다.
pipelines[*].examples[*].data string 유효한 JSON 값의 인코딩이며 전체 샘플 배열이 아닙니다. 생성 시 사용하는 testData의 인코딩 계층과 다릅니다.
예: eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ==
가져오기 또는 입력 방법: 예시는 단일 JSON 객체의 UTF8 base64입니다.
pipelines[*].testData string 선택 사항인 이전 형식입니다. examples가 있으면 우선합니다. 디코딩 시 None이 되는 것을 방지하려면 생략하지 말고 W10=을 사용하세요.
예: W10=
가져오기 또는 입력 방법: 이전 템플릿에 examples가 없을 때만 사용하며 전체 샘플 배열을 인코딩합니다.
isForce boolean 선택 사항이며 기본값은 false입니다. 기본값 충돌 확인에만 사용되며 구문, 소스, 이름, 버전 등의 검증을 건너뛸 수 없습니다. 강제 교체 시 기존 기본값을 비기본값으로 변경하고 해당 버전을 아카이브합니다.
null 허용: False
예: false
가져오기 또는 입력 방법: content.confirm을 받은 후 기존 기본 Pipeline 교체를 확인한 다음 true로 설정합니다.
pipelineType string Y 필수이며 logging/all입니다. logging은 비로그 항목을 건너뛰지만 일부 제한/확인 검사는 카테고리 건너뛰기 전에 수행됩니다.
선택 가능한 값: ['logging', 'all']
예: all
가져오기 또는 입력 방법: 여러 카테고리 가져오기를 관리하려면 all, 로그만 가져오려면 logging을 사용합니다.
pipelines array Y 필수 배열이며 빈 배열이면 성공과 함께 0 통계를 반환합니다. 각 항목은 템플릿 객체이며 내부에서 전체 필드 선언 검증을 수행하지 않습니다. 통합 응답을 그대로 전달하지 마세요.
null 허용: False
예: [{"name": "production_parser", "type": "local", "category": "logging", "asDefault": 0, "enableByLogBackup": 0, "source": ["nginx"], "isDisable": false, "content": "YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==", "examples": [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}], "dataType": "json", "extend": {"loggingIndex": "default"}}]
가져오기 또는 입력 방법: export 응답의 content.pipelines에서 배열을 가져옵니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/pipeline/import' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"pipelineType":"all","isForce":false,"pipelines":[{"name":"production_parser","type":"local","category":"logging","asDefault":0,"enableByLogBackup":0,"source":["nginx"],"isDisable":false,"content":"YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==","examples":[{"data":"eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}],"dataType":"json","extend":{"loggingIndex":"default"}}]}'

응답

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

필드 타입 설명
content.success_count integer 성공적으로 생성된 후보 수입니다.
content.fail_count integer 입력 수에서 성공 수를 뺀 값이며 건너뛴 항목을 포함합니다. 항목별 사유는 없습니다.
content.declaration object 공통 선언입니다.
content.confirm array<string> 기본값 충돌 시 일반 엔터티 대신 반환되며 교체 확인이 필요한 카테고리를 나열합니다. 이 분기에서는 이번 대상 구성이 저장되지 않습니다.
content.confirm[] string 단일 카테고리입니다.
content.pl_errors array<object> ft.PipelineSyntaxError 오류의 content에서만 반환되는 컴파일 오류 배열입니다.
content.pl_errors[].error string 컴파일 오류 설명입니다.
content.pl_errors[].pos_chain array<object> 참조/위치 체인입니다.
content.pl_errors[].pos_chain[].file string 파일 이름입니다.
content.pl_errors[].pos_chain[].ln integer 음수가 아닌 위치 인덱스로 컴파일러에서 정의합니다. 문제 해결 시 원래 값을 유지합니다.
content.pl_errors[].pos_chain[].col integer 음수가 아닌 위치 인덱스로 컴파일러에서 정의합니다. 문제 해결 시 원래 값을 유지합니다.
content.pl_errors[].pos_chain[].pos integer 음수가 아닌 위치 인덱스로 컴파일러에서 정의합니다. 문제 해결 시 원래 값을 유지합니다.
{
  "code": 200,
  "content": {
    "success_count": 1,
    "fail_count": 0,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

기본값 확인 대기:

{
  "code": 200,
  "content": {
    "confirm": [
      "logging"
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 파라미터 파싱 실패 파라미터 위치, 필드 이름, 타입 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
406 ft.InvalidBase64 스크립트/테스트 샘플이 디코딩 가능한 UTF8 base64가 아님. 생성 시 testData가 생략되어도 발생할 수 있음 유효하지 않은 base64 내용 content와 testData를 완전히 제공하고 먼저 UTF8로 인코딩한 뒤 base64로 인코딩합니다.
406 ft.ContextExceedLimit 스크립트가 UI 문자 수 또는 UTF8 바이트 1MiB를 초과하거나, add/modify 단일 테스트 샘플이 이전 길이 제한을 초과함 텍스트 내용 초과, {}자 제한 스크립트/단일 샘플을 줄이고 message에 표시된 단위를 확인합니다.
406 ft.PipelineSyntaxError 동기 샘플 없는 컴파일에서 스크립트 또는 참조 구문 오류가 반환됨 Pipeline 스크립트 구문 오류, 오류 위치를 확인하세요 content.pl_errors의 error 및 pos_chain에 따라 위치를 찾아 수정한 뒤 재시도합니다.
400 ft.PipelineNameExists 동일 배치의 동일 카테고리 후보 스크립트 이름이 중복됨 동일한 이름의 Pipeline이 이미 존재합니다 먼저 템플릿 이름을 중복 제거합니다.
403 ft.ForbiddenFreeEditionWorkspace 특정 후보의 type이 워크스페이스 버전과 맞지 않음 무료 플랜 워크스페이스는 이 기능을 지원하지 않습니다. 상용 플랜을 개통하면 제한을 해제할 수 있습니다 대상 실행 방식을 조정합니다.
403 ft.ForbiddenFreeWKSPCentralPipeline 무료/체험 워크스페이스에서 central을 가져옴 무료 플랜 워크스페이스는 중앙 pipeline 구성을 지원하지 않습니다 워크스페이스 버전의 지원 여부를 확인합니다.
500 ft.InternalServerError 동기 컴파일 서비스를 사용할 수 없음/시간 초과/형식 이상(내부 PipelineValidationUnavailable이 최종적으로 통합 래핑됨), 데이터베이스, 구조 오류 또는 제출 후 포맷팅 실패 내부 오류 나중에 재시도하기 전에 현재 구성과 버전을 먼저 읽어 저장 여부를 확인합니다. 계속 실패하면 traceId를 제공합니다.

문서 평가

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