AWA 에이전트 API

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기34분

    • AWA(고급 작업 할당) 에이전트 API는 에이전트 현재 상태, 채널 가용성 및 작업 부하를 관리하는 엔드포인트를 제공합니다.

    이 API에는 고급 작업 할당 (com.glide.awa) 플러그인과 awa_integration_user 역할이 필요합니다. 자세한 내용은 고급 작업 할당을 참조하십시오.

    AWA 에이전트 - GET /now/awa/agents/{user_id}

    현재 에이전트 현재 상태 및 채널 가용성을 반환합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/awa/agents/{user_id}

    기본 URL: /api/now/awa/agents/{user_id}

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 작업 항목의 Sys_id입니다.
    작업 항목은 다음 기준을 충족해야 합니다.
    • 지정된 에이전트에 작업 항목을 할당해야 합니다.
    • 작업 항목은 수락 보류 중 상태여야 합니다.

    데이터 유형: 문자열

    테이블: AWA 작업 항목 [awa_work_item]
    표 2. 쿼리 매개변수
    이름 설명
    안 함
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    머리글 설명
    presence.channels.available 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 채널을 사용할 수 있습니다.
    • false: 채널을 사용할 수 없습니다.

    데이터 유형: 부울
    presence.channels.sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    presence.sys_id 현재 상태 sys_id.

    데이터 유형: 문자열

    테이블: 현재 상태 [awa_presence_state]

    머리글

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    컨텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다.
    가능한 이유:
    • 사용자에게 awa_integration_user 역할이 없습니다.
    • glide.awa.enabled 속성의 값이 예가 아닙니다. 이 속성은 고급 작업 할당(com.glide.awa) 플러그인이 설치된 경우 시스템 속성 [sys_property] 테이블에 나열됩니다. 자세한 내용은 고급 작업 할당과 함께 설치되는 구성 요소를 참조하십시오.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    표 7. 응답 본문 매개변수(JSON 또는 XML)
    매개변수 설명
    오류 요청 프로세스 중에 발생한 오류를 설명하는 상세 정보입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 요청 프로세스 중에 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 요청 프로세스 중에 발생한 오류에 대한 메시지입니다. 각 오류 메시지에는 속성에 해당 설명이 detail 있습니다.
    가능한 값:
    • 기록을 찾을 수 없음: 요청 본문에 제공된 정보가 정확하지 않거나 존재하지 않습니다.
    • 사용자가 인증되지 않음: 사용자에게 awa_integration_user 역할이 없습니다.

    데이터 유형: 문자열
    presence 에이전트의 현재 상태 및 채널에 대한 정보입니다.

    데이터 유형: 객체

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presence.available 에이전트를 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 에이전트를 사용할 수 있습니다.
    • false: 에이전트를 사용할 수 없습니다.

    데이터 유형: 부울
    presence.channels 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다.

    데이터 유형: 객체 배열

    "channels": [
  {
    "available": Boolean,
    "name": "String",
    "sys_id": "String"
  }
]
    presence.channels.available 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 채널을 사용할 수 있습니다.
    • false: 채널을 사용할 수 없습니다.

    데이터 유형: 부울
    presence.channels.name 채팅 또는 전화 같은 채널 이름입니다.

    데이터 유형: 문자열
    presence.channels.restrict_update 사용자가 업데이트를 제한할 수 있는지 여부를 나타내는 플래그입니다(즉, 가용성에 대한 채널 선택).
    가능한 값:
    • true: 사용자가 가용성을 위해 이 채널을 선택할 수 있습니다.
    • false: 사용자가 가용성을 위해 이 채널을 선택할 수 없습니다.

    데이터 유형: 부울
    presence.channels.service_channel_type 채팅과 같은 서비스 채널 유형입니다. 가능한 값은 설치된 플러그인에 따라 다릅니다.

    데이터 유형: 문자열
    presence.channels.sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    presence.name 에이전트의 현재 상태 이름입니다.
    가능한 값:
    • 사용 가능
    • 사용할 수 없음

    데이터 유형: 문자열
    presence.restrict_update 사용자가 업데이트를 제한할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 사용자가 업데이트를 제한할 수 있습니다.
    • false: 사용자가 업데이트를 제한할 수 없습니다.

    데이터 유형: 부울
    presence.sys_id 현재 상태 sys_id.

    데이터 유형: 문자열

    테이블: 현재 상태 [awa_presence_state]
    상태 실패한 요청의 상태입니다. 이 속성은 오류가 있는 경우에만 응답에 포함됩니다.

    유효한 값: failure

    데이터 유형: 문자열
    sys_id 에이전트 sys_id입니다.

    데이터 유형: 문자열
    workItem

    workItem: 이벤트와 연결된 작업 항목에 대한 정보입니다.

    데이터 유형: 문자열
    작업 항목.문서 workItem.document: 작업 항목 작업과 연결된 문서의 목록입니다.

    데이터 유형: 문자열
    workItem.document.sys_id workItem.document.sys_id: 작업 항목 작업에 할당된 문서의 Sys_id입니다.

    데이터 유형: 문자열
    작업 항목.문서.테이블 workItem.document.table: 작업에 할당된 문서 테이블의 이름입니다.

    데이터 유형: 문자열
    workItem.previousWorkItem workItem.previousWorkItem: 동일한 문서 ID에 대한 이전 작업 항목의 Sys_id입니다. 전송되지 않은 작업 항목의 경우 이 값은 비어 있습니다.

    데이터 유형: 문자열
    workItem.serviceChannel workItem.serviceChannel: 작업 항목 작업과 연결된 서비스 채널의 목록입니다.

    데이터 유형: 문자열
    workItem.serviceChannel.name workItem.serviceChannel.name: 채팅 또는 전화와 같은 서비스 채널의 이름입니다.

    데이터 유형: 문자열
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: 서비스 채널의 Sys_id입니다.

    데이터 유형: 문자열
    작업 항목.크기 workItem.size: 이 작업 항목이 에이전트에 할당될 때 사용되는 에이전트의 용량입니다.

    데이터 유형: 문자열
    workItem.sys_id workItem.sys_id: 수락되거나 제안된 작업 항목의 Sys_id입니다.

    데이터 유형: 문자열
    workItem.isQueueTransferred workItem.isQueueTransferred: 작업 항목이 큐 전송되었는지 여부를 나타내는 플래그입니다. 작업 항목이 큐로 전송되면 true로 설정하고, 그렇지 않으면 false로 설정합니다. 큐 전송에 대한 자세한 내용은 다음 문서를 참조하십시오 Transfer a chat to another queue.

    데이터 유형: 부울
    workitem.isAutoAccepted workItem.isAutoAccepted: 시스템에서 작업 항목을 자동으로 수락했는지 여부를 나타내는 플래그입니다. 작업 항목이 자동으로 수락된 경우 true로 설정합니다.

    데이터 유형: 부울

    샘플 cURL 요청

    curl -X GET \
https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
    {
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

    AWA 에이전트 - GET /now/awa/agents/{user_id}/capacities

    에이전트의 채널 용량, 범용 용량 및 현재 작업 부하를 반환하여 에이전트가 케이스를 처리할 수 있는지 확인합니다.

    이 AWA 에이전트 - PUT /now/awa/agents/{user_id}/capacities 방법을 사용하여 에이전트의 채널 및 범용 용량을 수정합니다.

    참조:

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/awa/agents/{user_id}/capacities

    기본 URL: /api/now/awa/agents/{user_id}/capacities

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 8. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 나열된 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 9. 쿼리 매개변수
    이름 설명
    안 함
    표 10. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    안 함

    머리글

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 11. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 12. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 13. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다.
    가능한 이유:
    • 사용자에게 awa_integration_user 역할이 없습니다.
    • glide.awa.enabled 속성의 값이 예가 아닙니다. 이 속성은 고급 작업 할당(com.glide.awa) 플러그인이 설치된 경우 시스템 속성 [sys_property] 테이블에 나열됩니다. 자세한 내용은 고급 작업 할당과 함께 설치되는 구성 요소를 참조하십시오.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    채널 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다. 
    "channels": [
  {
    "channel_sys_id": "String",
    "current_workload": Number,
    "max_capacity": Number
  }
]

    데이터 유형: 배열
    channels.channel_sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    channels.current_workload 현재 에이전트에 할당된 특정 서비스 채널의 작업 항목 수입니다.

    데이터 유형: 숫자
    channels.max_capacity 에이전트를 한 번에 능동적으로 할당할 수 있는 특정 서비스 채널의 최대 작업 부하입니다.

    데이터 유형: 문자열
    오류 요청 프로세스 중에 발생한 오류를 설명하는 상세 정보입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 요청 프로세스 중에 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 요청 프로세스 중에 발생한 오류에 대한 메시지입니다. 설명은 속성에 제공됩니다 error.detail .

    데이터 유형: 문자열
    상태 실패한 요청의 상태입니다. 이 속성은 오류가 있는 경우에만 응답에 포함됩니다.

    유효한 값: failure

    데이터 유형: 문자열
    universal_capacity 모든 서비스 채널에서 에이전트의 최대 용량입니다. 에이전트의 현재 워크로드가 최대 범용 용량과 같으면 추가 작업 항목이 에이전트에 할당되지 않습니다.

    이 속성은 이 에이전트에 대한 범용 용량 기록이 존재하는 경우에만 반환됩니다.

    데이터 유형: 숫자
    universal_workload 지정된 에이전트에 현재 할당된 모든 서비스 채널의 작업 항목 수입니다.

    이 속성은 에이전트에 대한 범용 용량 기록이 존재하는 경우에만 반환됩니다.

    데이터 유형: 숫자

    샘플 cURL 요청

    다음 예제에서는 사용자의 용량 및 작업 부하 값을 가져오는 방법을 보여 줍니다.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    성공적인 응답에는 각 채널에 대한 용량 값과 작업 부하가 포함됩니다.

    {
  "result": {
    "universal_workload": 2,
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "current_workload": 2,
        "max_capacity": 4
      }
    ],
    "universal_capacity": 10
  }
}

    AWA 에이전트 - GET /now/awa/agents/{user_id}/presence_states

    에이전트의 현재 상태를 반환하고 에이전트를 사용할 수 있는지 또는 다른 현재 상태인지 여부를 나타냅니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/awa/agents/{user_id}/presence_states

    기본 URL: /api/now/awa/agents/{user_id}/presence_states

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 14. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 나열된 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 15. 쿼리 매개변수
    이름 설명
    안 함
    표 16. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    안 함

    머리글

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 17. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 18. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 19. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다.
    가능한 이유:
    • 사용자에게 awa_integration_user 역할이 없습니다.
    • glide.awa.enabled 속성의 값이 예가 아닙니다. 이 속성은 고급 작업 할당(com.glide.awa) 플러그인이 설치된 경우 시스템 속성 [sys_property] 테이블에 나열됩니다. 자세한 내용은 고급 작업 할당과 함께 설치되는 구성 요소를 참조하십시오.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    오류 요청 프로세스 중에 발생한 오류를 설명하는 상세 정보입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 요청 프로세스 중에 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 요청 프로세스 중에 발생한 오류에 대한 메시지입니다. 설명은 속성에 제공됩니다 error.detail .

    데이터 유형: 문자열
    <현재 상태> 객체로서 에이전트의 현재 상태 정의 목록입니다. 각 객체는 상태를 설명하고 에이전트의 채널을 포함합니다.

    데이터 유형: 배열

    {
  "available": Boolean,
  "channels": [Array],
  "disable_inactivity_check": Boolean,
  "name": "String",
  "show_channels": Boolean,
  "sys_id": "String"
}
    <현재 상태>.사용 가능 에이전트를 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 에이전트를 사용할 수 있습니다.
    • false: 에이전트를 사용할 수 없습니다.

    데이터 유형: 부울
    <현재 상태>.channels 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다.

    데이터 유형: 배열

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "restrict_update": Boolean,
  "service_channel_type": "String",
  "sys_id": "String"
 }
]
    <현재 상태>.channels.available 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 채널을 사용할 수 있습니다.
    • false: 채널을 사용할 수 없습니다.

    데이터 유형: 부울
    <현재 상태>.channels.name 채팅 또는 전화 같은 채널 이름입니다.

    데이터 유형: 문자열
    <현재 상태>.channels.sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    <현재 상태>.disable_inactivity_check 이 현재 상태의 비활성 여부를 확인할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 현재 상태 비활성 검사가 비활성화되었습니다.
    • false: 현재 상태 비활성 확인을 사용합니다.

    데이터 유형: 부울

    기본값: false

    이 설정을 수정하는 방법에 대한 자세한 내용은 에이전트 현재 상태 구성을 참조하세요.
    <현재 상태>.name 에이전트의 현재 상태 이름입니다. 기본적으로 설치되는 현재 상태는 대화 가능, 자리 비움 및 오프라인입니다.

    데이터 유형: 문자열
    <현재 상태>.order 에이전트 받은 편지함에 이 상태가 표시되는 순서입니다.

    데이터 유형: 숫자
    <현재 상태>.show_channels 에이전트에게 현재 상태를 변경할 수 있는 권한이 있는지 여부를 나타내는 플래그입니다(예: 작업 가능에서 자리 비움으로).
    유효한 값은 다음과 같습니다.
    • true: 사용자에게 현재 상태를 변경할 수 있는 권한이 있습니다.
    • false: 사용자가 현재 상태를 변경할 수 없습니다.

    데이터 유형: 부울
    <현재 상태>.sys_id 현재 상태 sys_id.

    데이터 유형: 문자열

    테이블: 현재 상태 [awa_presence_state]
    상태 실패한 요청의 상태입니다. 이 속성은 오류가 있는 경우에만 응답에 포함됩니다.

    유효한 값: failure

    데이터 유형: 문자열

    샘플 cURL 요청

    다음 예시에서는 지정된 에이전트의 현재 상태를 가져오는 방법을 보여줍니다.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    응답 본문은 에이전트의 가능한 현재 상태를 나열하고 에이전트를 사용할 수 있음을 나타냅니다.

    {
  "result": [
    {
      "name": "Available",
      "order": 0,
      "show_channels": false,
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3",
          "restrict_update": false,
          "service_channel_type": "chat"
        }
      ],
      "disable_inactivity_check": false
    },
    {
      "name": "Away",
      "order": 1000,
      "show_channels": false,
      "sys_id": "41f9b8dfb31313005baa6e5f26a8dcac",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    },
    {
      "name": "Offline",
      "order": 2000,
      "show_channels": false,
      "sys_id": "9cd83267575313005baaaa65ef94f98b",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    }
  ]
}

    AWA 에이전트 - PUT /now/awa/agents/{user_id}

    지정된 에이전트의 현재 상태를 설정하고, 제공된 경우 해당 상태에 대한 에이전트의 채널 가용성을 설정합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/awa/agents/{user_id}

    기본 URL: /api/now/awa/agents/{user_id}

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 20. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 21. 쿼리 매개변수
    이름 설명
    안 함
    표 22. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    presence.channels 에이전트에서 사용할 수 있는 채널을 정의하는 객체의 목록입니다.
    데이터 유형: 객체 배열
    "channels": [
  { 
    "available": Boolean,
    "sys_id": "String"
  }
]
    presence.channels.available 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 채널을 사용할 수 있습니다.
    • false: 채널을 사용할 수 없습니다.
    주:
    응답 본문에 채널을 포함하도록 이 설정을 지정해야 합니다.

    데이터 유형: 부울

    기본값: false
    presence.channels.sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    presence.sys_id 현재 상태 sys_id.

    데이터 유형: 문자열

    테이블: 현재 상태 [awa_presence_state]

    머리글

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 23. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    컨텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 24. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 25. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다.
    가능한 이유:
    • 사용자에게 awa_integration_user 역할이 없습니다.
    • glide.awa.enabled 속성의 값이 예가 아닙니다. 이 속성은 고급 작업 할당(com.glide.awa) 플러그인이 설치된 경우 시스템 속성 [sys_property] 테이블에 나열됩니다. 자세한 내용은 고급 작업 할당과 함께 설치되는 구성 요소를 참조하십시오.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.
    표 26. 응답 본문 매개변수(JSON 또는 XML)
    매개변수 설명
    오류 요청 프로세스 중에 발생한 오류를 설명하는 상세 정보입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 요청 프로세스 중에 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 요청 프로세스 중에 발생한 오류에 대한 메시지입니다. 각 오류 메시지에는 속성에 해당 설명이 detail 있습니다.
    가능한 값:
    • 기록을 찾을 수 없음: 요청 본문에 제공된 정보가 정확하지 않거나 존재하지 않습니다.
    • 사용자가 인증되지 않음: 사용자에게 awa_integration_user 역할이 없습니다.

    데이터 유형: 문자열
    presence 에이전트의 현재 상태 및 채널에 대한 정보입니다.

    데이터 유형: 객체

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presence.available 에이전트를 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 에이전트를 사용할 수 있습니다.
    • false: 에이전트를 사용할 수 없습니다.

    데이터 유형: 부울
    presence.channels 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다.

    데이터 유형: 객체 배열

    "channels": [
  {
    "available": Boolean,
    "name": "String",
    "sys_id": "String"
  }
]
    presence.channels.available 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 채널을 사용할 수 있습니다.
    • false: 채널을 사용할 수 없습니다.

    데이터 유형: 부울
    presence.channels.name 채팅 또는 전화 같은 채널 이름입니다.

    데이터 유형: 문자열
    presence.channels.restrict_update 사용자가 업데이트를 제한할 수 있는지 여부를 나타내는 플래그입니다(즉, 가용성에 대한 채널 선택).
    가능한 값:
    • true: 사용자가 가용성을 위해 이 채널을 선택할 수 있습니다.
    • false: 사용자가 가용성을 위해 이 채널을 선택할 수 없습니다.

    데이터 유형: 부울
    presence.channels.service_channel_type 채팅과 같은 서비스 채널 유형입니다. 가능한 값은 설치된 플러그인에 따라 다릅니다.

    데이터 유형: 문자열
    presence.channels.sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    presence.name 에이전트의 현재 상태 이름입니다.
    가능한 값:
    • 사용 가능
    • 사용할 수 없음

    데이터 유형: 문자열
    presence.restrict_update 사용자가 업데이트를 제한할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 사용자가 업데이트를 제한할 수 있습니다.
    • false: 사용자가 업데이트를 제한할 수 없습니다.

    데이터 유형: 부울
    presence.sys_id 현재 상태 sys_id.

    데이터 유형: 문자열

    테이블: 현재 상태 [awa_presence_state]
    상태 실패한 요청의 상태입니다. 이 속성은 오류가 있는 경우에만 응답에 포함됩니다.

    유효한 값: failure

    데이터 유형: 문자열
    sys_id 에이전트 sys_id입니다.

    데이터 유형: 문자열
    workItem

    workItem: 이벤트와 연결된 작업 항목에 대한 정보입니다.

    데이터 유형: 문자열
    작업 항목.문서 workItem.document: 작업 항목 작업과 연결된 문서의 목록입니다.

    데이터 유형: 문자열
    workItem.document.sys_id workItem.document.sys_id: 작업 항목 작업에 할당된 문서의 Sys_id입니다.

    데이터 유형: 문자열
    작업 항목.문서.테이블 workItem.document.table: 작업에 할당된 문서 테이블의 이름입니다.

    데이터 유형: 문자열
    workItem.previousWorkItem workItem.previousWorkItem: 동일한 문서 ID에 대한 이전 작업 항목의 Sys_id입니다. 전송되지 않은 작업 항목의 경우 이 값은 비어 있습니다.

    데이터 유형: 문자열
    workItem.serviceChannel workItem.serviceChannel: 작업 항목 작업과 연결된 서비스 채널의 목록입니다.

    데이터 유형: 문자열
    workItem.serviceChannel.name workItem.serviceChannel.name: 채팅 또는 전화와 같은 서비스 채널의 이름입니다.

    데이터 유형: 문자열
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: 서비스 채널의 Sys_id입니다.

    데이터 유형: 문자열
    작업 항목.크기 workItem.size: 이 작업 항목이 에이전트에 할당될 때 사용되는 에이전트의 용량입니다.

    데이터 유형: 문자열
    workItem.sys_id workItem.sys_id: 수락되거나 제안된 작업 항목의 Sys_id입니다.

    데이터 유형: 문자열
    workItem.isQueueTransferred workItem.isQueueTransferred: 작업 항목이 큐 전송되었는지 여부를 나타내는 플래그입니다. 작업 항목이 큐로 전송되면 true로 설정하고, 그렇지 않으면 false로 설정합니다. 큐 전송에 대한 자세한 내용은 다음 문서를 참조하십시오 Transfer a chat to another queue.

    데이터 유형: 부울
    workitem.isAutoAccepted workItem.isAutoAccepted: 시스템에서 작업 항목을 자동으로 수락했는지 여부를 나타내는 플래그입니다. 작업 항목이 자동으로 수락된 경우 true로 설정합니다.

    데이터 유형: 부울

    		 
    curl -X PUT \
 https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
-d '{"presence": {\
  "sys_id": "0b10223c57a313005baaaa65ef94f970",\
  "channels": [{ \
  "sys_id": "0bbdedbb3b892300a2bac9bb34efc445",\
  "available": true
}] 
}}
    {
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

    AWA 에이전트 - PUT /now/awa/agents/{user_id}/capacities

    채널 용량 및 범용 용량에 대한 에이전트의 최대 용량(작업 부하)을 업데이트할 수 있습니다.

    이 AWA 에이전트 - GET /now/awa/agents/{user_id}/capacities 메서드를 사용하여 에이전트의 현재 채널과 범용 용량을 검색합니다.

    참조:

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/awa/agents/{user_id}/capacities

    기본 URL: /api/now/awa/agents/{user_id}/capacities

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 27. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    user_id 나열된 에이전트의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]
    표 28. 쿼리 매개변수
    이름 설명
    안 함
    표 29. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    채널 지정된 에이전트에 대해 하나 이상의 채널 최대값을 업데이트하는 경우 필수입니다. 채널에 할당된 각 채널의 최대 용량에 채널을 매핑하는 하나 이상의 키-값 쌍을 포함하는 JSON 객체입니다.

    데이터 유형: 객체

    쌍의 형식은 다음과 같습니다.
    • 키(채널 sys_id) – 채널 sys_id.

      데이터 유형: 문자열

    • 값(최대 용량) – 에이전트를 한 번에 능동적으로 할당할 수 있는 특정 서비스 채널의 최대 작업 부하입니다.

      데이터 유형: 숫자

    channels: {"<channel_sys_id>": <max_capacity>}
    universal_capacity 범용 용량을 업데이트하는 경우 필수입니다. 모든 서비스 채널에서 에이전트의 최대 용량입니다. 에이전트의 현재 워크로드가 최대 범용 용량과 같으면 추가 작업 항목이 에이전트에 할당되지 않습니다.

    데이터 유형: 숫자

    머리글

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 30. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 31. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 32. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    채널 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다. 
    "channels": [
  {
    "channel_sys_id": "String",
    "max_capacity": Number
  }
]

    데이터 유형: 배열
    channels.channel_sys_id 채널 sys_id.

    데이터 유형: 문자열

    표: 서비스 채널 [awa_service_channel]
    channels.max_capacity 에이전트를 한 번에 능동적으로 할당할 수 있는 특정 서비스 채널의 최대 작업 부하입니다.

    데이터 유형: 문자열
    오류 요청 프로세스 중에 발생한 오류를 설명하는 상세 정보입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 요청 프로세스 중에 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 요청 프로세스 중에 발생한 오류에 대한 메시지입니다. 설명은 속성에 제공됩니다 error.detail .

    데이터 유형: 문자열
    상태 실패한 요청의 상태입니다. 이 속성은 오류가 있는 경우에만 응답에 포함됩니다.

    유효한 값: failure

    데이터 유형: 문자열
    universal_capacity 모든 서비스 채널에서 에이전트의 최대 용량입니다. 에이전트의 현재 워크로드가 최대 범용 용량과 같으면 추가 작업 항목이 에이전트에 할당되지 않습니다.

    이 속성은 이 에이전트에 대한 범용 용량 기록이 존재하는 경우에만 반환됩니다.

    데이터 유형: 숫자

    샘플 cURL 요청

    다음 예시에서는 에이전트의 범용 용량과 지정된 채널의 최대 용량을 변경하는 방법을 보여줍니다.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"channels\": { \"27f675e3739713004a905ee515f6a7c3\": 6 },
 \"universal_capacity\" : 12
}" \
--user 'username':'password'

    성공적인 응답에는 업데이트된 용량 값이 포함됩니다.

    {
  "result": {
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "max_capacity": 6
      }
    ],
    "universal_capacity": 12
  }
}