일부 제품과 기능의 이름이 변경되고 있습니다. 생성형 플레이북 및 흐름 기능도 단일 통합 콘솔로 마이그레이션되고 있습니다.

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

웹훅

웹훅은 비즈니스 로직을 호스팅하거나 다른 서비스를 호출하는 서비스입니다. 세션 중에 웹훅을 사용하면 Dialogflow CX의 자연어 처리에서 추출한 데이터를 사용하여 동적 응답을 생성하거나, 수집된 데이터를 검증하거나, 백엔드에서 작업을 트리거할 수 있습니다.

웹훅은 표준 웹훅 또는 가변형 웹훅일 수 있습니다. 표준 웹훅의 경우 Dialogflow CX에서 요청 및 응답 필드를 정의합니다. 가변형 웹훅에서는 개발자가 요청 및 응답 필드를 정의합니다.

$request.webhook_status_code 요청 매개변수를 사용하여 웹훅 호출의 HTTP 상태 코드에 액세스할 수도 있습니다.

표준 웹훅

표준 웹훅에서는 Dialogflow CX에서 정의된 요청 및 응답 메시지를 사용합니다. 요청 메시지는 세션에 대한 많은 세부정보를 제공합니다. 예를 들어 현재 활성 페이지, 최근에 일치한 의도, 세션 매개변수 값, 에이전트에서 정의된 응답이 모두 포함됩니다.

표준 웹훅 요청

웹훅이 포함된 fulfillment가 호출되면 Dialogflow CX는 웹훅 서비스에 HTTPS POST 웹훅 요청을 보냅니다. 이 요청의 본문은 세션 정보가 포함된 WebhookRequest JSON 객체입니다.

일부 통합에서는 WebhookRequest.payload 필드를 추가 정보로 채웁니다. 예를 들어 Dialogflow CX Phone Gateway 통합에서는 최종 사용자 호출자 ID를 제공합니다.

자세한 내용은 WebhookRequest (V3) 또는 WebhookRequest (V3Beta1) 참조 문서를 확인하세요.

표준 웹훅 응답

웹훅 서비스가 요청을 받은 후에는 다음 요구사항을 충족하는 응답을 보내야 합니다.

응답은 웹훅 리소스를 만들 때 구성한 제한 시간 내에 발생해야 합니다.
응답은 64KiB 이하여야 합니다.

자세한 내용은 WebhookResponse (V3) 또는 WebhookResponse (V3Beta1) 참조 문서를 확인하세요.

표준 웹훅 리소스 설정

다음 표에서는 표준 웹훅의 웹훅 리소스 설정을 설명합니다.

X	항목
표시 이름	웹훅이 콘솔에 표시되는 이름입니다.
웹훅 제한 시간	Dialogflow CX가 웹훅 서비스에 HTTP 요청을 보낼 때 이 설정은 전체 대화 차례가 아닌 각 개별 요청 시도의 시간 제한(초)을 제어합니다. 시도가 제한 시간을 초과하거나 일시적인 오류로 실패하면 Dialogflow CX에서 자동으로 한 번 다시 시도합니다. 이 재시도로 인해 오류가 반환되기 전에 구성된 제한 시간 값의 최대 두 배에 달하는 총 처리 시간이 발생할 수 있습니다. 재시도 후 시간 초과가 발생하면 Dialogflow CX는 webhook.error.timeout 이벤트를 호출합니다. 자세한 내용은 자동 재시도를 참고하세요.
유형	비공개 네트워크 액세스에 서비스 디렉터리를 사용하는 경우 서비스 디렉터리로 설정하고 그렇지 않으면 일반 웹 서비스로 설정합니다.
웹훅 URL	웹훅 서비스의 URL 주소를 제공하세요.
하위 유형	표준으로 설정합니다.
환경별 웹훅	환경별 웹훅을 제공할 수 있습니다.
인증	인증 섹션을 참고하세요.
커스텀 CA 인증서	이는 커스텀 CA 인증서를 업로드하는 데 사용됩니다.

가변형 웹훅

가변형 웹훅에서는 요청 HTTP 메서드, 요청 URL 매개변수, 요청 및 응답 메시지의 필드를 정의합니다. 요청은 선택한 매개변수 값만 제공할 수 있고 응답은 매개변수 재정의 값만 제공할 수 있습니다. 세션 매개변수 값 이외의 다른 항목은 통신할 필요가 거의 없으므로 에이전트와 웹훅 간의 인터페이스가 간소화됩니다. 또한 요청 및 응답 메시지에 필요한 것만 포함되기 때문에 웹훅 구현을 간소화할 수 있고 다양한 시나리오에 대해 고유한 웹훅 메시지를 제공할 수 있습니다.

가변형 웹훅 요청

에이전트의 웹훅 리소스를 만들 때 웹훅 요청에 대해 다음을 지정할 수 있습니다.

웹훅 서비스에 전송된 웹훅 요청에 사용되는 HTTP 메서드입니다.
Dialogflow CX가 URL을 사용해서 웹훅 서비스에 전송해야 하는 세션 매개변수 값
POST, PUT, PATCH를 메서드로 선택한 경우 Dialogflow CX가 요청 JSON 본문을 통해 웹훅 서비스로 전송해야 하는 세션 매개변수 값입니다.

요청 URL 또는 JSON 본문을 사용하여 세션 매개변수 값을 전송하려면 매개변수 참조를 사용합니다. 매개변수 참조를 URL로 이스케이프 처리하거나 따옴표로 묶지 않아도 됩니다. 런타임에 Dialogflow CX는 필요에 따라 파라미터 값을 URL로 이스케이프 처리합니다. 목록 또는 복합 값은 JSON으로 제공됩니다.

JSON 본문에서 매개변수 참조를 사용할 때는 매개변수 유형에 관계없이 참조를 따옴표로 묶어야 합니다. 매개변수가 실제로 숫자 스칼라, 목록, 조합 값이면 Dialogflow CX가 매개변수 데이터 유형을 보존하기 위해 런타임에 요청을 전송할 때 따옴표를 삭제합니다. 문자열 스칼라 유형은 따옴표가 있는 상태로 유지됩니다. 문자열 값 내에서 숫자 스칼라, 목록, 복합 값을 참조하는 경우 (예: '숫자입니다: $session.params.size') 매개변수는 문자열로 처리됩니다 ('숫자입니다: 3').

예를 들어 다음과 같이 fruit 및 size 세션 매개변수 값을 요청 URL에 제공할 수 있습니다.

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

그리고 요청 JSON 본문에 다음과 같이 제공합니다.

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

가변형 웹훅 응답

에이전트의 웹훅 리소스를 만들 때 Dialogflow CX가 런타임에 웹훅 응답의 특정 필드로 설정되도록 세션 매개변수를 지정할 수 있습니다.

대답은 다음 제한사항을 충족해야 합니다.

응답은 웹훅 리소스를 만들 때 구성한 제한 시간 내에 발생해야 하며 그렇지 않으면 요청이 타임아웃됩니다.
응답 크기는 최대 64KiB여야 합니다.

스칼라, 목록 또는 복합 필드를 지정하려면 다음 형식을 사용합니다.

$.fully.qualified.path.to.field

예를 들어 다음 JSON 응답을 사용한다고 가정해 보세요.

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

'value' 필드를 지정하려면 다음을 사용합니다.

$.routes[0].legs[0].distance.value

가변형 웹훅 리소스 설정

다음 표에서는 가변형 웹훅의 웹훅 리소스 설정을 설명합니다.

X	항목
표시 이름	웹훅이 콘솔에 표시되는 이름입니다.
웹훅 제한 시간	Dialogflow CX가 웹훅 서비스에 HTTP 요청을 보낼 때 이 설정은 전체 대화 차례가 아닌 각 개별 요청 시도의 시간 제한(초)을 제어합니다. 시도가 제한 시간을 초과하거나 일시적인 오류로 실패하면 Dialogflow CX에서 자동으로 한 번 다시 시도합니다. 이 재시도로 인해 오류가 반환되기 전에 구성된 제한 시간 값의 최대 두 배에 달하는 총 처리 시간이 발생할 수 있습니다. 재시도 후 시간 초과가 발생하면 Dialogflow CX는 webhook.error.timeout 이벤트를 호출합니다. 자세한 내용은 자동 재시도를 참고하세요.
유형	비공개 네트워크 액세스에 서비스 디렉터리를 사용하는 경우 서비스 디렉터리로 설정하고 그렇지 않으면 일반 웹 서비스로 설정합니다.
웹훅 URL	세션 매개변수에 대한 참조가 포함될 수 있는 웹훅 서비스의 URL 주소를 제공합니다.
하위 유형	Flexible로 설정합니다.
메서드	웹훅 요청의 HTTP 메서드를 설정합니다.
요청 본문	위에서 설명한 대로 요청 JSON 본문을 제공합니다.
응답 구성	위에서 설명한 대로 응답 필드로 설정할 세션 매개변수를 제공합니다.
환경별 웹훅	환경별 웹훅을 제공할 수 있습니다.
인증	인증 섹션을 참조하세요.
커스텀 CA 인증서	이는 커스텀 CA 인증서를 업로드하는 데 사용됩니다.

사전 정의된 커스텀 템플릿 사용

Dialogflow는 Salesforce CRM에 가변형 웹훅을 통합하기 위해 사용할 수 있는 사전 정의된 커스텀 템플릿을 제공합니다.

관리 탭으로 이동하여 웹훅을 선택한 다음 만들기를 클릭합니다.
하위 유형에서 가변형을 선택합니다.
사전 정의된 템플릿을 사용하여 구성을 클릭합니다.
통합 유형 메뉴에서 Salesforce를 선택합니다.
API 이름 메뉴에서 API 이름을 선택합니다. 템플릿은 선택한 API 이름에 따라 웹훅 양식을 자동으로 작성합니다.
1. 매개변수에 따라 필요하면 다음 필드를 수동으로 구성합니다.
  - 웹훅 URL
  - 메서드
  - 요청 본문 JSON
  - 응답 구성
2. 필수 OAuth 필드는 인증 섹션에 강조 표시됩니다.
저장을 클릭합니다.

웹훅 서비스 요구사항

웹훅 서비스는 다음 요구사항을 충족해야 합니다.

HTTPS 요청을 처리합니다. HTTP는 지원되지 않습니다. Google Cloud 에서 Compute 또는 서버리스 컴퓨팅 솔루션을 사용하여 웹훅 서비스를 호스팅하는 경우 HTTPS와 함께 제공되는 문서를 참고하세요. 다른 호스팅 옵션은 도메인의 SSL 인증서 받기를 참고하세요.
웹훅 서비스 URL이 공개적으로 액세스할 수 있는지 확인합니다. 단, Cloud Run 리소스로 호스팅되거나 서비스 디렉터리 웹훅으로 액세스되는 경우는 예외입니다.
표준 웹훅 또는 가변형 웹훅 섹션에 설명된 대로 요청과 응답을 처리합니다.
에이전트가 서비스 디렉터리 비공개 네트워크 액세스와 통합되지 않으면 웹훅 호출이 서비스 경계 외부로 간주되어 VPC 서비스 제어를 사용 설정할 때 차단됩니다. 서비스 디렉터리는 제한된 엔드포인트를 지원합니다. 자세한 내용은 서비스 디렉터리를 참고하세요.

인증

본인 또는 Dialogflow CX 에이전트만 요청을 실행할 수 있도록 웹훅 서비스를 보호합니다. 웹훅 리소스를 만들거나 수정할 때 이를 구성합니다. Dialogflow CX는 다음과 같은 인증 메커니즘을 지원합니다.

X	항목
인증 헤더	웹훅 설정의 경우 선택사항인 HTTP 헤더 키-값 쌍을 지정할 수 있습니다. 제공되는 경우 Dialogflow CX가 이러한 HTTP 헤더를 웹훅 요청에 추가합니다. `authorization` 키와 함께 단일 쌍을 제공하는 것이 일반적입니다. 헤더 값은 정적 응답 메시지와 같은 세션 매개변수 참조 및 시스템 함수 파싱을 지원합니다 `authorization` 헤더에 정적 사용자 인증 정보를 사용하는 경우 Secret Manager를 사용하여 사용자 인증 정보를 제공하는 것이 좋습니다.
사용자 이름과 비밀번호를 사용하는 기본 인증	웹훅 설정의 경우 선택사항인 로그인 사용자 이름과 비밀번호 값을 지정할 수 있습니다. 제공되는 경우 Dialogflow CX가 웹훅 요청에 승인 HTTP 헤더를 추가합니다. 이 헤더는 `"authorization: Basic <base 64 encoding of the string username:password>"` 형식입니다. Secret Manager를 사용하여 사용자 이름과 비밀번호를 제공하는 것이 좋습니다.
서드 파티 OAuth	Dialogflow CX가 OAuth 시스템의 액세스 토큰을 교환하고 승인 HTTP 헤더에 추가하도록 서드 파티 OAuth 구성을 지정할 수 있습니다. 클라이언트 사용자 인증 정보 흐름만 지원됩니다. Secret Manager를 사용하여 클라이언트 보안 비밀을 제공하는 것이 좋습니다.
서비스 에이전트 액세스 토큰	지원 중단되었습니다.
서비스 계정	인증에 서비스 계정을 사용할 수 있습니다. 이 토큰은 다른 Google Cloud API에 액세스하는 데 사용할 수 있습니다.
서비스 에이전트 ID 토큰	서비스 에이전트 인증 섹션에서 ID 토큰을 선택하여 인증에 서비스 에이전트 ID 토큰을 사용할 수 있습니다. 이를 통해 Cloud Run 리소스에 액세스할 수 있습니다.
상호 TLS 인증	상호 TLS 인증 문서를 참조하세요.

서드 파티 OAuth

Dialogflow CX는 서드 파티 OAuth 제공업체에서 액세스 토큰을 수집하고 웹훅 요청을 할 때 승인 HTTP 헤더에 추가합니다.

다음 표에서는 서드 파티 OAuth의 리소스 설정을 설명합니다.

X	항목
클라이언트 ID	OAuth 토큰을 요청할 때 사용할 클라이언트 ID입니다.
클라이언트 보안 비밀번호	OAuth 토큰을 요청할 때 사용할 보안 비밀입니다. Secret Manager를 사용하여 클라이언트 보안 비밀을 제공하는 것이 좋습니다.
OAuth 엔드포인트 URL	OAuth 토큰을 요청하는 데 사용할 URL입니다.
OAuth 범위	OAuth 토큰을 사용할 수 있는 범위의 쉼표로 구분된 목록입니다.

토큰을 수신하기 위해 OAuth 엔드포인트 URL로 전송된 요청에는 웹훅 요청에 대해 구성된 맞춤 요청 헤더가 포함되지 않습니다. OAuth 엔드포인트 URL의 쿼리 문자열 내에서 매개변수로 OAuth 서버에 맞춤 정보를 전달할 수 있습니다.

서비스 에이전트 ID 토큰

Dialogflow CX는 Dialogflow CX 서비스 에이전트를 사용하여 ID 토큰을 생성할 수 있습니다. 이 토큰은 Dialogflow CX가 웹훅을 호출할 때 승인 HTTP 헤더에 추가됩니다.

ID 토큰은 Cloud Run 호출자 역할(roles/run.invoker)을 부여한 후 Cloud Run 리소스에 액세스하는 데 사용할 수 있습니다.

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Cloud Run 리소스가 동일한 리소스 프로젝트에 있으면 이를 호출하는 데 추가 Identity and Access Management (IAM) 권한이 필요하지 않습니다.

ID 토큰을 생성하는 데 사용되는 대상은 쿼리 매개변수를 제외한 전체 웹훅 URL입니다. Cloud Run을 사용하는 경우 이 URL이 Cloud Run 대상에서 지원되는지 확인합니다.

예를 들어 웹훅 URL이 다음과 같은 경우:

https://myproject.cloudfunctions.net/my-function/method1?query=value

다음 URL은 커스텀 대상에 있어야 합니다.

https://myproject.cloudfunctions.net/my-function/method1

모든 웹훅은 Google 클라이언트 라이브러리 또는 Node.js용 Google 인증 라이브러리와 같은 오픈소스 라이브러리를 사용하여 토큰을 선택적으로 검증할 수 있습니다.

웹훅이 Cloud Run에서 호스팅되고 부하 분산기를 통해 액세스되는 경우 부하 분산기의 URL을 Cloud Run에 맞춤 잠재고객으로 추가합니다. 커스텀 대상에 대한 자세한 내용은 서비스에 커스텀 대상 설정하기를 참고하세요.

서비스 계정

서비스 계정을 사용하여 웹훅 요청을 지원하는 Google API에 인증할 수 있습니다.

아직 서비스 계정을 만들지 않았다면 서비스 계정을 만듭니다.

서비스 계정은 주 구성원이므로 다른 주 구성원과 마찬가지로 역할을 부여하여 프로젝트의 리소스에 액세스할 수 있습니다. 서비스 계정 이메일은 웹훅 요청의 Authorization 헤더에 전송되는 액세스 토큰을 생성하는 데 사용됩니다.

서비스 계정을 사용하도록 웹훅을 구성하려면 다음 권한이 있어야 합니다.

roles/iam.serviceAccountUser

토큰을 생성하려면 Dialogflow 서비스 에이전트에 다음 권한이 있어야 합니다.

roles/iam.serviceAccountTokenCreator

또한 서비스 계정에는 웹훅을 호스팅하는 서비스에 액세스할 수 있는 권한이 있어야 합니다.

Secret Manager 인증

인증 헤더, 사용자 이름과 비밀번호를 사용한 기본 인증 또는 서드 파티 OAuth를 사용하는 경우 Secret Manager를 사용하여 사용자 인증 정보를 보안 비밀로 저장할 수 있습니다. 다음은 보안 비밀을 사용하여 웹훅을 인증하는 데 필요한 단계입니다.

보안 비밀이 없는 경우 보안 비밀을 만듭니다.
새 보안 비밀에 대한 Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 역할을 Dialogflow 서비스 에이전트에 부여합니다.
클립보드에 사용자 인증 정보를 복사합니다.
보안 비밀에 새 보안 비밀 버전을 추가하고 사용자 인증 정보를 보안 비밀 값으로 붙여넣습니다.
- 인증 헤더를 사용하는 경우 Bearer <YOUR_CREDENTIAL>를 입력합니다.
- 기본 사용자 이름 및 비밀번호 인증을 사용하는 경우 <YOUR_USERNAME>:<YOUR_PASSWORD>를 입력합니다.
- 끝에 있는 줄바꿈 문자는 생략합니다.
추가한 보안 비밀 버전의 이름을 복사합니다. 이름 형식은 projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>입니다.
웹훅 수정 화면을 엽니다.
인증 설정을 구성합니다.
- 인증 헤더를 사용하는 경우 새 보안 비밀 버전 요청 헤더를 만듭니다. 키 필드에 'Authorization'을 입력하고 보안 비밀 버전 필드에 보안 비밀 버전 이름을 붙여넣습니다.
- 기본 사용자 이름 및 비밀번호 인증의 경우 기본 인증에서 보안 비밀 버전을 클릭하고 보안 비밀 버전 이름을 보안 비밀 버전 필드에 붙여넣습니다.
- 서드 파티 OAuth를 사용하는 경우 서드 파티 OAuth 아래에서 보안 비밀 버전을 클릭하고 보안 비밀 버전 이름을 보안 비밀 버전 필드에 붙여넣습니다.
저장을 클릭합니다.

HTTPS 인증서 확인

Dialogflow CX는 기본적으로 Google의 기본 트러스트 저장소를 사용하여 HTTPS 인증서를 확인합니다. 자체 서명된 인증서 또는 커스텀 루트 인증서와 같이 Google의 기본 트러스트 저장소에서 인식하지 못하는 인증서를 HTTPS 서버에 사용하려면 커스텀 CA 인증서를 참고하세요.

환경별 웹훅

환경을 사용하여 프로덕션을 개발과 격리하는 경우 웹훅을 환경별로 구성할 수 있습니다. 각 웹훅 리소스에 환경별 URL 및 인증 설정을 제공할 수 있습니다.

이 구성을 사용하면 웹훅 코드 업데이트를 프로덕션 환경에 배포하기 전에 안전하게 개발하고 테스트할 수 있습니다.

웹훅 리소스 만들기 또는 수정

웹훅 서비스가 실행 중이면 에이전트에서 연결 및 인증 정보가 포함된 웹훅 리소스를 만듭니다. 언제든지 웹훅 리소스 설정을 수정할 수 있습니다.

웹훅 리소스를 만들거나 수정하려면 다음 안내를 따르세요.

콘솔

Dialogflow CX 콘솔을 엽니다.
프로젝트로 이동합니다.
에이전트를 선택합니다.
관리 탭을 클릭합니다.
웹훅을 클릭합니다.
만들기를 클릭하거나 기존 웹훅을 선택하여 수정합니다.
표준 웹훅 리소스 설정 또는 가변형 웹훅 리소스 설정을 구성합니다.
저장을 클릭합니다.

API

웹훅 리소스 만들기에 관한 자세한 내용은 Webhook 유형의 create 메서드를 참고하세요. 웹훅 리소스(환경별 설정 제외)를 수정하는 방법에 대한 자세한 내용은 Webhook 유형의 patch 또는 update 메서드를 참고하세요.

웹훅 참조의 프로토콜 및 버전 선택:

프로토콜	V3	V3beta1
REST	웹훅 리소스	웹훅 리소스
RPC	웹훅 인터페이스	웹훅 인터페이스
C++	WebhooksClient	해당 사항 없음
C#	WebhooksClient	해당 사항 없음
Go	WebhooksClient	해당 사항 없음
자바	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	없음	해당 사항 없음
Python	WebhooksClient	WebhooksClient
Ruby	없음	해당 사항 없음

웹훅의 환경별 설정을 수정하는 방법에 대한 자세한 내용은 Environment 유형의 patch 또는 update 메서드를 참고하세요.

환경 참조의 프로토콜 및 버전을 선택합니다.

프로토콜	V3	V3beta1
REST	환경 리소스	환경 리소스
RPC	환경 인터페이스	환경 인터페이스
C++	EnvironmentsClient	해당 사항 없음
C#	EnvironmentsClient	해당 사항 없음
Go	EnvironmentsClient	해당 사항 없음
자바	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	없음	해당 사항 없음
Python	EnvironmentsClient	EnvironmentsClient
Ruby	없음	해당 사항 없음

웹훅 오류

웹훅 서비스가 웹훅 요청을 처리하는 동안 오류가 발생하면 웹훅 코드가 다음 HTTP 상태 코드 중 하나를 반환해야 합니다.

400: 잘못된 요청
401: 승인되지 않음
403: 금지됨
404: 찾을 수 없음
500: 서버 오류
503: 서비스를 사용할 수 없음

Dialogflow CX는 다음과 같은 오류 상황에서 웹훅 오류 또는 제한 시간 기본 제공 이벤트를 호출하고 평소처럼 처리를 진행합니다.

응답 제한 시간을 초과했습니다.
오류 상태 코드가 수신됩니다.
응답이 잘못되었습니다.
웹훅 서비스를 사용할 수 없습니다.

인텐트 인식 API 호출에 의해 웹훅 서비스 호출이 트리거된 경우 인텐트 인식 응답의 queryResult.webhookStatuses 필드에 웹훅 상태 정보가 포함됩니다.

자동 재시도

Dialogflow CX는 안정성을 높이기 위해 특정 웹훅 오류가 발생하면 요청을 자동으로 재시도합니다. 자동 재시도는 기본적으로 사용 설정되어 있으며 사용 중지할 수 없습니다.

Dialogflow CX는 요청 시간 초과, 네트워크 연결 중단, 5xx 범위의 HTTP 상태 코드(예: 500 Server fault 또는 503 Service unavailable)와 같은 일시적인 오류에 대해 한 번의 재시도를 실행합니다. HTTP 상태 코드 404 Not found와 같은 터미널 클라이언트 오류는 재시도 없이 즉시 실패합니다.

누적 지연 시간 및 타임아웃 예산 책정

Dialogflow CX는 일시적인 실패를 한 번 재시도하므로 응답하지 않는 웹훅 엔드포인트로 인해 Dialogflow CX가 오류를 반환하기 전에 구성된 제한 시간 값의 최대 두 배에 달하는 누적 처리 시간이 발생할 수 있습니다. 예를 들어 기본 5초 제한 시간 설정의 경우 응답하지 않는 엔드포인트는 초기 시도에서 5초 후에 제한 시간이 초과되고 재시도에서 또 다른 5초 후에 제한 시간이 초과됩니다. 이로 인해 Dialogflow CX가 webhook.error.timeout 이벤트 핸들러 또는 sys.no-match-default 이벤트 핸들러와 같은 오류 핸들러를 호출하기 전까지 총 지연 시간이 약 10초가 됩니다.

아키텍처에 엄격한 업스트림 지연 시간 제한이 있는 경우 (예: 10초 제한 시간 창 후 통화를 종료하는 전화 통신 또는 대화형 음성 응답 (IVR) 시스템) 웹훅 제한 시간을 허용되는 창의 절반 (예: 2.5~4초)으로 설정하여 두 시도 모두에 예산을 할당합니다.

재시도 권장사항

웹훅 서비스에서 재시도를 효과적으로 처리하려면 다음 단계를 따르세요.

웹훅 서비스 로직에서 멱등성 또는 요청 중복 제거를 구현하여 중복 요청을 안전하게 처리합니다.
웹훅 작업이 구성된 제한 시간보다 오래 걸리는 경우 대체 메시지와 함께 즉각적인 HTTP 상태 코드 200 OK 응답을 반환하고 오래 실행되는 작업을 비동기식으로 처리합니다.

Cloud Run 사용

Dialogflow CX는 Cloud Run과 통합되므로 서버리스 보안 웹훅을 만들 수 있습니다. 에이전트와 동일한 프로젝트에 있는 Cloud Run 리소스를 만드는 경우 인증 구성에서 서비스 에이전트 인증을 선택한 다음 ID 토큰을 선택하여 에이전트가 웹훅을 안전하게 호출할 수 있도록 합니다.

다음 두 상황에서는 이 통합을 수동으로 설정해야 합니다.

에이전트 프로젝트에 다음 주소를 사용하는 Dialogflow CX Service Agent 서비스 계정이 있어야 합니다.
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
이 특수 서비스 계정과 연결된 키는 일반적으로 프로젝트의 첫 번째 에이전트를 만들 때 자동으로 생성됩니다. 에이전트를 2020년 11월 1일 이전에 만든 경우 이 특별 서비스 계정 생성을 트리거할 수 있습니다.
1. 프로젝트의 새 에이전트를 만듭니다.
2. 다음 명령어를 실행합니다.
```
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
```
웹훅 함수가 에이전트가 아닌 다른 프로젝트에 있는 경우 Cloud Run 리소스 프로젝트의 Dialogflow CX 서비스 에이전트 서비스 계정에 Cloud Run 호출자 또는 Cloud Functions 호출자 IAM 역할을 제공해야 합니다.

그런 다음 인증 구성 섹션에서 서비스 에이전트 인증 > ID 토큰을 선택합니다.

컨테이너화된 웹훅 및 Go ezcx 프레임워크 사용

Go를 사용하여 컨테이너화된 웹훅을 구현하려면 Go ezcx 프레임워크를 참고하세요. 이 프레임워크를 사용하면 웹훅을 만드는 데 필요한 여러 단계를 간소화할 수 있습니다.

내부 전용 트래픽에 Cloud Run 사용

에이전트가 동일한 프로젝트 또는 동일한 VPC 서비스 제어 경계에 있는 경우 동일한 프로젝트 또는 동일한 VPC 서비스 제어 경계에 있는 가상 프라이빗 클라우드 (VPC) 네트워크로부터 내부 트래픽을 수락하도록 구성된 Cloud Run 리소스를 웹훅으로 사용할 수 있습니다.

비공개 네트워크 액세스에 서비스 디렉터리 사용

Dialogflow CX는 서비스 디렉터리 비공개 네트워크 액세스와 통합되므로 VPC 네트워크 내의 웹훅 대상에 연결할 수 있습니다. 이렇게 하면 트래픽이 Google Cloud 네트워크 내에서 유지되며 IAM 및 VPC 서비스 제어가 적용됩니다.

비공개 네트워크를 타겟팅하는 웹훅을 설정하려면 다음 안내를 따르세요.

서비스 디렉터리 비공개 네트워크 구성에 따라 VPC 네트워크와 서비스 디렉터리 엔드포인트를 구성합니다.

참고: Dialogflow CX는 90초 동안 서비스 디렉터리 정보를 캐시합니다. 즉, 서비스 디렉터리 엔드포인트를 업데이트하는 경우 변경사항이 적용되는 데 90초가 소요됩니다.
에이전트 프로젝트에 다음 주소를 사용하는 Dialogflow CX 서비스 에이전트 서비스 계정이 있어야 합니다.
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
서비스 디렉터리가 있는 프로젝트에서 Dialogflow CX 서비스 에이전트 서비스 계정에 다음 역할을 부여합니다.
- servicedirectory.viewer
- servicedirectory.pscAuthorizedService
또한 서비스 디렉터리가 Dialogflow CX 에이전트와 다른 프로젝트에 있는 경우 Dialogflow CX 에이전트를 호스팅하는 프로젝트의 Dialogflow CX 서비스 에이전트 계정에 servicedirectory.viewer 역할을 부여해야 합니다.

웹훅을 만들 때 서비스 디렉터리 서비스, URL, 선택적 인증 정보를 지정합니다.

콘솔

서비스 디렉터리 웹훅 스크린샷

API

Webhook 유형의 serviceDirectory 필드를 참조하세요.