사전 예방적 인게이지먼트 API

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기8분

    • 사전 예방적 인게이지먼트 API는 디지털 경험 문제를 생성하기 위한 엔드포인트를 제공합니다.

    이 API는 사용자 지정 스크립트 REST API로 사용할 수 있습니다. 사전 예방적 인게이지먼트(proactive-engagement) 플러그인과 sn_pren.experience_issue_create 역할이 필요합니다. 이 API는 sn_pren 네임스페이스에 속합니다.

    사용자의 인스턴스에서 문제가 감지되면 사전 예방적 인게이지먼트 API를 사용하여 경험 문제를 생성합니다. 생성된 경험 문제는 사용자의 참여를 유도하고 사용자가 문제를 스스로 해결하는 데 도움을 줍니다.

    이 API를 사용하려면 다음 테이블이 기록으로 채워져 있는지 확인합니다.

    • 문제 레지스트리 템플릿 [sn_pren_issue_registry_template]
    • 문제 레지스트리 [sn_pren_issue_registry]
    • 해결 [sn_pren_resolution]
    • 알림 콘텐츠 [sn_pren_notification_content]
    • 제공자 [sn_pren_provider]

    자세한 내용은 Proactive Engagement 문서를 참조하십시오.

    사전 예방적 인게이지먼트 - CREATE /api/sn_pren/self_remediation/experience_issue/create

    사용자의 엔드포인트에서 문제가 감지되면 경험 문제를 생성합니다. 경험 문제 [sn_pren_experience_issue] 테이블을 업데이트합니다.

    URL 형식

    기본 URL: /api/sn_pren/self_remediation/experience_issue/create

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    없음
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    endpoint 필수 문제 상세 정보를 탐지하는 데 사용되는 CI(구성 항목) 및 사용자 정보가 포함된 객체입니다.
    주:
    이 개체 내의 모든 매개 변수는 선택 사항입니다. 사용자 또는 장치를 식별하기 위해 개체 내에서 하나 이상의 매개 변수를 전달해야 합니다."

    데이터 유형: 객체

    "endpoint": {
    "CI": "String",
    "email": "String",
    "user_id": "String",
    "user_name": "String"
  }
    끝점. CI (영문) 문제가 탐지된 CI 장치의 Sys_id입니다. 컴퓨터 [cmdb_ci_computer] 테이블에 있습니다.

    데이터 유형: 문자열
    endpoint.email 문제가 탐지된 사용자의 이메일 주소입니다.

    데이터 유형: 문자열
    endpoint.user_id 문제가 탐지된 사용자의 Sys_id입니다. 사용자 [sys_user] 테이블에 있습니다.

    데이터 유형: 문자열
    endpoint.user_name 문제가 탐지된 사용자의 사용자 이름입니다. 사용자 [sys_user] 테이블에 있습니다.

    데이터 유형: 문자열
    experience_id 옵션입니다. 생성된 문제에 할당할 사용자 정의 ID입니다. 이 매개 변수를 지정하지 않으면 ID가 자동으로 생성됩니다.

    데이터 유형: 숫자
    input_parameters 옵션입니다. 장치에서 실행될 작업에 전달할 매개변수입니다. 전송된 입력 매개변수는 하위 플로우, 플로우 작업 또는 CI 작업과 같은 구성된 해결-정정 작업으로 전달됩니다.

    데이터 유형: 객체

    "input_parameters": {
    "process_id": "String"
  }
    input_parameters.process_id 옵션입니다. 종료하거나 다시 시작할 프로세스의 sys_id입니다.

    데이터 유형: 문자열
    investigative_details 옵션입니다. PUE(전력 사용 효율성) 확인이 실패하는 경우 수동 조사에 유용할 수 있는 세부 정보입니다. 조사 상세 정보는 PUE 확인이 실패할 경우 폴백으로 생성되는 인시던트에 복사됩니다.

    데이터 유형: 객체

    "investigative_details": {
    "cpu_usage": "String",
    "processes_running": "String",
    "available_memory": "String"
  }
    investigative_details.cpu_usage 장치에서 사용되는 CPU 사용량입니다.

    데이터 형식: 숫자(문자열로 구문 분석됨)
    investigative_details.processes_running 장치에서 실행 중인 프로세스 수입니다.

    데이터 형식: 숫자(문자열로 구문 분석됨)
    investigative_details.available_memory입니다. 장치에서 사용 가능한 메모리입니다.

    데이터 형식: 숫자(문자열로 구문 분석됨)
    issue_code 필수 문제와 연결할 코드를 발행합니다. 문제 코드를 사용할 수 있어야 하며 인스턴스에 배포되어야 합니다. 문제 레지스트리 [sn_pren_issue_registry] 테이블에 있습니다. 비어 있거나 잘못된 문제가 제공된 경우 API는 오류를 반환합니다.

    데이터 유형: 문자열
    제공자 필수 제공자의 고유 코드입니다. 이 코드는 인스턴스의 테이블에 있는 sn_pren_provider 필드와 일치 provider_code 해야 합니다.

    데이터 유형: 문자열

    헤더

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

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

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

    기본값: application/json

    상태 코드

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

    상태 코드 설명
    200 경험 문제가 성공적으로 생성되었습니다.
    400 잘못된 요청입니다. 엔드포인트 상세 정보를 제공합니다.

    요청에 빈 endpoint 객체가 전송되었습니다.
    400 잘못된 문제 코드입니다. 올바른 문제 코드를 제공하십시오.

    요청에 빈 issue_code 항목이 전송되었습니다.
    400 잘못된 제공자입니다. 올바른 제공자를 제공하십시오.

    요청에 빈 제공자가 전송되었습니다.
    400 잘못된 문제 코드 또는 제공자입니다. 올바른 상세 정보를 제공하십시오.

    인스턴스에서 문제를 탐지할 수 없습니다. 확인 issue_code 및 provider 상세 정보.
    400 문제 코드에 적절한 해결 방법이 없습니다.

    식별된 문제에 대해 PUE 프레임워크에 유효한 해결 방법이 구성되어 있지 않습니다.
    400 엔드포인트 상세 정보에서 사용자를 확인할 수 없습니다. 올바른 상세 정보를 제공하십시오.

    PUE 프레임워크 ID가 지정된 엔드포인트 세부 정보에서 사용자를 식별할 수 없는 경우 이 오류가 반환됩니다.
    400 지정된 사용자에 대해 지정된 문제 코드로 경험 문제를 해결하는 중입니다.

    지정된 경험 문제가 현재 진행 중 또는 미결 상태입니다.
    400 지정된 experience_id 기존 경험 문제가 아직 실행 중이거나 종결되었습니다.

    이 오류는 경험 문제가 연결 시나리오에 있을 때 발생합니다. 예를 들어 새 issue_code 키가 기존 experience_id및 실행과 함께 전송되고 이전 경험 문제가 실행 중이거나 종결된 상태인 경우입니다.

    이 experience_id의 경험 문제는 이전 experience_id 사용하여 새 issue_code 보내려면 action_wait 상태여야 합니다.
    400 경험 문제를 생성하는 동안 오류가 발생했습니다.

    이는 기술적 오류를 나타냅니다.

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

    이름 설명
    experienceId 생성된 경험 문제의 경험 ID입니다. 요청 매개변수에서 experience_id 생성됩니다. 경험 문제는 경험 문제 [sn_pren_experience_issue] 테이블에 생성됩니다.

    전달되지 않은 경우 experience_id 결과 ID는 항상 작성된 기록의 sys_id입니다.

    cURL 요청

    다음 예에서는 사용자 Abel Tuter에 대한 경험 문제를 만듭니다. 본문의 문제 코드를 사용하면 사전 예방적 인게이지먼트가 문제 레지스트리 템플릿에서 해결 방법을 식별하고 가상 에이전트를 통해 최종 사용자와 소통하여 문제를 자체 해결하도록 지원할 수 있습니다.

    curl  "http://instance.servicenow.com//api/sn_srf/self_remediation/experience_issue/create" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data “{
  "endpoint": {
    "CI": "d049b28e936aa1106f98f6db5cba10d5",
    "user_id": "62826bf03710200044e0bfc8bcbe5df1",
    "user_name": "abel.tuter",
    "email": ""
  },
  "issue_code": "100",
  "provider": "sn",
  "experience_id": "09ed4830f393739df33",
  "input_parameters": {
    "process_id": "10644"
  },
  "investigative_details": {
    "cpu usage": "78%",
    "processes running": "35",
    "available memory": "23%"
  }
}”\

    응답 본문은 문제 생성이 성공했음을 나타내는 경험 ID를 반환합니다.

    { 
  "result": { 
    "experience_id": “09ed4830f393739df33”
  } 
}