공유¶
POST /api/v1/snapshots/{snapshot_uuid}/share
개요¶
기존 스냅샷에 대한 액세스 공유 및 장기 최초 진입 코드를 생성합니다.
호출 전 및 사용 단계¶
현재 Key에는 share.shareManage 권한이 필요하며, 현재 워크스페이스에서 삭제되지 않은 스냅샷만 대상으로 합니다. 무료 플랜 워크스페이스는 스냅샷 공유를 지원하지 않으며, 구체적인 지원 여부는 사이트 버전에 따라 결정됩니다. 공유 구성을 새로 만들 때마다 공개 멱등 키가 없으므로, 요청을 반복하면 여러 개의 유효한 공유가 생성될 수 있습니다. 타임아웃/500 발생 시 먼저 현재 콘솔의 공유 관리 목록에서 resourceUUID를 확인한 후 재시도 여부를 결정하십시오.
content.token과 authCode는 동일한 장기 최초 진입 코드이며, 현재 워크스페이스의 브랜드/사용자 정의 콘솔 도메인에 있는 /share/{code} 페이지에 사용됩니다. 데이터 조회에 직접 사용할 수 있는 2단계 share token이 아니며, share_ 구성 UUID도 아닙니다. shortUrl은 사이트에서 단축 링크가 비활성화된 경우 비어 있을 수 있으므로, 실제 콘솔 진입점에 /share/와 authCode를 이어 붙여 사용해야 합니다. 브랜드 도메인을 하드코딩하지 마십시오. 공유를 취소하려면 콘솔 공유 관리에서 해당 share_ UUID를 가져와야 합니다. 현재 생성 응답은 이 UUID를 반환하지 않으며, 이 OpenAPI 그룹에는 ShareConfig 공개 목록도 없으므로 이번에 반환된 코드만으로 UUID를 추론할 수 없습니다. UI에 표시되지 않는 경우 워크스페이스 관리자에게 도움을 요청하여 가져오십시오. 교차 워크스페이스 권한 부여 구성인 grant_ UUID를 사용할 수 없으며, token 또는 snap_를 전달해서도 안 됩니다.
이번 요청에서는 표시용으로 스냅샷 페이지 구성의 복사본을 저장하지만, 실제 쿼리는 여전히 스냅샷 저장 시의 서버 측 범위로 복원됩니다. 클라이언트의 maskCfg는 추가 마스킹만 수행하며 권한을 확장할 수 없습니다. 공유 정규식은 문자열 값만 처리하며, 숫자/객체/배열은 이 규칙으로 마스킹되지 않습니다. fields=*는 단독으로 사용해야 하며, *,message를 혼합하면 모든 필드가 포함된다고 보장할 수 없습니다. 저장 시 정규식 검증에는 regex를 사용하고 실행 시에는 Python 표준 re.sub를 사용하므로, 두 방식이 공통으로 지원하는 문법을 사용하고 실제 샘플로 검증해야 합니다. 저장 성공이 쿼리 실행 가능성을 보장하지는 않습니다. 이전 스냅샷 범위가 누락되었거나 지원되지 않는 쿼리는 액세스 시 403이 발생하여 원래 공유자가 다시 생성하도록 요구할 수 있습니다. 공유 생성 성공이 모든 쿼리의 사용 가능성을 보장하지는 않습니다.
IP 제어는 현재 custom만 공개 선언을 실제로 통과할 수 있으며, followWorkspace는 길이 검증 충돌로 406이 발생합니다. isOpen=true, type=custom 및 비어 있지 않은 실제 IP 목록이 필요하며, custom[]는 실제로 제한하지 않습니다. 추출 코드/만료 및 마스킹을 사용하여 필요에 따라 액세스를 제어하며, hiddenTopBar/showWatermark는 표시 용도일 뿐입니다. 단축 링크와 최초 진입 코드의 캐시 동기화는 본문 커밋 전후에 발생할 수 있으므로, 500이 유효한 공유가 없음을 보장하지 않습니다. 먼저 확인한 후 재시도하십시오.
라우트 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| snapshot_uuid | string | Y | 공유 구성 share_ UUID, token/authCode 최초 진입 코드 또는 대시보드 UUID가 아닙니다. 예: snap_example가져오기 또는 입력 방법: 스냅샷 목록에서 content.data[].uuid를 가져오며, 현재 Key로 관리 권한이 확인된 snap_ UUID만 작업합니다. |
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| maskCfg | object | 선택적 객체이며, 올바른 fields/reExprs를 함께 구성해야 합니다. 공유에 추가되는 마스킹으로, 스냅샷 생성 시 캡처된 데이터/민감 규칙을 대체하지 않습니다. 실제 데이터의 전체 범위가 자동으로 검증되지는 않습니다. 예: {"fields": "message", "reExprs": [{"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}]}가져오기 또는 입력 방법: 표시할 실제 필드와 마스킹 패턴에 맞게 구성하고, 먼저 통제된 데이터에서 검증하십시오. |
|
| maskCfg.fields | string | 선택적 문자열이며, 생략/빈 값이면 공유 마스킹 필드를 지정하지 않습니다. 앞뒤 공백은 필드 strip으로 처리됩니다. 일치하는 문자열 값에만 활성화된 정규식이 실행되며, 숫자/객체/배열은 이 공유 정규식으로 변환되어 마스킹되지 않습니다. 액세스 허용 목록이 아닙니다. 빈 문자열 허용: True null 허용: False 예: message,host가져오기 또는 입력 방법: 스냅샷 쿼리에서 실제 반환된 열 이름으로 필드를 선택하고 쉼표로 구분합니다. 모든 필드는 *를 단독으로 전달해야 하며, *,message와 같은 혼합 목록을 작성하지 마십시오. |
|
| maskCfg.reExprs | array | 선택적 객체 배열이며, 생략 시 []입니다. 생성 시 enable=0인 항목을 포함한 모든 reExpr의 문법을 검사합니다. 하위 항목에 대한 전체 선언 검증은 없으며, 객체가 아닌 경우 500이 발생할 수 있습니다. null 허용: False 예: [{"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}]가져오기 또는 입력 방법: 호출자가 검증한 정규식 배열을 제공합니다. |
|
| maskCfg.reExprs[*] | json | 객체에는 올바른 reExpr와 enable이 포함되어야 하며, 배열 순서대로 적용됩니다. 예: {"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}가져오기 또는 입력 방법: 마스킹 규칙 하나입니다. |
|
| maskCfg.reExprs[*].name | string | 선택적 표시 이름이며, 필드 선택에는 사용되지 않습니다. 예: email가져오기 또는 입력 방법: 호출자가 정규식에 표시 이름을 지정합니다. |
|
| maskCfg.reExprs[*].reExpr | string | 저장 검증에는 regex.finditer를 사용하고 실행에는 표준 re.sub를 사용하므로, 두 방식 모두와 호환되어야 합니다. regex 전용 문법은 저장에 성공하더라도 공유 쿼리 시 오류가 발생할 수 있습니다. 저장 검증 실패 시 400 ErrorRegularExpression이 발생합니다. 실제 문자열 샘플과 성능을 검증해야 합니다. 예: [A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+가져오기 또는 입력 방법: Python 표준 re.sub와 호환되는 표현식을 입력하고 실제 샘플에서 검증하십시오. |
|
| maskCfg.reExprs[*].enable | integer | 실행 시 참/거짓 값으로 실행 여부를 판단하며, 0/1 정수를 권장합니다. 열거형이 완전히 선언되어 있지 않으므로 임의 유형에 안정적인 동작을 의존하지 마십시오. 예: 1가져오기 또는 입력 방법: 0은 비활성화, 1은 활성화입니다. |
|
| ipWhitelistSet | object | 선택적 IP 제어 객체이며, 생략/비활성화 시 공유 IP 제한을 추가하지 않습니다. 생성 시 IP 문자열을 완전히 검증하지 않으므로 실제 액세스 경로에서 확인하십시오. 예: {"isOpen": true, "type": "custom", "ipWhitelist": ["192.0.2.0/24"]}가져오기 또는 입력 방법: 네트워크 관리자가 공유 액세스를 허용할 실제 출구 IP/CIDR을 제공해야 하며, 예시 주소는 교체해야 합니다. |
|
| ipWhitelistSet.ipWhitelist | array | 선택적 배열이며, custom일 때 명시적으로 비어 있지 않아야 합니다. []는 현재 실제로 제한하지 않으며 모두 거부하는 것이 아닙니다. 항목별 생성 검증이 없으므로 유효하지 않은 주소는 액세스 시 예외가 발생할 수 있으니 반드시 검증하십시오. null 허용: False 예: ["192.0.2.0/24"]가져오기 또는 입력 방법: 네트워크 관리자가 제공한 단일 IP 또는 CIDR 대역이며, 서버가 식별하는 실제 클라이언트 출구 주소를 확인하십시오. |
|
| ipWhitelistSet.isOpen | boolean | 선택적 불리언이며, 생략 시 false입니다. true인 경우에도 유효한 type을 선택하고 비어 있지 않은 목록을 제공해야 의도한 대로 제한할 수 있습니다. null 허용: False 예: true가져오기 또는 입력 방법: 공유 수신 네트워크를 제한해야 할 때 명시적으로 true로 설정하십시오. |
|
| ipWhitelistSet.type | string | 열거형으로 custom/followWorkspace를 선언하지만, followWorkspace는 15자로 현재 maxLength 12와 충돌하여 사전에 406이 발생하므로 이 공개 진입점으로는 설정할 수 없습니다. 생략/빈 값이고 isOpen=true인 경우 실행 시 경고만 발생하고 제한하지 않을 수 있으므로, 이를 기본 워크스페이스 따르기로 간주해서는 안 됩니다. 빈 문자열 허용: True null 허용: False 선택 가능 값: ['followWorkspace', 'custom'] 최대 길이: 12 예: custom가져오기 또는 입력 방법: 현재 공개 쓰기에서는 custom을 사용하십시오. |
|
| ipWhitelistSet.ipWhitelist[*] | string | 단일 IP/대역 문자열이며, 도메인 또는 URL이 아닙니다. 예: 192.0.2.0/24가져오기 또는 입력 방법: 실제 허용 출구 IP/CIDR이며, 예시 대역은 형식만 보여줍니다. |
|
| changeTime | boolean | 선택적 불리언이며, UI 기본값은 false입니다. 표시 제어만 저장하며 서버 측 권한 범위/원본 데이터 보존 기간을 확장하지 않습니다. null 허용: False 예: false가져오기 또는 입력 방법: 공유 방문자가 UI에서 쿼리 시간을 조정할 수 있는지 여부에 따라 결정하십시오. |
|
| expirationAt | integer | 선택적 정수이며, 생략 시 사이트의 snapshotShareCfg.effectiveTime(기본 172800초=2일)을 따릅니다. -1은 영구이며, 빈 문자열을 명시하더라도 허용으로 선언되어 있어 -1로 정규화되므로 정수만 사용하는 것을 권장합니다. 과거 시간은 저장할 수 있지만 액세스 즉시 만료됩니다. Unix 밀리초가 아닙니다. 빈 문자열 허용: True null 허용: False 예: -1가져오기 또는 입력 방법: 호출자가 유효 기간을 Unix 초 단위로 선택합니다. -1은 영구이며, 현재 시간에 원하는 유효 초를 더해 사용하십시오. |
|
| extractionCode | string | 선택적 문자열이며, 생략/빈 값이면 추출 코드를 추가하지 않습니다. DF-API-KEY 또는 공유 최초 진입 authCode가 아닙니다. 서버에 추출 코드가 저장되므로 공개 로그에 기록하지 마십시오. 빈 문자열 허용: True null 허용: False 최대 길이: 12 예: read123가져오기 또는 입력 방법: 호출자가 1–12자 추출 코드를 생성하고 통제된 채널을 통해 수신자에게 알립니다. |
|
| hiddenTopBar | boolean | 선택적 불리언이며, 기본값은 false이고 Body가 호환되는 Query 값을 덮어씁니다. 페이지 상단 표시줄만 제어하며 인증이 아닙니다. null 허용: False 예: false가져오기 또는 입력 방법: 공유 페이지 표시 요구 사항에 따라 선택하십시오. |
|
| showWatermark | boolean | 선택적 불리언이며, UI 기본값은 false입니다. 워터마크는 데이터 액세스 제한을 대체하지 않습니다. null 허용: False 예: false가져오기 또는 입력 방법: 공유 표시 필요에 따라 선택하십시오. |
파라미터 추가 설명¶
스냅샷은 페이지 구성과 서버 측 쿼리 범위를 저장합니다. 인터넷 공유를 위해서는 공유 구성을 별도로 생성해야 하며, snap_, share_, 최초 진입 코드와 2단계 token은 서로 다른 식별자입니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/snapshots/snap_example/share' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"expirationAt":-1,"extractionCode":"read123","changeTime":false,"hiddenTopBar":false,"showWatermark":true,"ipWhitelistSet":{"isOpen":true,"type":"custom","ipWhitelist":["192.0.2.0/24"]}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 공유 생성 결과이며, share_ 구성 UUID/전체 스냅샷을 포함하지 않습니다. |
| content.token | string | 장기 최초 진입 코드 호환 필드이며 authCode와 동일합니다. 2단계 쿼리 token이 아닙니다. |
| content.authCode | string | 동일한 장기 최초 진입 코드입니다. 콘솔 /share/{code}에 액세스하며, 유효 기간은 공유 구성을 따릅니다. |
| content.shortUrl | string | 생성된 단축 링크의 전체 URL이며, 비활성화/미반환 시 비어 있으므로 콘솔의 원래 공유 주소를 사용해야 합니다. |
| content.isHidden | boolean | 이 공개 생성에서는 false이며, isHidden 입력을 받지 않습니다. |
| content.declaration | object 또는 null | 현재 워크스페이스의 공개 선언입니다. |
{
"code": 200,
"content": {
"token": "SHARE-LINK-CODE",
"authCode": "SHARE-LINK-CODE",
"shortUrl": "",
"isHidden": false,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 문법이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | 요청 JSON의 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 공유 파라미터 객체를 제출하십시오. |
| 404 | ft.ObjectNotExists | 현재 워크스페이스의 대상 스냅샷이 존재하지 않음/삭제됨 | 지정한 객체가 존재하지 않음 | 이 워크스페이스의 스냅샷 목록에서 snap_ UUID를 다시 가져오십시오. |
| 401 | ft.WKSPNotExistOrReleased | 공유 생성 시 현재 활성 워크스페이스 검증 실패/워크스페이스 해제됨 | 워크스페이스가 존재하지 않음/또는 해제됨 | 먼저 현재 Key 워크스페이스의 활성 상태를 확인하십시오. 브랜드 주소만 구성하는 NotFoundWorkspace와 달리 기존 페이지 링크로 워크스페이스가 여전히 유효함을 증명하는 데 의존하지 않습니다. |
| 403 | ft.ForbiddenFreeWKSPSnapshotShare | 현재 워크스페이스가 스냅샷 공유를 지원하지 않는 무료 버전임 | 무료 플랜 워크스페이스에서는 스냅샷 공유가 금지됨 | 관리자가 제품 버전을 확인해야 하며, isHidden 등 비공개 파라미터로 우회하지 마십시오. |
| 403 | ft.ShareTokenInvalid | 사전에 스냅샷을 조회한 후 공유 생성이 리소스를 다시 읽을 때 이미 무효화됨 | 공유 리소스가 이미 무효화됨 | 스냅샷 상태를 새로고침하고 삭제되었는지 확인하십시오. |
| 406 | ft.NotFoundWorkspace | 브랜드/사용자 정의 도메인으로 콘솔 주소를 구성할 때 워크스페이스가 존재하지 않음 | 지정한 워크스페이스를 찾을 수 없음 | 관리자가 Key 워크스페이스와 액세스 도메인 구성을 확인하십시오. |
| 400 | ft.ErrorRegularExpression | maskCfg.reExprs의 모든 정규식 중 컴파일할 수 없는 항목이 있음(비활성화 항목 포함) | 정규식 오류 | 먼저 모든 정규식을 검증하고 유효하지 않은 항목을 제거한 후 다시 생성하십시오. |
| 500 | ft.InternalServerError | 이전 스냅샷의 content/meta 구조, 공유/최초 진입 자격 증명 쓰기, 단축 링크 생성 또는 제출 후 자격 증명 캐시 동기화 중 처리되지 않은 예외 발생 | 내부 오류 | 먼저 콘솔 공유 관리에서 생성 여부를 확인한 후 재시도 여부를 결정하여 여러 유효한 공유가 생성되는 것을 피하십시오. traceId를 보관하여 위치를 파악하십시오. |