가져오기¶
POST /api/v1/tag/import
개요¶
이름 기준으로 태그를 일괄 생성하거나 덮어쓰며, 스코프 영향을 사전 검사하고 항목별로 제출합니다.
호출 전 및 사용 단계¶
먼저 check로 중복 이름을 검사하고, 덮어써야 할 때는 recover를 사용합니다. 전체 배치는 먼저 템플릿/동일 배치 내 중복 이름, 기존 중복 및 scope 영향을 검증합니다. recover에서 참조/모니터링 구성을 제거하는 변경이 있지만 유효한 가져오기 자격 증명이 없으면 requiresConfirmation=true 및 scopePreviews를 성공적으로 반환하며, 전체 배치는 아직 기록되지 않습니다. 확인 후 tagUUID별로 scopePreviewTokens를 구성하고, 완전히 동일한 가져오기 템플릿으로 재시도합니다. token이 만료되거나 영향이 변경되면 새 미리보기를 반환하며, 이를 완료된 것으로 간주하지 않습니다. 독립적인 scope_preview의 자격 증명에는 전체 가져오기 지문이 없으므로 이 분기의 자격 증명을 직접 대체할 수 없습니다.
사전 검사가 통과하면 각 항목을 독립적으로 제출하며, 일부 실패가 있어도 이미 성공한 태그를 롤백하지 않습니다. 실패 항목 이름은 failedNames에서 확인하고, traceId와 함께 조사한 후 대상별로 재시도합니다. skip은 successCount 또는 failCount에 포함되지 않으므로 두 값의 합이 입력 수보다 작을 수 있습니다. recover에서 description/colour/scope를 생략하면 빈 문자열/default/all로 덮어쓰므로, 이전 템플릿을 가져올 때 특히 scope의 기본값 all이 적용 범위를 확대할 수 있음에 주의해야 합니다. 신서틱 테스트 동기화 실패는 pendingDialingTaskUUIDs로 별도 반환되며, 이미 제출된 태그는 여전히 성공으로 집계됩니다. 태그 정의만 가져오며 리소스 연결 및 권한 구성은 복원하지 않습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| scopePreviewTokens.태그UUID | string | 하나의 태그에 대한 가져오기 확인 자격 증명입니다. 예시: IMPORT-PREVIEW-TOKEN가져오기 또는 입력 방법: 이번 scopePreviews에서 해당 tagUUID의 previewToken입니다. |
|
| tags[*].scope[*] | string | 배열 멤버이며 all과 구체적인 값을 혼합하지 않습니다. 예시: monitor가져오기 또는 입력 방법: 상위 열거형에서 단일 스코프를 선택합니다. |
|
| repeatTagNameOp | string | 선택 사항이며 기본값은 check입니다. check는 중복 이름을 만나면 repeat_name을 성공적으로 반환하고 전체 배치를 쓰지 않습니다. skip은 기존 항목을 변경하지 않습니다. recover는 템플릿에 따라 기존 이름에 해당하는 description/colour/scope를 전체적으로 다시 채우며, 누락 시 각각 빈 문자열/default/all입니다.null 허용: False 선택 가능한 값: ['check', 'skip', 'recover'] 예시: check가져오기 또는 입력 방법: check는 먼저 중복을 확인하고, skip은 기존 항목을 건너뛰며, recover는 기존 항목을 덮어씁니다. |
|
| scopePreviewTokens | object | 선택적 매핑이며 값의 최대 길이는 128입니다. 전체 정규화된 가져오기 파일과 현재 ID/영향 지문에 바인딩되며 600초 동안 유효합니다. 독립적인 scope_preview의 token을 가져오기 token 대신 사용하지 마십시오. 확인 후 재시도할 때는 tags 내용/순서 및 정책을 완전히 동일하게 유지하십시오.null 허용: False 예시: {"tag_example": "IMPORT-PREVIEW-TOKEN"}가져오기 또는 입력 방법: 이 API의 requiresConfirmation 분기에서 scopePreviews[]의 각 항목에서 tagUUID→previewToken을 가져옵니다. |
|
| tags | array | Y | 필수이며 비어 있지 않은 객체 배열입니다. 각 항목의 필드는 선언과 일치해야 하며, name은 trim 후 검사하고 전체에서 동일한 이름(대소문자 구분)이면 즉시 오류를 반환합니다.null 허용: False 예시: [{"name": "production", "description": "生产资源统一标记。", "colour": "default", "scope": ["scene", "monitor"]}]가져오기 또는 입력 방법: export 응답의 content에서 배열을 가져오고 각 항목의 declaration을 제거합니다. |
| tags[*] | object | 리소스 참조/UUID/권한 필드는 허용하지 않으며, 내보내기 통합 래퍼를 그대로 제출할 수 없습니다. 예시: {"name": "production", "description": "生产资源统一标记。", "colour": "default", "scope": ["scene", "monitor"]}가져오기 또는 입력 방법: 단일 {name,description,colour,scope} 템플릿입니다. |
|
| tags[*].colour | string | 선택 사항이며 기본값은 default입니다. recover는 원래 색상을 대체합니다. 50 카운트 단위 이하를 권장합니다. null 허용: False 예시: default가져오기 또는 입력 방법: 목록의 기존 colour를沿用하거나 기본값 default를 사용할 수 있습니다. |
|
| tags[*].description | string | 선택 사항이며 기본값은 빈 문자열입니다. recover는 원래 설명을 비웁니다. 100 카운트 단위 이하를 권장합니다. null 허용: False 예시: 生产资源统一标记。가져오기 또는 입력 방법: 비즈니스 담당자가 해당 태그의 용도를 설명합니다. |
|
| tags[*].name | string | Y | 필수이며 비어 있지 않은 이름입니다. trim 후 대소문자 구분 중복 검사에 사용됩니다. 가져오기 선언에는 생성 페이지의 길이 상한이 없지만, 고객 인터페이스와의 호환성을 위해 50 카운트 단위 이하를 권장합니다. null 허용: False 예시: production가져오기 또는 입력 방법: 비즈니스에서 사용자 정의한 태그 이름이며, 먼저 태그 목록에서 사용 중인 이름을 확인합니다. |
| tags[*].scope | any | 비어 있지 않은 스코프 배열이며, 열거형은 all 전역, scene 시나리오, monitor 모니터링, dialing 신서틱 테스트, security 보안, infrastructure 인프라, catalog 통합 카탈로그입니다. 이전 단일 값 문자열과 호환됩니다. all은 다른 값과 혼합할 수 없습니다. 중복 값은 제거되며 고정된 열거 순서로 반환됩니다. []/null/알 수 없는 값은 허용하지 않습니다. 추가/가져오기 시 생략하면 기본값은 ["all"]이며, 수정 시 생략하면 이전 값을 유지합니다. scope는 태그 적용 범위만 제한하며 리소스 권한을 부여하지 않습니다. 인프라/통합 카탈로그의 이름 바인딩은 여기서 엔터티 참조를 정리하더라도 변경되지 않습니다. null 허용: False 예시: ["scene", "monitor"]가져오기 또는 입력 방법: 태그를 바인딩할 리소스의 비즈니스 유형에 따라 필요에 맞게 선택합니다. |
파라미터 추가 설명¶
이 API는 전역 태그 템플릿을 개별적으로 가져오는 데 사용됩니다.
호출 흐름
tags배열을 준비하며, 각 요소는 태그 템플릿을 나타냅니다.repeatTagNameOp를 통해 동일한 이름의 태그를 만났을 때의 처리 정책을 지정합니다.- 정책이
check이고 동일한 이름의 태그가 있으면 API는repeat_name을 바로 반환하고 저장을 수행하지 않습니다.
repeatTagNameOp 설명
| 값 | 설명 |
|---|---|
| check | 중복만 검사하며, 동일한 이름의 태그가 있으면 repeat_name을 반환합니다. |
| skip | 이미 존재하는 동일한 이름의 태그를 건너뛰고 존재하지 않는 태그만 가져옵니다. |
| recover | 대상 워크스페이스에 동일한 이름의 태그가 있으면 해당 description과 colour를 덮어씁니다. |
템플릿 필드
| 필드 | type | 필수 | 설명 |
|---|---|---|---|
| name | string | 예 | 태그 이름 |
| description | string | 아니요 | 태그 설명 |
| colour | string | 아니요 | 태그 색상 |
| scope | string | 아니요 | 단일 스코프이며 이전 파일에서는 기본값이 all입니다. |
반환 설명
- 가져오기 실행이 성공하면
successCount,failCount를 반환합니다. - 일부 객체 실행이 실패하면 반환에
failedNames가 추가로 포함됩니다. check모드에서 중복이 발견되면repeat_name을 반환합니다.- 범위를 덮어쓸 때 영향을 받는 리소스가 있으면 먼저
requiresConfirmation과scopePreviews를 반환하며, 확인 후scopePreviewTokens를 포함해 원본 파일을 다시 전송합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/tag/import' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"repeatTagNameOp":"check","tags":[{"name":"production","description":"生产资源统一标记。","colour":"default","scope":["scene","monitor"]}]}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.successCount | integer | 이번 배치에서 항목별로 제출에 성공한 수이며 skip으로 건너뛴 항목은 포함하지 않습니다. |
| content.failCount | integer | 항목별 예외로 실패한 수이며 skip은 포함하지 않습니다. |
| content.failedNames | array<string> |
실패가 있을 때 나타나는 이름이며, 항목별 오류 코드는 반환되지 않습니다. |
| content.failedNames[] | string | 단일 실패 이름입니다. |
| content.pendingDialingTaskUUIDs | array<string> |
태그는 제출되었지만 신서틱 테스트 배포에 실패한 작업 집합이며 생략할 수 있습니다. |
| content.pendingDialingTaskUUIDs[] | string | 확인이 필요한 작업 UUID입니다. |
| content.repeat_name | array<string> |
check 적중 시 통계 대신 반환되며 전체 배치는 기록되지 않았습니다. |
| content.repeat_name[] | string | 동일한 이름의 태그 이름입니다. |
| content.requiresConfirmation | boolean | 사전 검사에 확인이 필요하면 true이며 통계를 대신하고, 이번 전체 배치는 기록되지 않았습니다. |
| content.scopePreviews | array<object> |
scope 변경 확인이 필요한 태그 미리보기입니다. |
| content.scopePreviews[].tagUUID | string | 대상 태그 UUID입니다. |
| content.scopePreviews[].oldScope | array<string> |
현재 스코프의 정규화된 배열입니다. |
| content.scopePreviews[].oldScope[] | string | 단일 이전 scope입니다. |
| content.scopePreviews[].newScope | array<string> |
대상 스코프의 정규화된 배열입니다. |
| content.scopePreviews[].newScope[] | string | 단일 새 scope입니다. |
| content.scopePreviews[].requiresConfirmation | boolean | 정리될 엔터티 참조 또는 모니터링 구성이 있는지 여부입니다. 공개 modify는 여전히 token을 생략하고 직접 실행할 수 있습니다. |
| content.scopePreviews[].affectedResourceCount | integer | 비즈니스 리소스 기준으로 중복 제거한 총수이며 관계 수와 같지 않습니다. SLO 내부 규칙은 소속 SLO로 병합됩니다. |
| content.scopePreviews[].affectedRelationCount | integer | 정리될 것으로 예상되는 엔터티 참조 수입니다. |
| content.scopePreviews[].affectedConfigCount | integer | 정리될 것으로 예상되는 incidentsTags 규칙 구성 수입니다. |
| content.scopePreviews[].orphanRelationCount | integer | 참조는 존재하지만 대응하는 유효 리소스가 없는 관계 수이며, 관계 영향에도 포함됩니다. |
| content.scopePreviews[].summary | array<object> |
리소스 유형별로 집계한 중복 제거 리소스 수입니다. |
| content.scopePreviews[].summary[].resourceType | string | dashboard/viewer/service/checker/smartMonitor/aiMonitor/incident/dialing/security/slo 등의 실제 비즈니스 유형입니다. |
| content.scopePreviews[].summary[].count | integer | 해당 유형의 리소스 수입니다. |
| content.scopePreviews[].data | array<object> |
이 페이지에서 영향을 받는 리소스 요약입니다. |
| content.scopePreviews[].data[].resourceType | string | 비즈니스 리소스 카테고리입니다. |
| content.scopePreviews[].data[].resourceUUID | string | 리소스 UUID입니다. |
| content.scopePreviews[].data[].name | string | 리소스 표시 이름이며, 이름이 없으면 UUID로 대체합니다. |
| content.scopePreviews[].data[].scope | string | 해당 리소스가 속한 scope입니다. |
| content.scopePreviews[].previewToken | string | 600초 동안 유효한 미리보기 자격 증명이며 이번 ID/워크스페이스/태그/대상 scope/영향 지문에 바인딩됩니다. 인증 Token이 아닙니다. |
| content.scopePreviews[].pageInfo | object | 미리보기 상세는 기본적으로 첫 페이지로 페이지네이션되며 공통 최상위로 올라가지 않습니다. |
| content.scopePreviews[].pageInfo.pageIndex | integer | 기본값은 1입니다. |
| content.scopePreviews[].pageInfo.pageSize | integer | 기본값은 50입니다. |
| content.scopePreviews[].pageInfo.totalCount | integer | 해당 태그로 중복 제거된 영향 리소스 총수입니다. |
| content.declaration | object | 공통 선언입니다. |
{
"code": 200,
"content": {
"successCount": 1,
"failCount": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
check에서 중복 이름이 발견된 경우:
{
"code": 200,
"content": {
"repeat_name": [
"production"
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
recover에서 확인이 필요할 때:
{
"code": 200,
"content": {
"requiresConfirmation": true,
"scopePreviews": [
{
"tagUUID": "tag_example",
"oldScope": [
"all"
],
"newScope": [
"scene"
],
"requiresConfirmation": true,
"affectedResourceCount": 1,
"affectedRelationCount": 1,
"affectedConfigCount": 0,
"orphanRelationCount": 0,
"summary": [
{
"resourceType": "checker",
"count": 1
}
],
"data": [
{
"resourceType": "checker",
"resourceUUID": "rul_example",
"name": "生产监控器",
"scope": "monitor"
}
],
"previewToken": "PREVIEW-TOKEN",
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"totalCount": 1
}
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.ErrorFieldCheck | 특정 항목의 trim 후 name이 비어 있음 | {} 필드 검증 실패 | 비어 있지 않은 이름을 제공합니다. |
| 400 | ft.FileObjectNameRepeat | 동일 배치에서 trim 후 대소문자가 같은 이름이 존재함 | 파일에 동일한 이름의 객체가 존재함 | 먼저 입력 이름의 중복을 제거합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 태그/권한 구조, 캐시 또는 응답 형식화 실패 | 내부 오류 | 요청을 확인한 후 태그의 현재 상태를 다시 읽습니다. 쓰기가 이미 커밋되었을 수 있으므로 무작정 반복하지 말고, 계속 실패하면 traceId를 제공합니다. |