콘텐츠로 이동

조회



GET /api/v1/workspace/declaration/get

개요

현재 워크스페이스 속성 클레임을 읽고, 필요한 경우 조직 정보 백그라운드 동기화를 트리거합니다.

호출 전 및 사용 단계

대상 워크스페이스의 API Key를 사용합니다. 워크스페이스는 Key로 결정되며, Query 또는 Body에 workspaceUUID를 별도로 전달할 수 없습니다. 워크스페이스 클레임은 비즈니스 식별 및 응답 표시에 사용되는 키-값 구성이며, 데이터 액세스 권한 부여, 과금 조직 마이그레이션 또는 리소스 이름 변경 인터페이스가 아닙니다.

content 최상위의 클레임 키를 읽습니다. 비어 있지 않은 객체에는 공용 OpenAPI 응답이 content.declaration을 추가합니다(호출 워크스페이스 캐시의 공용 클레임). 이는 이 페이지에서 새로 추가된 또 다른 계층의 비즈니스 객체가 아니며, 전체 응답 셸이나 이 보조 필드를 그대로 다시 기록해서는 안 됩니다. 기존 구성에서 declaration과 동일한 이름의 키를 직접 사용한 경우 원래 값이 반환될 수 있으므로, 사용자 정의 키는 declaration/organization/business/data/pageInfo 등 예약된 의미를 피하는 것이 좋습니다. 기존 사용자 정의 필드에 data와 pageInfo가 동시에 포함된 경우 공용 래퍼가 pageInfo를 응답 최상위로 이동합니다. 이는 인터페이스 페이징을 의미하지 않으며, 이동된 필드를 버린 후 무작정 다시 기록해서도 안 됩니다. 빈 클레임은 {}을 반환할 수 있고, 기존 비유료 구성은 null일 수도 있으며, 항상 business 또는 organization이 있다고 보장하지 않습니다.

pay/enterprise 워크스페이스는 조직 정보를 실시간으로 보완하려고 시도하며, 실패하면 저장된 값을 그대로 사용할 수 있습니다. 차이가 있으면 백그라운드 동기화도 트리거하므로 이 GET은 완전히 부작용이 없는 것은 아닙니다. 백그라운드 동기화는 이번 응답에서 작업 ID 또는 완료 진행률을 제공하지 않습니다. 비동기 큐를 사용할 수 없으면 읽기가 500을 반환할 수도 있습니다. 다른 버전은 저장된 클레임을 직접 반환하며 동일한 보완 수행을 보장하지 않습니다. 비즈니스 문자열 표시는 실제 반환값에 따라 읽어야 하며, business를 고정 배열로 간주해서는 안 됩니다.

요청 헤더

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

요청 예시

curl --get 'https://openapi.guance.com/api/v1/workspace/declaration/get' \
  -H 'DF-API-KEY: <DF-API-KEY>'

응답

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

필드 유형 설명
content object 또는 null 클레임 키-값 객체입니다. 빈 구성은 {}일 수 있고, 일부 기존 비유료 레코드는 null일 수 있습니다.
content.organization string 또는 null 시스템이 유지 관리하는 조직 식별자이며 생략될 수 있습니다. 유료/엔터프라이즈 버전은 조직 정보에서 가져옵니다. 배포 플랜에서는 수정 사항이 default_private_organization으로 저장됩니다. 워크스페이스 UUID와 같지 않으며, 이 인터페이스로 대상 조직을 지정할 수 없습니다.
content.business 임의의 기존 JSON 값 비즈니스 속성이며 생략될 수 있습니다. pay/enterprise 읽기와 현재 수정에서는 문자열로 정규화되지만, 비유료 GET은 기존 배열/null 등을 그대로 반환할 수 있으므로 고정적으로 string으로 파싱해서는 안 됩니다.
content.{사용자 정의 키} 임의의 기존 JSON 값 사용자 정의 키이며 실제 키에 따라 읽습니다. 현재 수정에서는 문자열이 아닌 값을 JSON 문자열로 변환하지만, 기존 저장 값에는 여전히 다른 유형이 있을 수 있습니다.
pageInfo 임의의 기존 JSON 값 클레임에 원래 data/pageInfo가 동시에 포함된 경우에만 공용 래퍼에 의해 최상위로 이동되며, 이 인터페이스의 페이징이 아닙니다.
content.declaration object 또는 null 또는 기존 사용자 정의 값 비어 있지 않은 객체에 추가될 수 있는 공용 클레임입니다. 최상위에서 읽는 소스/새로 고침 시점과 다를 수 있습니다. 같은 이름의 사용자 정의 필드가 유지되는 경우 덮어쓰지 않습니다.
{
  "code": 200,
  "content": {
    "organization": "organization_example",
    "business": "checkout",
    "costCenter": "platform",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공용 요청 오류는 공용 오류 정의를 참조하세요.

공용 인증, 허용 목록, 속도 제한 오류는 공용 오류 정의를 참조하세요. 실시간 조직 정보 읽기 예외는 먼저 저장된 값으로 폴백되므로, 조직 업스트림 오류가 발생할 때마다 이를 이 인터페이스의 실패로 간주해서는 안 됩니다. 이후 비동기 전송 예외로 인해 여전히 500이 발생할 수 있습니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방식
401 ft.WKSPNotExistOrReleased API Key가 가리키는 워크스페이스에 유효한 레코드가 없거나 해제됨 워크스페이스가 존재하지 않거나 해제됨 Key 소유권 및 워크스페이스 상태를 확인합니다.
500 ft.InternalServerError 클레임 저장 형식 비호환, 읽기 실패 또는 비동기 동기화 작업 전송 실패 내부 오류 traceId를 보관하고 관리자에게 문의하며, 나중에 다시 읽고, 이번 결과만으로 백그라운드 작업이 완료되었다고 추론하지 않습니다.

문서 평가

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