수정¶
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로 다시 제출합니다. 요청 타임아웃인 경우 먼저 대상 상태를 확인합니다. |
다운스트림이 버전 조건 불일치를 보고할 때의 응답