사용자 구성 데이터 가져오기

Apps API는 사용자 구성 데이터를 가져오도록 설계되었습니다. 역할이나 상태와 관계없이 모든 사용자 또는 단일 사용자의 현재 사용자 구성을 읽을 수 있습니다. 이 출력에는 시스템 역할과 맞춤 역할이 모두 포함됩니다.

이 엔드포인트는 대량 사용자 업로드 프로세스에 사용되는 엔드포인트와 다르며, 대량 작업을 지원하는 데 필요한 정보를 제공합니다. 사용자 일괄 관리 프로세스를 실행하는 방법에 관한 자세한 내용은 사용자 일괄 관리 API를 참고하세요.

API 기능 및 제한사항

사용자 데이터를 가져올 때 매개변수를 포함하여 필요에 맞게 API 응답을 조정할 수 있습니다. 지원되는 매개변수는 다음과 같습니다.

특정 사용자
- ID 옵션: 이메일, 시스템 ID 또는 맞춤 사용자 ID 사용자는 하나 이상의 ID를 지정할 수 있습니다. 여러 사용자 ID가 동일한 사용자를 가리키는 경우 해당 사용자는 응답에 한 번만 표시되어야 합니다.
페이지 나누기
- 사용자는 페이지로 나눈 세트로 결과를 가져와 대규모 데이터 세트를 관리할 수 있습니다. API 응답은 가져올 추가 페이지가 있는지 여부를 나타내야 합니다.
- API 매개변수를 사용하면 사용자가 특정 페이지의 결과를 요청할 수 있습니다.
- 사용자가 페이지 크기를 지정할 수 있습니다. 기본 페이지 크기는 100이고 최대 페이지 크기는 1,000입니다. 특정 페이지 번호가 제공되면 사용자 ID를 요청에 포함할 수 없습니다.

API 응답에는 '상태' 필드를 제외한 모든 사용자 프로필 및 구성 필드가 포함됩니다. '상태' 필드 대신 API에서 deactivated_at 필드를 제공합니다. 이 필드에는 다음이 포함됩니다.

활성 사용자 값이 없습니다.
사용자가 비활성화된 날짜와 시간입니다.

다음 표에는 API 응답에 포함될 사용자 프로필 필드가 나와 있습니다.

표 1. 사용자 프로필 필드 표

Order	열 유형	열 수	열 이름	유효한 값
1	이메일	1	이메일	이메일
2	에이전트 ID	1	에이전트 ID	문자열
3	이름	1	이름	문자열
4	성	1	성	문자열
5	별칭	1	별칭	문자열
6	비활성화된 시간	1	비활성화된 시간	값 없음, 날짜/시간
7	위치	1	위치	위치 이름인 문자열입니다. Empty (변경 없음), Null (현재 위치 삭제)
8	채팅 동시성	1	채팅 동시성	1~X (여기서 X는 구성된 값), Empty
9	채팅 동시 실행 상태	1	채팅 동시 실행 상태	0, 1, Empty
10	제한이 없는 국제 전화	1	제한이 없는 국제 전화	(참/거짓)
11	외부 사용자	1	외부 사용자	(예/아니요)
12	외부 SIP URI	1	외부 SIP URI	문자열
13	UCaaS 사용자 이름	1	UCaaS 사용자 이름	문자열
14	상담사 확장 프로그램	1	상담사 확장 프로그램
15	역할	다수	역할: 역할 이름 A 역할: 역할 이름 B 역할: 역할 이름 C 등	0, 1, Empty
16	팀	다수	팀: 팀 이름 A, 팀: 팀 이름 B, 팀: 팀 이름 C 등	0, 1, Empty
17	전화번호	다수	Direct Inbound Number: 1, Direct Inbound Number: 2, Direct Inbound Number: 3	전화번호가 164 형식
18	필터	단일	필터	문자열
19	필터 제한 시간	단일	필터 제한 시간	0~1,440 사이의 숫자 값

제한사항

요청당 하나의 사용자 ID 유형만 지원됩니다.
API 요청당 최대 ID 수는 1,000개입니다.
사용자는 단일 API 요청에서 사용자 ID와 페이지 번호 요청을 모두 제공할 수 없습니다. API는 요청에 따라 최대 1,000명의 모든 사용자를 반환합니다.

API 오류 메시지

API는 특정 시나리오에 대해 다음 오류 메시지를 제공합니다.

페이지 크기: '최대 페이지 크기 요청을 초과했습니다 (최대는 1,000)'
페이지 크기 (숫자 입력 요구사항): '잘못된 페이지 크기 요청입니다. 숫자 값이어야 합니다.'
사용자 ID와 페이지로 나누기 요청의 조합: '사용자 ID와 페이지로 나누기 요청의 조합은 지원되지 않습니다.'
사용자 ID (초과): '최대 사용자 ID 수 (최대 1,000개)를 초과했습니다.'

요청 및 응답 예시

이 예에서는 페이지당 100명의 사용자가 있는 첫 번째 사용자 페이지를 가져오는 방법을 보여줍니다. 응답 본문에는 자세한 사용자 구성 데이터가 포함된 사용자 객체의 배열이 포함됩니다.

요청:

Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100

대답:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

이 예시에서는 이메일 매개변수를 전달하여 단일 사용자의 세부정보를 검색하는 방법을 보여줍니다. 응답 본문에는 자세한 사용자 구성 데이터가 포함된 사용자 객체가 포함됩니다.