생성¶
POST /api/v1/notes_v2/create
개요¶
새 노트를 생성하고 Markdown 본문을 저장합니다.
호출 전 및 사용 단계¶
노트 관리 권한이 있는 Key를 사용합니다. 제목과 Markdown 문자열을 제출하면 새 노트가 생성됩니다. 응답의 noteUUID와 etag를 저장합니다. 본문은 새 노트 상세에서 읽을 수 있습니다. 요청 시간 초과 시 먼저 목록에서 새 노트가 이미 생성되었는지 확인한 후 재시도 여부를 결정합니다.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| title | string | Y | 노트 제목입니다. null 허용: False 예: 生产巡检说明가져오기 또는 입력 방법: 노트 제목에 표시할 텍스트를 입력합니다. |
| content | string | Y | 전체 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에서 현재 값을 가져오거나 대상 공개 범위에 맞게 설정합니다. |
|
| extend | json | 클라이언트 확장 정보 객체입니다. null 허용: False 예: {}가져오기 또는 입력 방법: 기존 노트의 extend에서 가져오거나 비즈니스 요구에 따라 전체 값을 제공합니다. |
|
| noteType | string | 전달하지 않으면 normal을 사용합니다. null 허용: False 선택 가능한 값: ['normal', 'runbook', 'statuspages'] 예: runbook가져오기 또는 입력 방법: 용도에 따라 normal(일반), runbook(운영 매뉴얼) 또는 statuspages(상태 페이지 노트)를 선택합니다. |
매개변수 추가 설명¶
이 API는 JSON을 수신하며 content 필드에 Markdown 텍스트를 입력합니다. 생성 시 새로운 noteUUID가 생성됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"title":"生产巡检说明","content":"# 生产巡检\n\n先查看服务可用性,再核对最近告警。","tags":["ops"],"tagKV":{"service":"checkout"},"noteType":"runbook"}'
응답¶
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 | 현재 ID로 즐겨찾기되었는지 여부입니다. |
| content.creator | string | 생성자 ID입니다. |
| content.updator | string | 최근 업데이트한 사용자 ID입니다. |
| 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-1",
"version": 1,
"nbookETag": "etag-example-1",
"nbookVersion": 1,
"lastSyncAt": 1785427200,
"syncStatus": "synced",
"syncError": "",
"status": 0,
"isFavourited": false,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"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 객체에 넣습니다. |
| 406 | ft.MissingParameterValue | 제목이 필수이며 비어 있습니다. | 매개변수 title 누락 | 비어 있지 않은 제목을 입력한 후 다시 시도합니다. |
| 424 | ft.NbookDBApiError | 노트 서비스 요청 실패, 응답 이상 또는 서비스 사용 불가 | 노트 서비스 호출 실패 | 먼저 content.upstreamStatus와 응답 내용을 확인합니다. traceId를 보관하고 이후 구체적인 원인에 따라 재시도하거나 관리자에게 문의합니다. |