ParseDialogflowRequest 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

개요

ParseDialogflowRequest 정책은 Dialogflow와 Apigee의 통합을 도와줍니다. 자세한 내용은 Apigee와 Contact Center AI 통합을 참조하세요.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

ParseDialogflowRequest 정책은 요청 데이터를 백엔드 시스템에 보내기 전에 Dialogflow 에이전트에서 WebhookRequest를 처리합니다. 정책은 WebhookRequest에서 전체 API 호출 기간 동안 사용 가능한 흐름 변수로 데이터를 추출합니다. 후속 콜아웃, 조회 또는 조정된 로직에서 변수를 사용할 수 있습니다. 이 정책은 Dialogflow 에이전트가 기존 백엔드 시스템과 상호작용하도록 하려는 경우에 특히 유용합니다. 에이전트의 데이터를 백엔드 시스템에 보내기 전에 백엔드 시스템이 사용할 수 있는 방식으로 데이터를 파싱하고 구조화할 수 있습니다.

백엔드 서비스 통합업체는 Dialogflow WebhookRequest의 형식을 이해하는 데 시간을 소비할 필요가 없습니다. 즉시 사용 가능한 ParseDialogflowRequest 정책이 요청 데이터를 원활하게 처리해 줍니다.

Apigee에서 Dialogflow 에이전트의 WebhookRequest에 액세스하려면 에이전트의 웹훅 URL(fulfillment)을 Apigee에서 구성한 ProxyEndPoint로 설정해야 합니다. ProxyEndPoint에 공개적으로 액세스할 수 있어야 합니다. 자세한 내용은 웹훅 서비스 요구사항을 참조하세요.

참고: ParseDialogflowRequest 정책은 Dialogflow 요청의 fulfillmentInfo.tag, sentimentAnalysisResult, sessionInfo 객체만 파싱합니다.

`<ParseDialogflowRequest>`

ParseDialogflowRequest 정책을 정의합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 객체
상위 요소	해당 사항 없음
하위 요소	`<DialogflowVersion>` `<DisplayName>` `<VariablePrefix>`

다음 표에서는 ParseDialogflowRequest 정책과 관련된 하위 요소를 간략하게 설명합니다.

하위 요소	필수 여부	설명
`<VariablePrefix>`	선택사항	흐름 변수의 커스텀 프리픽스를 지정합니다.
`<DialogflowVersion>`	선택사항	Dialogflow 버전을 지정합니다.

예

다음 예시에서는 샘플 웹훅 요청, 해당 ParseDialogflowRequest 정책, 정책을 적용한 후 생성된 흐름 변수를 보여줍니다.

구문

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The optional prefix to be added to all variables created from the
         Dialogflow Webhook request. Note that all variables created from the
         WebhookRequest object will be within a container named
         "google.dialogflow" -->
    <VariablePrefix>CUSTOM_PREFIX</VariablePrefix>
    <!-- The version of Dialogflow for which this request policy is written up.
         This policy supports only the CX version. This element is optional and
         defaults to CX if unspecified -->
    <DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>
</ParseDialogflowRequest>

웹훅 요청

다음 예시에서는 Dialogflow 에이전트의 웹훅 요청(JSON 형식)을 보여줍니다.

{
    "fulfillmentInfo": {
        "tag": "check-claim-status"
    },
    "sessionInfo": {
        "session": "projects/apigee-test/locations/global/agents/ea45003d-3f5c-46ba-ac6b-f4c6dc8db707/sessions/5ea2e8-7c1-cf4-2cf-8e4d89e72",
        "parameters": {
            "claimId": "1234",
            "policyId": "abcd"
        }
    },
    "sentimentAnalysisResult": {
      "score": -0.7,
      "magnitude": 0.7
  }
}

요청에서 구성할 수 있는 다양한 필드는 WebhookRequest를 참조하세요.

다음 샘플로 이동하여 ParseDialogflowRequest 정책 구성을 확인합니다.

ParseDialogflowRequest 정책

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="DialogflowRequest-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Request Policy</DisplayName>
    <VariablePrefix>my-prefix</VariablePrefix>
    <DialogflowVersion>CX</DialogflowVersion>
</ParseDialogflowRequest>

다음 샘플로 이동하여 정책에서 만든 흐름 변수를 확인합니다.

흐름 변수

google.dialogflow.my-prefix.fulfillment.tag = "check-claim-status"
google.dialogflow.my-prefix.session.id = "5ea2e8-7c1-cf4-2cf-8e4d89e72"
google.dialogflow.my-prefix.session.project.id = "apigee-test"
google.dialogflow.my-prefix.session.agent.id = "ea45003d-3f5c-46ba-ac6b-f4c6dc8db707"
google.dialogflow.my-prefix.session.parameters.claimId = "1234"
google.dialogflow.my-prefix.session.parameters.policyId = "abcd"
google.dialogflow.my-prefix.sentimentAnalysisResultScore = -0.7
google.dialogflow.my-prefix.sentimentAnalysisResultMagnitude = 0.7

생성된 모든 흐름 변수는 google.dialogflow로 시작하고 <VariablePrefix> 요소에 지정된 프리픽스(my-prefix)로 이어집니다.

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성	기본	필수 여부	설명
`name`	해당 없음	필수	정책의 내부 이름입니다. `name` 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 `<DisplayName>` 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
`continueOnError`	false	선택	정책이 실패할 경우 오류가 반환되도록 하려면 `false`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
`enabled`	true	선택	정책을 시행하려면 `true`로 설정합니다. 정책을 중지하려면 `false`로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
`async`	false	지원 중단됨	이 속성은 지원이 중단되었습니다.

하위 요소 참조

이 섹션에서는 <ParseDialogflowRequest>의 하위 요소를 설명합니다.

`<DisplayName>`

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값	해당 사항 없음
필수 여부	선택사항. `<DisplayName>`을 생략하면 정책의 `name` 속성 값이 사용됩니다.
유형	문자열
상위 요소	<`PolicyElement`>
하위 요소	없음

<DisplayName> 요소는 다음 문법을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

`<VariablePrefix>`

흐름 변수의 커스텀 프리픽스를 지정합니다. 이 요소에 지정된 값은 ParseDialogflowRequest 정책으로 생성된 모든 변수 이름에 프리픽스로 추가됩니다. 기본적으로 정책에 의해 생성된 모든 변수에는 google.dialogflow 프리픽스가 추가됩니다. VariablePrefix 요소를 지정한 경우 커스텀 프리픽스가 google.dialogflow 뒤에 추가됩니다. 따라서 변수 이름은 google.dialogflow.CUSTOM_PREFIX로 시작합니다.

VariablePrefix 요소를 지정하지 않으면 변수 이름에 google.dialogflow로만 프리픽스가 추가됩니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	`<ParseDialogflowRequest>`
하위 요소	없음

<VariablePrefix> 요소는 다음 문법을 사용합니다.

구문

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

예

다음 예시에서는 VariablePrefix를 my-prefix로 설정합니다.

<VariablePrefix>my-custom-prefix</VariablePrefix>

이 구성에 따라 모든 변수 이름이 google.dialogflow.my-custom-prefix로 시작됩니다.

`<DialogflowVersion>`

Dialogflow 버전을 지정합니다. ParseDialogflowRequest 정책은 CX 버전만 지원합니다. 정책에서 이 요소를 지정하지 않으면 버전은 기본적으로 CX가 됩니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	해당 사항 없음
하위 요소	없음

<DialogflowVersion> 요소는 다음 문법을 사용합니다.

구문

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

예

다음 예시에서는 DialogflowVersion을 CX로 설정합니다.

<DialogflowVersion>CX</DialogflowVersion>

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인	해결
`steps.parsedialogflowrequest.InvalidSessionInfo`	`500`	이 오류는 Dialogflow 요청에 잘못된 sessionInfo.session 필드가 있을 때 발생합니다. 웹훅은 이 필드를 사용하여 세션을 식별할 수 있습니다. 지원되는 세션 형식에 대한 자세한 내용은 Class SessionInfo를 참조하세요.
`steps.parsedialogflowrequest.MalformedInput`	`500`	이 오류는 이 정책에 제공된 JSON이 유효하지 않거나 잘못되었을 때 발생합니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름	원인	해결
`UnsupportedOperation`	이 오류는 `DialogflowVersion` 요소에 지원되지 않는 Dialogflow 버전을 지정한 경우에 발생합니다. ParseDialogflowRequest 정책은 `CX` 버전만 지원합니다.

오류 변수

정책에 실행 오류가 발생할 때마다 Apigee는 오류 메시지를 생성합니다. 오류 응답에서 이러한 오류 메시지를 볼 수 있습니다. 시스템에서 생성된 오류 메시지가 제품의 컨텍스트와 관련이 없을 경우가 많습니다. 메시지를 보다 의미 있게 만들기 위해 오류 유형에 따라 오류 메시지를 맞춤설정할 수 있습니다.

오류 메시지를 맞춤설정하려면 오류 규칙 또는 RaiseFault 정책을 사용하면 됩니다. 오류 규칙과 RaiseFault 정책의 차이점에 대한 자세한 내용은 FaultRules와 RaiseFault 정책 비교를 참조하세요. 오류 규칙과 RaiseFault 정책 모두에서 Condition 요소를 사용하여 조건을 확인해야 합니다. Apigee는 각 정책에 고유한 오류 변수를 제공하며 정책이 런타임 오류를 트리거할 때 오류 변수 값이 설정됩니다. 이러한 변수를 사용하여 특정 오류 조건을 확인하고 적절한 조치를 취할 수 있습니다. 오류 조건 확인에 대한 자세한 내용은 빌드 조건을 참조하세요.

다음 표에서는 이 정책과 관련된 오류 변수를 설명합니다.

변수	각 항목의 의미는 다음과 같습니다.	예시
`fault.name="FAULT_NAME"`	`FAULT_NAME`은 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	`fault.name Matches "UnresolvedVariable"`
`ParseDialogflowRequest.POLICY_NAME.failed`	`POLICY_NAME`은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	`ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true`

정책 오류에 대한 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

ParseDialogflowRequest 정책

개요

<ParseDialogflowRequest>

예

구문

웹훅 요청

ParseDialogflowRequest 정책

흐름 변수

하위 요소 참조

<DisplayName>

구문

예

<VariablePrefix>

구문

예

<DialogflowVersion>

구문

예

오류 코드

런타임 오류

배포 오류

오류 변수

관련 주제

`<ParseDialogflowRequest>`

`<DisplayName>`

`<VariablePrefix>`

`<DialogflowVersion>`