콘텐츠로 이동

목록 조회



POST /api/v1/notes_v2/list

개요

조건에 따라 현재 호출 주체가 볼 수 있는 새 버전 노트를 조회합니다.

호출 전 및 사용 단계

노트 읽기 권한이 있는 Key를 사용합니다. 목록에는 공개 노트와 현재 호출 주체의 비공개 노트만 포함됩니다. 즐겨찾기 항목이 우선하며, 나머지는 최근 업데이트 시간 내림차순으로 정렬되고 업데이트되지 않은 경우 생성 시간을 사용합니다. 기본적으로 메타데이터를 반환하며, 단일 본문은 새 버전 노트 상세로 가져옵니다. 본문을 일괄로 읽어야 하는 경우 includeContent=true, 양의 정수 페이지 번호, 100을 초과하지 않는 pageSize를 함께 전달합니다.

요청 헤더

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

Body 요청 파라미터

파라미터 이름 유형 필수 설명
pageIndex integer 양의 정수 pageSize와 함께 제공하면 페이지네이션을 활성화합니다.
null 허용: False
예시: 1
가져오기 또는 입력 방법: 1부터 페이지 번호를 전달합니다.
pageSize integer 양의 정수 페이지 크기입니다. 생략하거나 양의 정수 페이지 번호와 함께 전달하지 않으면 페이지네이션하지 않습니다.
null 허용: False
예시: 20
가져오기 또는 입력 방법: 한 페이지에 필요한 항목 수를 입력합니다. 본문을 읽을 때는 최대 100입니다.
search string 제목과 본문을 검색하는 데 사용합니다. 비어 있지 않은 query가 더 높은 우선순위를 가집니다.
null 허용: False
예시: 巡检
가져오기 또는 입력 방법: 제목 또는 Markdown 본문의 단어로 입력합니다.
query string 우선 사용되는 전체 텍스트 검색어입니다.
null 허용: False
예시: 巡检
가져오기 또는 입력 방법: 찾으려는 노트 제목 또는 본문에서 검색어를 선택합니다.
tags array 일반 태그 필터이며 기본적으로 태그 중 하나라도 일치하면 됩니다.
null 허용: False
예시: ["ops"]
가져오기 또는 입력 방법: 반환된 tags 배열 또는 알려진 태그 이름에서 값을 가져옵니다.
tagKV json 키-값 태그 일치입니다. tagKVQuery와 이름이 같은 키는 이 필드를 기준으로 합니다.
null 허용: False
예시: {"service": "checkout"}
가져오기 또는 입력 방법: 노트 tagKV 결과에서 일치시킬 키와 값을 복사합니다.
tagKVQuery string 키-값 태그 일치 표현식입니다. 값에 공백이 포함되면 따옴표를 사용합니다.
null 허용: False
예시: service:"checkout" AND env:"prod"
가져오기 또는 입력 방법: 실제 키와 값으로 key:"value" 표현식을 작성하며 AND 또는 공백으로 연결할 수 있습니다.
tagMode string 일반 태그 결합 방식이며 기본값은 or입니다.
null 허용: False
허용 값: ['and', 'or']
예시: and
가져오기 또는 입력 방법: 모든 일반 태그가 일치해야 하면 and를, 하나라도 일치하면 or를 사용합니다.
createdSource string 생성 소스를 정확히 일치시킵니다. 예: manual, ai. 생략하면 필터링하지 않습니다.
null 허용: False
예시: manual
가져오기 또는 입력 방법: 상세의 content.createdSource에서 필터링할 소스 값을 가져옵니다.
noteType string 노트 유형입니다.
null 허용: False
허용 값: ['normal', 'runbook', 'statuspages']
예시: runbook
가져오기 또는 입력 방법: 용도에 따라 normal(일반), runbook(런북) 또는 statuspages(상태 페이지 노트)를 선택합니다.
isPublic boolean 공개 범위 필터입니다. 생략하면 현재 호출 주체가 읽을 수 있는 모든 일치 레코드를 반환합니다.
null 허용: False
예시: true
가져오기 또는 입력 방법: 공개 노트를 조회하려면 true를, 현재 호출 주체 자신의 비공개 노트를 조회하려면 false를 전달합니다.
tagKVRange json 키는 영문자, 숫자, 밑줄, 하이픈, 점만 지원합니다. gte는 하한 포함, lte는 상한 포함이며 이 두 필드만 지원하고, 하나 이상의 비어 있지 않은 경계를 입력해야 합니다. 양쪽을 모두 입력할 때 문자열은 사전순으로 비교하며 gte는 lte보다 클 수 없습니다.
null 허용: False
예시: {"run_date": {"gte": "2026-07-01", "lte": "2026-07-31"}}
가져오기 또는 입력 방법: 반환된 tagKV에서 범위를 제한할 키를 선택하고 통일된 형식의 문자열 경계를 입력합니다.
includeContent boolean 기본값은 false입니다. 활성화하면 pageIndex는 최소 1, pageSize는 1–100입니다.
null 허용: False
예시: false
가져오기 또는 입력 방법: Markdown 본문을 일괄로 가져와야 하면 true로 설정하고 페이지네이션 파라미터를 제공합니다.

파라미터 추가 설명

검색, 일반 태그 및 키-값 태그 조건은 필요에 따라 조합할 수 있습니다. tagKVRange는 원본 문자열 정렬을 사용하므로 고정 너비의 날짜 또는 숫자 형식을 사용하는 것이 좋습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"pageIndex":1,"pageSize":20,"query":"巡检","includeContent":true}'

응답

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

필드 유형 설명
content.data array<object> 현재 목록 또는 단일 페이지의 일치 항목입니다.
content.data[].id integer 노트 레코드 번호입니다.
content.data[].uuid string Studio 노트 식별자이며 noteUUID와 동일합니다.
content.data[].noteUUID string 상세, 수정 및 삭제 경로에 사용되는 노트 UUID입니다.
content.data[].title string 노트 제목입니다.
content.data[].name string title과 동일한 엔터티 필드입니다.
content.data[].workspaceUUID string 노트가 속한 워크스페이스 UUID입니다.
content.data[].isPublic integer 1은 공개, 0은 비공개입니다.
content.data[].tags array<string> 일반 태그입니다.
content.data[].tagKV object 키-값 태그입니다.
content.data[].extend object 비즈니스 확장 설정입니다.
content.data[].createdSource string 생성 소스입니다. 예: manual 또는 ai.
content.data[].noteType string normal, runbook 또는 statuspages입니다.
content.data[].etag string 현재 ETag이며 수정 또는 삭제 시 ifMatch로 사용할 수 있습니다.
content.data[].version integer 현재 콘텐츠 버전 번호입니다.
content.data[].nbookETag string etag와 동일한 엔터티 필드입니다.
content.data[].nbookVersion integer version과 동일한 엔터티 필드입니다.
content.data[].lastSyncAt integer 마지막 동기화 시간(Unix 초)입니다.
content.data[].syncStatus string 콘텐츠 동기화 상태입니다. 예: synced.
content.data[].syncError string 동기화 오류 설명이며 동기화된 경우 일반적으로 비어 있습니다.
content.data[].status integer 노트 상태입니다.
content.data[].isFavourited boolean 현재 호출 주체의 즐겨찾기로 표시되었는지 여부입니다.
content.data[].creator string 생성자 식별자입니다.
content.data[].updator string 최근 업데이트자 식별자입니다.
content.data[].createAt number 생성 시간(Unix 초)입니다.
content.data[].updateAt number 업데이트 시간(Unix 초)이며 새로 생성된 경우 -1일 수 있습니다.
content.data[].deleteAt number 삭제 시간(Unix 초)이며 삭제되지 않은 경우 -1입니다.
content.data[].creatorInfo object 생성자 ID의 추가 정보이며 찾을 수 없으면 빈 객체입니다.
content.data[].updatorInfo object 마지막 업데이트 ID의 추가 정보이며 찾을 수 없으면 빈 객체입니다.
content.data[].creatorInfo.uuid string 실제 ID 정보에 따라 제공됩니다. ID 식별자입니다.
content.data[].creatorInfo.status integer 실제 ID 정보에 따라 제공됩니다. 계정 상태입니다.
content.data[].creatorInfo.wsAccountStatus integer 실제 ID 정보에 따라 제공됩니다. 워크스페이스 멤버 상태입니다.
content.data[].creatorInfo.username string 실제 ID 정보에 따라 제공됩니다. 계정 로그인 이름입니다.
content.data[].creatorInfo.name string 실제 ID 정보에 따라 제공됩니다. 표시 이름입니다.
content.data[].creatorInfo.iconUrl string 실제 ID 정보에 따라 제공됩니다. 아바타 URL입니다.
content.data[].creatorInfo.email string 실제 ID 정보에 따라 제공됩니다. 계정 이메일입니다. API Key ID는 해당 식별자를 반환할 수 있습니다.
content.data[].creatorInfo.mobile string 실제 ID 정보에 따라 제공됩니다. 연락처입니다.
content.data[].creatorInfo.countryCode string 실제 ID 정보에 따라 제공됩니다. 휴대폰 번호 국가 또는 지역 코드입니다.
content.data[].creatorInfo.acntWsNickname string 실제 ID 정보에 따라 제공됩니다. 워크스페이스 닉네임입니다.
content.data[].updatorInfo.uuid string 실제 ID 정보에 따라 제공됩니다. ID 식별자입니다.
content.data[].updatorInfo.status integer 실제 ID 정보에 따라 제공됩니다. 계정 상태입니다.
content.data[].updatorInfo.wsAccountStatus integer 실제 ID 정보에 따라 제공됩니다. 워크스페이스 멤버 상태입니다.
content.data[].updatorInfo.username string 실제 ID 정보에 따라 제공됩니다. 계정 로그인 이름입니다.
content.data[].updatorInfo.name string 실제 ID 정보에 따라 제공됩니다. 표시 이름입니다.
content.data[].updatorInfo.iconUrl string 실제 ID 정보에 따라 제공됩니다. 아바타 URL입니다.
content.data[].updatorInfo.email string 실제 ID 정보에 따라 제공됩니다. 계정 이메일입니다. API Key ID는 해당 식별자를 반환할 수 있습니다.
content.data[].updatorInfo.mobile string 실제 ID 정보에 따라 제공됩니다. 연락처입니다.
content.data[].updatorInfo.countryCode string 실제 ID 정보에 따라 제공됩니다. 휴대폰 번호 국가 또는 지역 코드입니다.
content.data[].updatorInfo.acntWsNickname string 실제 ID 정보에 따라 제공됩니다. 워크스페이스 닉네임입니다.
content.data[].content string Markdown 본문입니다. 목록은 includeContent가 활성화된 경우에만 반환됩니다.
content.declaration object 또는 null 워크스페이스의 공용 선언입니다.
pageInfo object 페이지네이션이 활성화된 경우 응답 최상위에 위치합니다.
pageInfo.pageIndex integer 현재 페이지 번호입니다.
pageInfo.pageSize integer 페이지 크기입니다.
pageInfo.totalCount integer 조건에 맞고 볼 수 있는 노트의 총 개수입니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "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,
        "creatorInfo": {},
        "updatorInfo": {},
        "content": "# 生产巡检\n\n先查看服务可用性,再核对最近告警。"
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 20,
    "totalCount": 1
  }
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.

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 tagKVQuery를 키-값 표현식으로 파싱할 수 없음 tagKVQuery 형식 오류 key:"value"로 변경하고 각 키와 값을 확인합니다.
406 ft.InvalidParameter tagKVRange의 키, 범위 필드 또는 상한/하한이 유효하지 않음 파라미터 tagKVRange가 유효하지 않음 gte 및 lte 문자열 경계를 사용하고 하나 이상 제공합니다.
400 ft.ParamsValidateError 요청에서 목록 본문을 읽을 때 유효한 페이지네이션이 없거나 pageSize가 100을 초과함 파라미터 검증 실패: pageSize 양의 정수 pageIndex와 1–100의 pageSize를 입력합니다.
424 ft.NbookDBApiError 노트 서비스 요청 실패, 응답 이상 또는 서비스 사용 불가 노트 서비스 호출 실패 먼저 content.upstreamStatus와 응답 내용을 확인합니다. traceId를 보관하고 이후 구체적인 원인에 따라 재시도하거나 관리자에게 문의합니다.

문서 평가

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