대량 사용자 관리 엔드포인트

일괄 관리 API 엔드포인트를 사용하면 일괄 사용자 관리 컬렉션을 통해 다수의 사용자를 생성하거나 업데이트할 수 있습니다.

API는 JSON 파일 사용을 지원합니다. 템플릿 API를 사용하여 JSON 데이터를 가져올 수 있습니다.

api_user 인증만 지원됩니다. 비밀번호 변수에 API 사용자 토큰을 입력해야 합니다. 회사 보안 비밀을 사용하는 기존 인증은 지원되지 않습니다.

업로드 API를 통해 JSON 파일을 업로드하면 작업이 생성되고 JSON 파일 스키마가 검증됩니다.

일괄 사용자 관리에 지원되는 엔드포인트는 다음과 같습니다.

일괄 사용자 API를 사용하여 사용자를 일괄 추가하거나 업데이트하려면 다음 단계를 따르세요.

  1. Template 메서드를 호출하여 JSON 파일을 생성하는 데 사용할 JSON 템플릿 객체를 가져옵니다.

  2. 일괄 추가를 수행하는지 일괄 업데이트를 수행하는지에 따라 파일에서 사용자 일괄 추가 메서드 또는 파일에서 사용자 일괄 업데이트 메서드를 호출합니다. 제공한 JSON 파일의 스키마를 확인합니다.

  3. JSON 파일 스키마가 확인되면 Proceed 메서드를 호출합니다. 이렇게 하면 작업이 시작됩니다.

  4. 작업 상태를 확인하려면 Jobs 메서드를 호출합니다.

JSON 파일 형식

템플릿 메서드를 호출하여 JSON 파일 형식을 가져올 수 있습니다.

필드 이름 값 필수 유효성 검사
이메일 문자열(이메일) 예 유효한 이메일이어야 합니다. 이메일 열 내 파일에서 고유해야 합니다 (중복 없음). 따라서 파일당 이메일 주소당 업데이트는 1개만 허용됩니다.
new_email 문자열(이메일) 아니요 유효한 이메일이어야 합니다. '새 이메일' 열의 파일 내에서 고유해야 합니다 (중복 없음). 따라서 파일당 이메일 주소당 업데이트는 1개만 허용됩니다.
agent_number 문자열 아니요 검증이 없는 문자열
이름 문자열 예 비어 있지 않은 문자열
성 문자열 예 비어 있지 않은 문자열
상태 활성, 비활성, 비어 있음 아니요 '활성', '비활성' 또는 비어 있어야 합니다.
위치 위치 이름인 문자열, Empty, Null 아니요 기존 위치 중 하나와 정확히 일치해야 합니다 (대소문자 구분 안 함). Null 또는 비어 있어도 됩니다.
max_chat_limit 1~X (X는 구성된 값), Empty 아니요 1~X (포함) 또는 비워야 합니다.
max_chat_limit_enabled 0, 1, Empty 아니요 0, 1 또는 비어 있어야 합니다.
역할 name: 역할 이름 / value: 0, 1, Empty 아니요 0, 1 또는 비어 있어야 합니다.
팀 name: 팀 이름 / value: 0, 1, Empty 아니요 0, 1 또는 비어 있어야 합니다.

JSON 파일 업로드 API 메서드가 성공하면 API 진행 메서드를 호출할 수 있으며, 사용자 생성 또는 수정 작업이 처리됩니다.

업로드 및 진행 메서드는 Contact Center AI Platform (CCAI Platform)에 의해 비동기적으로 실행됩니다. jobs 메서드를 호출하고 job_id를 지정하여 상태를 확인할 수 있습니다.

상태 필드

작업 status 필드에는 다음 값이 포함될 수 있습니다.

작업 상태 설명
생성됨 작업이 생성되었으며 검증을 기다리는 중입니다.
valid_scheme 스키마 유효성 검사가 성공했으며 진행이 가능합니다.
invalid_scheme 스키마 검사에 실패했습니다. 자세한 정보는 스키마 오류 로그 API를 통해 확인할 수 있습니다.
in_progress 사용자를 일괄 업데이트/생성하는 중입니다.
완료됨 사용자 일괄 업데이트/생성이 완료되었습니다.

템플릿

엔드포인트:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

템플릿 가져오기

이 예시에서는 템플릿을 가져오는 방법을 보여줍니다.

요청

본문: 없음

대답: 템플릿
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

상태 코드: 200

작업

엔드포인트:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

작업 세부정보

이 예에서는 특정 작업의 작업 세부정보를 가져오는 방법을 보여줍니다. 이 예시에서 작업 ID는 1입니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 작업 세부정보
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

상태 코드: 200

작업 목록

이 예시에서는 모든 작업을 가져오는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
응답: 작업 목록
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

상태 코드: 200

작업 생성됨

이 예시에서는 생성된 대량 사용자 요청 작업을 가져오는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 작업 생성됨
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

상태 코드: 200

작업 유효성 검사 성공

이 예시에서는 작업이 성공했는지 확인하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 작업 유효성 검사 성공
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

상태 코드: 200

작업 유효성 검사 실패

이 예시에서는 실패한 작업을 확인하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 작업 유효성 검사 실패
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

상태 코드: 200

작업 업데이트

이 예시에서는 업데이트 중인 작업을 확인하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
대답: 채용 정보 업데이트
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

상태 코드: 200

오류 없이 채용 정보 업데이트 완료

이 예에서는 오류 없이 완료된 작업을 식별하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 오류 없이 채용 정보 업데이트 완료
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

상태 코드: 200

오류로 인해 작업 업데이트가 완료됨

이 예에서는 오류로 완료된 작업을 식별하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 작업 업데이트가 오류와 함께 완료됨
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

상태 코드: 200

오류: 잘못된 작업 ID

이 예시에서는 작업 ID가 잘못된 실패 요청을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type application/json

질문:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
응답: 오류: 잘못된 작업 ID
{
    "message": "Not Found"
}

상태 코드: 404

파일에서 사용자 일괄 추가 및 수정

헤더:

키 값 설명
Content-Type multipart/form-data

엔드포인트:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

본문:

키 값 설명
파일

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

작업 생성됨

이 예시에서는 작업을 제출하는 방법을 보여줍니다.

요청

본문:

키 값 설명
파일
응답: 작업 생성됨
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

상태 코드: 200

계속

이 API 엔드포인트는 시작된 ipport 작업을 계속하는 데 사용됩니다.

엔드포인트:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

헤더:

키 값 설명
Content-Type multipart/form-data

본문:

키 값 설명
id `[job_id}`

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

진행 성공

이 예에서는 성공한 작업 진행을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type multipart/form-data

질문:

키 값 설명
id `[job_id}`
응답: 진행 성공
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

상태 코드: 200

오류: 유효성 검사 전에 진행

이 예시에서는 유효성 검사가 완료되기 전에 진행하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type multipart/form-data

질문:

키 값 설명
id `[job_id}`
응답: 오류: 유효성 검사 전에 진행
{
    "message": "This job cannot proceed update. status: created"
}

상태 코드: 400

오류: 진행 중일 때 계속

이 예에서는 작업이 이미 진행 중일 때 계속 진행하는 방법을 보여줍니다.

요청

헤더:

키 값 설명
Content-Type multipart/form-data

질문:

키 값 설명
id `[job_id}`
대답: 오류: 진행 중일 때 계속 진행
{
    "message": "Update is already in progress."
}

상태 코드: 400

스키마 오류

엔드포인트:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

스키마 오류

이 예시에서는 스키마 오류를 가져오는 방법을 보여줍니다.

요청

본문: 없음

대답: 스키마 오류
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

상태 코드: 200

오류 없음

이 예시에서는 오류 없이 스키마 오류를 가져오는 방법을 보여줍니다.

요청

본문: 없음

대답: 오류 없음
[]

상태 코드: 200

업데이트 오류

엔드포인트:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

요청 및 응답 예시

다음 섹션에서는 엔드포인트에 대한 요청의 예를 제공합니다.

업데이트 오류

이 예시에서는 업데이트 오류와 함께 스키마 오류를 가져오는 방법을 보여줍니다.

요청

본문: 없음

응답: 업데이트 오류
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

상태 코드: 200

오류 없음

이 예시에서는 오류 없이 스키마 오류를 가져오는 방법을 보여줍니다.

요청

본문: 없음

대답: 오류 없음
[]

상태 코드: 200