콘텐츠로 이동

매핑 구성 목록



GET /api/v1/login_mapping/field/list

개요

시스템 로그인 매핑과 현재 확인 가능한 워크스페이스 및 역할 이름을 페이지 단위로 조회합니다.

호출 전 및 사용 단계

기본적으로 본 서비스의 모든 워크스페이스에서 삭제되지 않은 시스템 매핑을 조회하며, workspaceUUID로 하나의 워크스페이스로 범위를 좁힐 수 있습니다. search는 역할 이름, 활성 워크스페이스 이름, 원본 필드 이름 및 원본 필드 값에 대해 포함 일치를 수행하며, 정확한 속성 조건 필터가 아닙니다. 업데이트 시간 기준 내림차순으로 정렬하며, 아직 업데이트되지 않은 경우 생성 시간을 사용합니다. 기본값은 pageIndex=1/pageSize=20이며 최대 100입니다. 규칙 대상 역할이 삭제된 경우 targetValues에 이전 UUID가 남아 있을 수 있으며, roles는 확인 가능한 유효 역할만 표시합니다. 확인 가능한 역할이 없으면 roles 필드가 생략될 수 있습니다.

요청 헤더

매개변수명 유형 필수 설명
X-Df-SVersion string 원본 경로와 요청 본문의 서명 버전입니다. 생략한 후 이 페이지의 알고리즘을 계속 사용할 수는 없습니다.
예시: v20240417
가져오기 또는 입력 방법: 본 페이지 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용합니다.
X-Df-Access-Key string Y 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API는 w 자격 증명이 필요합니다.
예시: <external-access-key>
가져오기 또는 입력 방법: 사이트 관리자가 External API AK를 할당하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다.
X-Df-Nonce string Y 임시 일련번호입니다. 실패 후 다시 전송할 때도 새 값을 생성하고 서명을 다시 계산합니다.
예시: 97d275ee9f774315a7885ba7347acbd9
가져오기 또는 입력 방법: 매 요청마다 uuid.uuid4().hex를 새로 생성합니다.
X-Df-Signature string Y 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다.
예시: <hmac-sha256-hex>
가져오기 또는 입력 방법: External API 서명 인증에 따라 함께 제공된 SK로 계산하며, 전체 실행 가능한 템플릿은 아래에서 확인할 수 있습니다.
X-Df-Timestamp string Y 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다.
예시: 1785427200
가져오기 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다.

Query 요청 매개변수

매개변수명 유형 필수 설명
pageIndex integer 기본값 1, 최소 1입니다.
null 허용: False
$minValue: 1
예시: 1
가져오기 또는 입력 방법: 1부터 시작하며, content.pageInfo에 따라 다음 페이지로 진행합니다.
pageSize integer 기본값 20, 최대 100입니다.
null 허용: False
$maxValue: 100
$minValue: 1
예시: 20
가져오기 또는 입력 방법: 클라이언트 표시에 따라 1~100에서 선택합니다.
search string 선택 사항이며, 앞뒤 공백을 제거한 후 포함 일치를 수행합니다. 여러 유형 중 하나라도 일치하면 되고, 생략하거나 공백만 있으면 필터링하지 않습니다.
null 허용: False
예시: 研发部
가져오기 또는 입력 방법: 원본 속성 이름, 값, 역할 이름 또는 워크스페이스 이름의 키워드를 사용합니다.
workspaceUUID string 선택 사항이며, 생략하거나 빈 문자열이면 모든 워크스페이스의 시스템 규칙을 조회하고 특정 워크스페이스를 자동으로 선택하지 않습니다.
null 허용: False
예시: wksp_example001
가져오기 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 가져옵니다.

매개변수 추가 설명

인증 방식은 External API 서명 인증을 참조하세요. 본 모듈은 사이트 시스템 로그인 매핑(isSystem=1)을 관리하며, OIDC/LDAP 등 공유 로그인 매핑 경로를 사용하는 타사 로그인에서 사용됩니다. 워크스페이스 사용자 지정 매핑 또는 독립 SAML 설정 API가 아닙니다. 구성 저장 시 모든 기존 사용자 권한이 즉시 일괄 재계산되지는 않으며, 이후 관련 로그인 시 모드에 따라 처리됩니다.

요청 예시

import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen

# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/login_mapping/field/list'
query = {'workspaceUUID': 'wksp_example001', 'search': '研发部', 'pageIndex': 1, 'pageSize': 20}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
    "X-Df-Access-Key": access_key,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-Signature": signature,
    "X-Df-SVersion": "v20240417",
}
if data is not None:
    headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
    print(result.read().decode("utf-8"))

응답

HTTP 200, application/json 통합 응답 래퍼입니다. External은 declaration을 자동으로 주입하지 않으며, 목록 페이지네이션은 content.pageInfo에 있습니다.

필드 유형 설명
content.data 객체 배열 이 페이지의 삭제되지 않은 시스템 매핑이며, 결과가 없으면 []입니다.
content.data[].id integer 또는 null 레코드 번호입니다. 생성 스냅샷에서는 null일 수 있으며, 작업에는 uuid를 사용합니다.
content.data[].uuid string 매핑 레코드 UUID이며, 일반적으로 lgmp_ 접두사가 붙습니다.
content.data[].status integer 규칙 상태이며 활성은 0입니다. 목록에서는 3을 필터링하지만 과거의 다른 상태가 포함될 수 있으며, 실제 로그인 소비 및 수정/삭제는 0만 처리합니다.
content.data[].creator string 생성 주체이며, External은 일반적으로 sys입니다.
content.data[].updator string 업데이트 주체이며, 업데이트되지 않은 경우 비어 있을 수 있습니다.
content.data[].createAt integer 생성 Unix 초입니다.
content.data[].deleteAt integer 삭제 Unix 초이며, 삭제되지 않은 경우 일반적으로 -1입니다.
content.data[].updateAt integer 업데이트 Unix 초이며, 아직 수정되지 않은 경우 일반적으로 -1입니다.
content.data[].sourceField string 일치 대상인 원본 userinfo 최상위 속성 이름입니다.
content.data[].sourceValue string 일치 대상인 속성 문자열 값입니다.
content.data[].targetValues 문자열 배열 저장된 대상 역할 UUID 목록이며, 과거 목록 항목만으로 역할이 여전히 유효하다고 직접 단정할 수 없습니다.
content.data[].targetValues[] string 단일 대상 역할 UUID입니다.
content.data[].workspaceUUID string 이 규칙의 대상 워크스페이스 UUID입니다.
content.data[].isSystem integer 또는 boolean 본 모듈은 시스템 매핑이므로 1 또는 true입니다. 워크스페이스 사용자 지정 규칙이 아닙니다.
content.data[].workspaceName string 또는 null 현재 활성 워크스페이스 이름이며, 워크스페이스가 유효하지 않거나 삭제되었거나 확인할 수 없을 때 null일 수 있습니다.
content.data[].roles 객체 배열 선택적 역할 요약이며, 확인 가능한 역할이 없으면 생략될 수 있습니다. targetValues와 다릅니다.
content.data[].roles[].uuid string 유효한 역할 UUID입니다.
content.data[].roles[].name string 유효한 역할 이름입니다.
content.pageInfo.pageIndex integer 현재 페이지 번호입니다.
content.pageInfo.pageSize integer 페이지당 개수입니다.
content.pageInfo.count integer 이 페이지의 건수입니다.
content.pageInfo.totalCount integer 필터 조건의 총 개수입니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "id": 1001,
        "uuid": "lgmp_example001",
        "status": 0,
        "creator": "sys",
        "updator": "",
        "createAt": 1785427200,
        "deleteAt": -1,
        "updateAt": -1,
        "sourceField": "department",
        "sourceValue": "研发部",
        "targetValues": [
          "readOnly"
        ],
        "workspaceUUID": "wksp_example001",
        "isSystem": 1,
        "workspaceName": "示例空间",
        "roles": [
          {
            "uuid": "readOnly",
            "name": "ReadOnly"
          }
        ]
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 20,
      "count": 1,
      "totalCount": 1
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

일치하는 규칙이 없을 때:

{
  "code": 200,
  "content": {
    "data": [],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 20,
      "count": 0,
      "totalCount": 0
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

확인된 규칙 및 요청 오류는 표에 나열되어 있습니다. 일반 데이터베이스/캐시/감사 예외는 최종적으로 500 ft.InternalServerError입니다. 구성이 이미 제출된 후 후속 오류가 발생할 수 있으므로, 먼저 현재 상태를 읽은 후 재시도하세요.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방식
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. 매개변수 파싱 실패 매개변수 위치, 필드 이름, 유형 및 값을 확인하세요.
500 ft.InternalServerError 데이터베이스, 사이트 구성 캐시, 감사 또는 처리되지 않은 과거 데이터 예외 내부 오류 traceId를 보관하고 먼저 규칙 또는 스위치를 읽어 현재 상태를 확인하세요. 데이터베이스와 캐시/감사는 동일한 트랜잭션이 아니므로, 오류가 완전히 저장되지 않았음을 증명하지는 않습니다.

문서 평가

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