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