콘텐츠로 이동

가져오기



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는 전역 태그 템플릿을 개별적으로 가져오는 데 사용됩니다.

호출 흐름

  1. tags 배열을 준비하며, 각 요소는 태그 템플릿을 나타냅니다.
  2. repeatTagNameOp를 통해 동일한 이름의 태그를 만났을 때의 처리 정책을 지정합니다.
  3. 정책이 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를 제공합니다.

문서 평가

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