동일 조직 워크스페이스 간소화 목록 조회¶
POST /api/v1/workspace/same_org/list
개요¶
조직 선언을 기준으로 활성 워크스페이스를 나열하며 ID 커서 페이지네이션을 지원합니다.
호출 전 및 사용 단계¶
대상 워크스페이스에서 routine.defaultAccess 등 읽기 권한이 허용된 OpenAPI Key를 사용합니다. 현재 워크스페이스는 요청 헤더의 Key에서 가져오며, 이 엔드포인트에서 workspaceUUID를 전달해 전환하지 않습니다.
현재 활성 워크스페이스에는 비어 있지 않은 declaration.organization이 있어야 합니다. 해당 조직 식별자를 기준으로 모든 활성 워크스페이스를 정확히 일치시키며, 현재 워크스페이스 자체도 포함합니다. 호출 계정의 가입 여부나 기존 교차 워크스페이스 권한 부여 여부로 필터링하지 않습니다. 반환은 동일 조직 디렉터리 관계를 나타내며, 다른 워크스페이스 데이터를 읽거나 워크스페이스를 관리하거나 다른 사이트에 액세스할 수 있음을 의미하지 않습니다.
workspaceId 내림차순으로 정렬됩니다. 첫 번째 호출에서는 beforeWorkspaceId를 생략하고 최상위 pageInfo.hasMore를 읽습니다. 값이 true이면 nextBeforeWorkspaceId를 사용해 계속 조회하며 workspaceUUIDs 필터 조건을 유지합니다. 이 페이지는 커서를 사용하며 pageIndex/totalCount를 제공하지 않습니다. 빈 필터 배열은 모든 동일 조직 워크스페이스를 조회한다는 의미이며, 어떤 워크스페이스도 조회하지 않는다는 의미로 사용할 수 없습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspaceUUIDs[*] | string | 단일 비어 있지 않은 UUID이며 최대 128자이고, trim 후 중복을 제거합니다. 목록에서 현재 조직에 속하지 않거나 비활성 상태인 항목은 반환되지 않습니다. 예: wksp_example획득 또는 입력 방법: 실제 워크스페이스 workspaceUUID를 사용하며 숫자 workspaceId가 아닙니다. |
|
| beforeWorkspaceId | integer | 선택적 양의 정수 커서이며 첫 번째 호출에서는 생략하거나 null로 지정합니다. 숫자 workspaceId가 이 값보다 작은 레코드만 반환합니다. pageIndex 또는 워크스페이스 UUID가 아니며 임의로 더하거나 빼지 마세요. null 허용: True 예: 1200획득 또는 입력 방법: 이전 페이지 최상위 pageInfo.nextBeforeWorkspaceId이며 첫 번째 호출에서는 생략합니다. |
|
| pageSize | integer | 선택적 양의 정수이며 생략하거나 null이면 기본값은 20입니다. 상한은 사이트 workspaceListPageSizeMax로 제어되며 기본값은 100입니다. 숫자 문자열과 불리언은 사용할 수 없습니다. null 허용: True 예: 20획득 또는 입력 방법: 페이지당 원하는 항목 수에 따라 선택하며 일반적으로 1..100입니다. |
|
| workspaceUUIDs | array | 선택적 문자열 배열이며 생략/null/[]은 모두 필터링하지 않습니다. 최대 사이트 maxWorkspaceCount(기본값 20)개 항목이며, 제한은 중복 제거 전에 확인합니다. 각 항목의 공백을 제거하고 중복을 제거합니다. 공백 항목/문자열이 아닌 항목/128자를 초과하는 항목은 거부됩니다. 호출자를 대신해 멤버 자격이나 데이터 권한을 설정하지 않습니다. null 허용: True 예: ["wksp_example"]획득 또는 입력 방법: 현재 워크스페이스 상세 또는 이전 동일 조직 목록의 content.data[].workspaceUUID에서 가져옵니다. 범위를 좁힐 워크스페이스 UUID만 입력합니다. |
파라미터 추가 설명¶
이 API는 SameOrgTraceQuerySet.enable의 제어를 받지 않으며, 동일 조직 trace 쿼리의 대상 워크스페이스를 선택하는 데만 보조적으로 사용됩니다.
workspaceId는 이 API의 페이지네이션에만 사용됩니다.- 후속 trace 쿼리에는
workspaceUUID를 사용해야 합니다. - 이 API는 DQL 쿼리를 실행하지 않으며 Kodo의 최종 동일 조직 검증을 대체하지도 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/same_org/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"pageSize":20}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> |
현재 페이지의 동일 조직 워크스페이스이며, 결과가 비어 있으면 []입니다. |
| content.data[].workspaceId | integer | 데이터베이스 숫자 ID이며 목록 커서에만 사용됩니다. |
| content.data[].workspaceUUID | string | 워크스페이스 UUID이며 후속 쿼리/권한 부여에는 여전히 별도 조건이 필요합니다. |
| content.data[].workspaceName | string | 워크스페이스 이름입니다. |
| content.data[].versionType | string | 워크스페이스의 실제 버전 코드입니다(예: pay/enterprise/unlimited/freeEdition 등). 이 API에서 전환하지 않습니다. |
| content.declaration | object | 현재 호출 워크스페이스의 공개 선언이며, 반환된 각 워크스페이스의 선언이 아닙니다. |
| pageInfo.pageSize | integer | 이번 페이지당 항목 수입니다. |
| pageInfo.hasMore | boolean | ID가 더 작은 레코드가 남아 있는지 여부입니다. |
| pageInfo.nextBeforeWorkspaceId | integer | hasMore=true이고 이 페이지에 레코드가 있을 때만 나타납니다. 다음 호출의 beforeWorkspaceId입니다. |
{
"code": 200,
"content": {
"data": [
{
"workspaceId": 1200,
"workspaceUUID": "wksp_example",
"workspaceName": "示例空间",
"versionType": "pay"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageSize": 20,
"hasMore": false
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | 요청 JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 객체를 제출하세요. |
| 406 | ft.ParameterCheckFailed | UUID 목록/개수/항목, 페이지 크기/커서가 일치하지 않거나 현재 워크스페이스에 유효한 조직 선언이 없음 | 예: page_size must be <= 100(구체적인 필드 및 상한은 이번 응답 메시지를 기준으로 함) | content.field에 따라 수정하세요. 오류 field는 workspace_uuids/page_size/before_workspace_id/organization 등 내부 매핑 이름을 사용할 수 있습니다. 조직 선언 누락은 관리자가 확인해야 합니다. |
| 500 | ft.InternalServerError | 워크스페이스/사이트/권한 구성, 데이터베이스 또는 캐시 읽기 및 응답 형식 지정 실패 | 내부 오류 | traceId와 쿼리 조건을 보관하고, 재시도해도 계속 실패하면 관리자에게 구성을 확인하도록 요청하세요. 빈 결과를 근거로 사이트에 데이터가 없다고 추론하지 마세요. |