워크스페이스 리소스 내보내기¶
POST /api/v1/workspace/resource/export/task/create
개요¶
현재 워크스페이스 리소스 구성 ZIP 내보내기 작업을 생성합니다.
호출 전 및 사용 단계¶
현재 Key에는 workspace.setManage 권한이 필요합니다. 작업은 현재 워크스페이스와 작업을 시작한 Key의 리소스 UUID에만 속합니다. 동일 워크스페이스의 다른 Key가 동일한 역할을 가지고 있더라도 해당 작업을 읽거나 취소할 수 없습니다. 동일 Key를 순환(교체)해도 리소스 UUID는 유지되며, taskId와 API Key 값을 혼용해서는 안 됩니다.
Body를 생략하거나 {}를 제출하세요. 비어 있지 않은 JSON 객체는 거부됩니다. resourceType/sloUUIDs를 전달하거나 일부 모듈만 내보내도록 지정할 수 없습니다. SLO 전용 내보내기는 별도 인터페이스를 사용하세요. 지원되는 카탈로그에 따라 대시보드, 모니터, 탐색기, 알림 대상, SLO, 보안 모니터링, 알림 정책, 데이터 전송, 워크스페이스 속성 클레임, 필드 구성, 태그, 환경 변수, 역할, 로그 인덱스, 블랙리스트, Pipeline, 정규식, 필드 마스킹 규칙, 민감 데이터 스캔 규칙 등의 구성 내보내기를 시도합니다. 로그/메트릭 등 원시 비즈니스 데이터는 포함하지 않으며 전체 데이터베이스 백업도 아닙니다.
성공 시 taskId만 반환됩니다. 리소스 작업 진행 상황을 사용하여 폴링하세요. status=ok 이후에만 url이 있을 수 있습니다. import_info.exportInfo.result, exportFailedInfo 및 리소스 실패 요약을 동시에 확인해야 합니다. ok는 일부 리소스가 권한 또는 직렬화 실패로 건너뛰어진 상태일 수 있으며, 모든 객체가 패키지에 포함된다고 보장하지 않습니다. 작업 생성 시점의 권한 컨텍스트를 저장하며, 일부 사용자 지정 작업 권한으로 제어되는 리소스는 규칙에 따라 필터링됩니다.
리소스 패키지에는 복구 가능한 외부 스토리지 액세스 키, 연결 구성, 환경 변수 등 민감한 구성이 포함될 수 있습니다. 민감한 백업으로 보관하고 다운로드 URL을 공개하지 마세요. 작업 및 임시 파일에는 유효 기간이 있습니다. 코드에서 기본 작업 캐시는 약 10분이며 사이트에서 구성할 수 있습니다. ok 후 가능한 한 빨리 다운로드하세요. 캐시가 완전히 존재하지 않을 때는 status=null이 조회될 수 있습니다. 장기 작업이 캐시 제한 시간을 초과한 후에는 소속 정보가 누락된 상태 레코드가 남고 403이 반환될 수 있으므로 taskId를 보관하고 관리자에게 작업 로그/리소스 확인을 요청한 후 재생성 여부를 결정해야 합니다. 작업 생성은 멱등적이지 않으므로 네트워크 실패 후에는 이미 반환된 taskId를 먼저 확인한 뒤 재시도하세요.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득하세요. |
매개변수 추가 설명¶
1. 인터페이스 용도
현재 워크스페이스의 리소스 내보내기 작업을 시작합니다.
이 인터페이스는 비동기 작업 인터페이스이며, 호출 성공 후 taskId만 반환하고 압축 패키지 내용은 즉시 반환하지 않습니다.
권장 호출 흐름은 다음과 같습니다.
- 현재 인터페이스를 호출하여
taskId를 획득합니다. GET /api/v1/workspace/resource/query_action_status를 호출하여 작업 상태를 폴링합니다.- 상태가
ok가 된 후 상태 인터페이스 반환 결과에서 내보내기 파일 정보를 획득합니다.
2. 요청 설명
기본적으로 요청 본문을 전달하지 않으면 DF-API-KEY가 속한 워크스페이스의 모든 리소스를 내보냅니다.
SLO 리소스 패키지를 내보내려면 POST /api/v1/slo/export/task/create를 호출하세요. 현재 인터페이스는 워크스페이스 전체 리소스 내보내기에만 사용됩니다.
3. 반환 설명
성공 반환 예시:
설명:
- 작업 생성에 성공하면
taskId가 반환됩니다. - 이후 내보내기 실행 실패, 일부 리소스 내보내기 실패는 모두 작업 상태 인터페이스를 통해 확인해야 합니다.
4. 현재 리소스 경계 설명
현재 워크스페이스 리소스 가져오기/내보내기에는 다음과 같은 경계가 있습니다.
- 환경 변수에는
scope=rum이 포함되지 않습니다. - 로그 인덱스에는 외부 인덱스 및
default가 포함되지 않습니다. - 필드 관리는 워크스페이스 사용자 지정 필드만 처리합니다.
- 데이터 액세스는 현재 워크스페이스 가져오기/내보내기를 지원하지 않습니다.
5. 내보내기 결과 추가 설명
특정 리소스의 단일 객체 내보내기가 실패하더라도 전체 내보내기 작업은 중단되지 않습니다.
작업 상태 인터페이스의 import_info.exportInfo.resourceFailureInfo는 중복 제거된 리소스 수준 실패 상세를 반환하며, 여기에는 리소스 유형, 리소스 UUID, 리소스 이름, 안정적인 실패 원인 및 영향을 받은 SLO가 포함됩니다. 리소스 구성, 권한 구성원, 예외 스택 또는 민감한 필드는 반환하지 않습니다.
기존 import_info.exportFailedInfo는 이전 클라이언트와의 호환을 위해 계속 유지되지만, 여기에 포함된 원시 예외 정보를 직접 표시하는 것은 권장하지 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/resource/export/task/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.taskId | string | 비동기 작업 ID로, 이후 taskId로 조회/취소합니다. ZIP 다운로드 주소나 Celery 실행 완료 플래그가 아닙니다. |
| content.declaration | object | 현재 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"taskId": "resource_task_example",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 400 | ft.ParamsValidateError | 비어 있지 않은 JSON 객체를 전송함. 이 진입점은 필터 내보내기 매개변수를 허용하지 않음 | 매개변수 검증 실패: {} | Body를 생략하거나 {}를 전송하세요. SLO 전용 매개변수를 혼합하지 마세요. |
| 500 | ft.InternalServerError | 작업 캐시/큐, 파일 시스템, 데이터베이스 또는 미처리 작업 상태/JSON 처리 실패 | 내부 오류 | 먼저 동일 워크스페이스의 동일 Key로 작업 및 리소스 현재 상태를 조회하여 큐에 등록되었는지/부분 저장되었는지 확인한 후 재시도하고, 가져오기 또는 덮어쓰기를 무작정 반복하지 마세요. |