콘텐츠로 이동

수정



POST /api/v1/service_manage/{service_uuid}/modify

개요

지정한 서비스 목록 구성을 수정합니다.

호출 전 및 사용 단계

API Key에는 서비스 관리 권한(trace.serviceManage)이 필요합니다. 먼저 서비스 목록 상세에서 현재 TOML을 내보내 편집 기반으로 삼고, 계속 사용할 리포지토리, 문서 및 연결 정보를 유지하세요. 전체 구성을 제출한 후 동일한 UUID로 다시 조회하여 확인합니다. 대상 UUID가 유효하지 않으면 내부 오류가 반환될 수 있으므로, 먼저 목록에서 대상을 확인하세요.

경로 매개변수

매개변수 이름 유형 필수 설명
service_uuid string Y 현재 워크스페이스의 서비스 목록 UUID이며 접두사는 sman_입니다.
null 허용: False
예시: sman_example
가져오기 또는 입력 방법: 서비스 목록의 content.data[].uuid에서 가져오며, 생성 응답의 content.uuid를 사용할 수도 있습니다.

요청 헤더

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

Body 요청 매개변수

매개변수 이름 유형 필수 설명
serviceCatelog string Y 서비스 목록 TOML 구성 텍스트입니다. 전체 JSON 이스케이프 예시는 요청 예시를 참조하세요. 최대 가중 길이는 65535이며, ASCII 문자와 반각 가타카나는 1로, 그 외 문자는 2로 계산합니다.
null 허용: False
$maxCustomLength: 65535
예시: "[Team]\nservice = \"checkout\"\ntype = \"web\"\nteam = \"team-commerce\"\ncolour = \"#40C9C9\"\n\n[[Team.oncall]]\nname = \"值班邮箱\"\ntype = \"email\"\nemails = [\"xxx@guance.com\"]\n\n[[Repos]]\nname = \"业务仓库\"\nlink = \"https://example.invalid/repos/checkout\"\nprovider = \"Git\"\n\n[[Docs]]\nname = \"操作手册\"\nlink = \"https://example.invalid/help/checkout\"\nprovider = \"Wiki\"\n\n[Related]\nAppId = \"\"\nTags = [\"team:commerce\"]\nDashboardUUIDs = []\n"
가져오기 또는 입력 방법: 서비스 목록 상세에서 originStr=1을 전달하여 원문을 가져오거나, 아래 필드 표에 따라 전체 TOML을 구성한 후 JSON 문자열로 전송합니다.

매개변수 추가 설명

serviceCatelog는 TOML 텍스트를 포함하는 JSON 문자열입니다. 아래 경로는 모두 파싱된 TOML 내용을 가리킵니다. 수정 시 전체 구성을 제출하며, 기존 Repos, Docs 또는 Related 연결을 생략하면 해당 구성 또는 태그가 교체되거나 제거됩니다.

TOML 필드 유형 입력 및 값 출처
Team TOML 테이블 호출 시 반드시 제공해야 하며, 서비스 기본 정보를 포함합니다.
Team.service string 비즈니스상 필수이며 비어 있지 않아야 합니다. 애플리케이션 성능 모니터링(APM)의 트레이스 기록에서 service 필드를 복사하거나, 서비스 목록을 미리 생성해야 하는 서비스 이름을 입력합니다. 데이터베이스 필드 길이인 256자를 초과하지 않는 것이 좋습니다.
Team.type string 생략할 수 있습니다. app, framework, cache, message_queue, custom, db, web 또는 aws_lambda 중 하나를 사용합니다. 생성 시 다른 값을 사용하면 기존 트레이스 데이터를 기준으로 추론하며, 일치하는 항목이 없으면 custom으로 설정됩니다. 수정 시 다른 값은 custom으로 바로 변환됩니다.
Team.colour string 생략할 수 있습니다. 유효한 색상은 #C43243, #DE5565, #D77D3D, #FDA82D, #FFD33B, #8934A4, #C75BC9, #F19AF2, #993C7E, #6454CB, #AC8AF0, #6C7AEB, #196AAB, #2EB2EE, #40C9C9, #1A9A82, #417C51, #49B566, #A7D650, #3F94DC입니다. 빈 값 또는 기타 색상은 서비스 이름을 기준으로 허용 범위 내의 색상을 생성합니다.
Team.team string 팀 이름이며, 팀 목록에서 name을 복사할 수 있습니다. 존재하지 않는 이름은 팀을 생성하므로, 기존 팀 이름을 명확히 입력하는 것이 좋습니다.
Team.oncall array<table> 연락처 배열이며, 생략하면 빈 배열이 됩니다. TOML에서는 여러 개의 [[Team.oncall]] 테이블을 사용할 수 있습니다.
Team.oncall[].name string 연락처 표시 이름(예: 온콜 이메일)입니다.
Team.oncall[].type string 각 항목에는 email, mobile 또는 slack을 입력합니다.
Team.oncall[].emails array<string> type=email인 경우 이메일 주소 배열을 입력합니다(예: ["xxx@guance.com"]).
Team.oncall[].mobiles array<string> type=mobile인 경우 전화번호 문자열 배열을 입력합니다.
Team.oncall[].slack string type=slack인 경우 Slack 채널 주소 또는 기존 구성 값을 입력합니다.
Repos array<table> 코드 리포지토리 배열이며, 생략하면 비어 있습니다. 각 항목은 name, link, provider로 구성됩니다.
Repos[].name string 리포지토리 표시 이름입니다.
Repos[].link string 실제 리포지토리 URL을 입력합니다.
Repos[].provider string 리포지토리 제공자 표시 이름입니다.
Docs array<table> 연결된 운영 문서 배열이며, 생략하면 비어 있습니다. 각 항목은 name, link, provider로 구성됩니다.
Docs[].name string 문서 표시 이름입니다.
Docs[].link string 고객이 액세스할 수 있는 운영 가이드 URL을 입력합니다.
Docs[].provider string 콘텐츠 제공자 표시 이름입니다.
Related TOML 테이블 호출 시 반드시 제공해야 합니다. 연결이 없더라도 [Related] 빈 테이블을 유지합니다.
Related.AppId string 실제 사용자 모니터링(RUM) 애플리케이션 ID이며, 대소문자는 AppId를 유지합니다. RUM 애플리케이션의 구성 또는 기록의 app_id에서 가져오며, 생략하거나 비워 둘 수 있습니다.
Related.DashboardUUIDs array<string> 내장 뷰 목록에서 content.data[].uuid를 가져오며, 현재 워크스페이스의 활성 내장 뷰만 사용합니다. 바인딩이 없으면 []를 입력합니다.
Related.Tags array<string> 시나리오 태그 이름 배열입니다. 상세 응답의 Related.Tags를 복사할 수 있으며, 빈 배열은 태그 연결을 비웁니다. 각 이름은 최대 128자입니다.

전체 구성 예시

[Team]
service = "checkout"
type = "web"
team = "team-commerce"
colour = "#40C9C9"

[[Team.oncall]]
name = "值班邮箱"
type = "email"
emails = ["xxx@guance.com"]

[[Repos]]
name = "业务仓库"
link = "https://example.invalid/repos/checkout"
provider = "Git"

[[Docs]]
name = "操作手册"
link = "https://example.invalid/help/checkout"
provider = "Wiki"

[Related]
AppId = ""
Tags = ["team:commerce"]
DashboardUUIDs = []

팀 검증에서는 팀이 먼저 생성 및 제출된 뒤 검증이 실패하더라도 해당 팀이 남아 있을 수 있습니다. 요청 시간 초과 또는 실패 후에는 먼저 현재 서비스와 팀을 조회하여 상태를 확인한 뒤 재시도 여부를 결정하세요.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/service_manage/sman_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"serviceCatelog":"[Team]\nservice = \"checkout\"\ntype = \"web\"\nteam = \"team-commerce\"\ncolour = \"#40C9C9\"\n\n[[Team.oncall]]\nname = \"值班邮箱\"\ntype = \"email\"\nemails = [\"xxx@guance.com\"]\n\n[[Repos]]\nname = \"业务仓库\"\nlink = \"https://example.invalid/repos/checkout\"\nprovider = \"Git\"\n\n[[Docs]]\nname = \"操作手册\"\nlink = \"https://example.invalid/help/checkout\"\nprovider = \"Wiki\"\n\n[Related]\nAppId = \"\"\nTags = [\"team:commerce\"]\nDashboardUUIDs = []\n"}'

응답

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

필드 유형 설명
content.uuid string 서비스 목록 UUID입니다.
content.service string 저장된 서비스 이름입니다.
content.type string 저장된 서비스 분류입니다.
content.declaration object 또는 null 워크스페이스 공통 선언입니다.
{
  "code": 200,
  "content": {
    "uuid": "sman_example",
    "service": "checkout",
    "type": "web",
    "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.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 요청 본문을 JSON 객체로 구성합니다.
400 ft.SetFormatError serviceCatelog를 TOML로 파싱할 수 없음 서비스 목록 toml 형식 파싱 실패 TOML 구문을 수정하고, JSON 내 줄바꿈과 큰따옴표가 올바르게 이스케이프되었는지 확인합니다.
400 ft.MissingCustomParameters Team이 존재하지만 service 필드가 누락됨 service 필드 누락 [Team]에 service 문자열을 제공합니다.
400 ft.ErrorFieldType TOML 내 서비스 유형, 색상, 팀 이름, 배열 또는 연락처 유형이 요구 사항에 맞지 않음 {} 필드 유형 오류 TOML 필드 표에 따라 오류 필드를 수정하고, 연락처 type은 email, mobile 또는 slack을 사용합니다.
406 ft.MissParamService Team.service가 빈 문자열임 필수 매개변수 누락, 서비스 이름 실제 서비스 이름을 입력합니다.
400 ft.ServiceNameRepeat 동일 워크스페이스에 일치하는 활성 서비스 목록이 이미 존재함 서비스 이름이 이미 존재함 먼저 목록을 조회하고, 생성 시 중복이면 해당 UUID로 수정하며, 수정 시 이름이 중복되면 다른 이름을 사용합니다.
400 ft.InvalidInnerDashboardUUID Related.DashboardUUIDs에 워크스페이스 내 존재하지 않거나 삭제되었거나 내장 뷰가 아닌 UUID가 포함됨 유효하지 않은 대시보드 UUID: {} 내장 뷰 목록에서 유효한 UUID를 다시 선택하고, 아직 연결하지 않을 경우 빈 배열을 전달합니다.
400 ft.TagScopeMismatch Related.Tags의 기존 동일 이름 태그가 시나리오 범위와 호환되지 않음 예: team:commerce: ['monitor'] -> scene 시나리오 또는 공통 범위의 태그를 선택하거나 다른 이름을 사용합니다.
406 ft.ExceedMaxCharacterLimit Related.Tags의 태그 이름이 128자를 초과함 {} 최대 문자 길이 제한 초과 태그 이름을 줄입니다.
500 ft.InternalServerError 유효한 TOML에 Team 또는 Related 테이블이 누락되었거나 저장 과정에서 명시적으로 처리되지 않은 구조 예외가 발생함 내부 오류 [Team] 및 [Related]를 포함한 전체 구성을 제출하고, 실패 후 팀과 서비스 현황을 확인한 뒤 재시도 여부를 결정합니다.
500 ft.InternalServerError 경로의 서비스 UUID가 존재하지 않거나 삭제되었거나 현재 워크스페이스에 없음 내부 오류 먼저 서비스 목록을 조회하여 대상을 확인하고, 이 오류를 저장 완료로 직접 간주하지 마세요.

문서 평가

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