Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

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	위치	위치 이름인 문자열, 비어 있음 (변경사항 없음), Null (현재 위치 삭제)
8	동시 채팅	1	동시 채팅	1~X (X는 구성된 값), 비어 있음
9	동시 채팅 상태	1	동시 채팅 상태	0, 1, 비어 있음
10	제한 없는 국제 전화	1	제한 없는 국제 전화	(True/False)
11	외부 사용자	1	외부 사용자	(예/아니요)
12	외부 SIP URI	1	외부 SIP URI	문자열
13	UCaaS 사용자 이름	1	UCaaS 사용자 이름	문자열
14	상담사 확장 프로그램	1	상담사 확장 프로그램
15	역할	다수	역할: 역할 이름 A 역할: 역할 이름 B 역할: 역할 이름 C 등	0, 1, 비어 있음
16	팀	다수	팀: 팀 이름 A, 팀: 팀 이름 B, 팀: 팀 이름 C 등	0, 1, 비어 있음
17	전화번호	다수	직접 수신 번호: 1, 직접 수신 번호: 2, 직접 수신 번호: 3	전화번호(E. 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"
    ]
  },
  ...
]

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