콘텐츠로 이동

생성



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를 보관하고 이후 구체적인 원인에 따라 재시도하거나 관리자에게 문의합니다.

문서 평가

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