가져오기¶
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를 제공합니다. |