콘텐츠로 이동

수정



POST /api/v1/notes_v2/{note_uuid}/modify

개요

새 버전 노트의 제목, 본문 또는 구성을 업데이트합니다.

호출 전 준비 및 사용 단계

먼저 새 버전 노트 상세로 본문과 etag를 조회합니다. 변경이 필요한 필드만 제출할 수 있으며, 생략하면 기존 값이 유지됩니다. content를 제출하면 본문 전체가 교체되며, 빈 문자열로 비울 수 있습니다. tags, tagKV, extend에 빈 컬렉션을 제출하면 비울 수 있습니다. 다른 사용자의 동시 업데이트를 덮어쓰지 않도록 ifMatch를 함께 전달하는 것을 권장합니다. 비공개 노트는 생성한 주체가 업데이트하며, 활동 상태 페이지와 연결된 경우 상태 페이지 구성 권한도 필요합니다.

라우트 파라미터

파라미터명 타입 필수 설명
note_uuid string Y 새 버전 노트 UUID입니다.
예시: nbnote_example
조회 또는 입력 방법: 새 버전 노트 목록의 content.data[].noteUUID 또는 생성 결과의 content.noteUUID에서 복사합니다.

요청 헤더

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

Body 요청 파라미터

파라미터명 타입 필수 설명
title string 노트 제목입니다.
null 허용: False
예시: 生产巡检说明
조회 또는 입력 방법: 노트 제목에 표시할 텍스트를 입력합니다.
content string 전체 Markdown 본문 문자열입니다.
null 허용: False
예시: "# 生产巡检\n\n先查看服务可用性,再核对最近告警。"
조회 또는 입력 방법: 저장할 Markdown 텍스트를 입력합니다. JSON 문자열의 줄바꿈은 이스케이프를 사용합니다.
tags array 일반 태그 문자열 배열입니다.
null 허용: False
예시: ["ops"]
조회 또는 입력 방법: 기존 노트의 tags에서 복사하거나 그룹화/필터링에 사용할 태그명을 직접 입력합니다.
tagKV json 키-값 태그 객체이며, 문자열 키와 값을 사용하는 것을 권장합니다.
null 허용: False
예시: {"service": "checkout"}
조회 또는 입력 방법: 기존 노트의 tagKV에서 복사하거나 비즈니스 규칙에 따라 키와 값을 입력합니다.
isPublic int 숫자 1은 공개, 0은 비공개입니다. 생략하면 기존 값이 유지됩니다.
null 허용: False
예시: 1
조회 또는 입력 방법: 노트 상세의 isPublic에서 현재 값을 가져오거나 대상 공개 범위에 맞게 설정합니다.
ifMatch string 선택적 버전 검증입니다. 업데이트 또는 삭제 전에 해당 버전을 비교하며, 생략하면 조건을 추가하지 않습니다.
null 허용: False
예시: etag-example-1
조회 또는 입력 방법: 새 버전 노트 상세의 content.etag에서 가져와 그대로 전달합니다.
extend json 클라이언트 확장 정보 객체입니다.
null 허용: False
예시: {}
조회 또는 입력 방법: 기존 노트의 extend에서 가져오거나 비즈니스 요구에 맞게 전체 값을 제공합니다.

파라미터 추가 설명

메타데이터만 변경하더라도 기존 본문이 다시 저장됩니다. 새 본문을 읽어야 할 경우 상세를 계속 조회합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/nbnote_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"content":"# 生产巡检\n\n先查看服务可用性,再核对最近告警。\n\n巡检完成。","ifMatch":"etag-example-1"}'

응답

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

필드 타입 설명
content.id integer 노트 레코드 번호입니다.
content.uuid string Studio 노트 식별자이며 noteUUID와 동일합니다.
content.noteUUID string 상세, 수정 및 삭제 경로에 사용하는 노트 UUID입니다.
content.title string 노트 제목입니다.
content.name string title과 동일한 엔터티 필드입니다.
content.workspaceUUID string 노트가 속한 워크스페이스 UUID입니다.
content.isPublic integer 1은 공개, 0은 비공개입니다.
content.tags array<string> 일반 태그입니다.
content.tagKV object 키-값 태그입니다.
content.extend object 비즈니스 확장 구성입니다.
content.createdSource string 생성 출처(예: manual 또는 ai)입니다.
content.noteType string normal, runbook 또는 statuspages입니다.
content.etag string 현재 ETag이며 수정 또는 삭제 시 ifMatch로 사용할 수 있습니다.
content.version integer 현재 콘텐츠 버전 번호입니다.
content.nbookETag string etag와 동일한 엔터티 필드입니다.
content.nbookVersion integer version과 동일한 엔터티 필드입니다.
content.lastSyncAt integer 마지막 동기화 시간이며 Unix 초 단위입니다.
content.syncStatus string 콘텐츠 동기화 상태(예: synced)입니다.
content.syncError string 동기화 오류 설명이며, 동기화된 경우 일반적으로 비어 있습니다.
content.status integer 노트 상태입니다.
content.isFavourited boolean 쓰기 결과는 false입니다. 실제 즐겨찾기 상태는 목록 또는 상세에서 조회합니다.
content.creator string 생성자 식별자입니다.
content.updator string 최근 수정자 식별자입니다.
content.createAt number 생성 시간이며 Unix 초 단위입니다.
content.updateAt number 업데이트 시간이며 Unix 초 단위입니다. 생성 시 -1일 수 있습니다.
content.deleteAt number 삭제 시간이며 Unix 초 단위입니다. 삭제되지 않은 경우 -1입니다.
content.declaration object 또는 null 워크스페이스의 공개 선언입니다.
{
  "code": 200,
  "content": {
    "id": 42,
    "uuid": "nbnote_example",
    "noteUUID": "nbnote_example",
    "title": "生产巡检说明",
    "name": "生产巡检说明",
    "workspaceUUID": "wksp_example",
    "isPublic": 1,
    "tags": [
      "ops"
    ],
    "tagKV": {
      "service": "checkout"
    },
    "extend": {},
    "createdSource": "manual",
    "noteType": "runbook",
    "etag": "etag-example-2",
    "version": 2,
    "nbookETag": "etag-example-2",
    "nbookVersion": 2,
    "lastSyncAt": 1785427320,
    "syncStatus": "synced",
    "syncError": "",
    "status": 0,
    "isFavourited": false,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427320,
    "deleteAt": -1,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

HTTP 424를 수신하면 content.upstreamStatus는 다운스트림이 반환한 상태이며, 연결 이상 시 0일 수 있습니다. content.upstreamPath는 해당 실패 요청의 경로이고, content.responseBody는 다운스트림 오류 내용입니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드명, 타입 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 구문은 유효하지만 요청 최상위가 객체가 아님 일부 json 파일 형식 오류 파라미터를 JSON 객체에 넣습니다.
404 ft.NotFoundNote 활동 노트가 존재하지 않거나, 현재 워크스페이스에 속하지 않거나, 이미 삭제됨 지정한 노트를 찾을 수 없음 현재 워크스페이스, 대상 noteUUID 및 작업 성공 여부를 확인합니다.
403 ft.ForbiddenOperationResource 호출 주체가 다른 사람의 비공개 노트를 수정 또는 삭제하거나, 대상에 활동 상태 페이지가 연결되어 있고 statusPage.configManage가 없음 현재 작업 권한 없음 대상의 공개 범위와 상태 페이지 연결을 확인하고, 필요한 권한을 갖춘 호출 주체로 전환합니다.
424 ft.NbookDBApiError 노트 서비스가 쓰기 또는 삭제를 거부하거나, 버전 조건이 일치하지 않거나, 요청이 실패함 노트 서비스 호출 실패 먼저 content.upstreamStatus를 확인합니다. 버전 충돌인 경우 새 버전 노트 상세로 본문과 ETag를 다시 읽고, 병합한 뒤 새 ifMatch로 다시 제출합니다. 요청 타임아웃인 경우 먼저 대상 상태를 확인합니다.

다운스트림이 버전 조건 불일치를 보고할 때의 응답

{
  "code": 424,
  "content": {
    "upstreamStatus": 412,
    "upstreamPath": "/v1/notes",
    "responseBody": {
      "message": "ETag 不匹配"
    }
  },
  "errorCode": "ft.NbookDBApiError",
  "message": "笔记服务调用失败",
  "success": false,
  "traceId": "TRACE-EXAMPLE"
}

문서 평가

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