Actions SDK를 사용하여 Google 어시스턴트 작업 빌드하기(레벨 1)

Google 어시스턴트 개발자 플랫폼을 사용하면 스마트 스피커, 스마트폰, 자동차, TV, 헤드폰 등 10억 대 이상의 기기에서 가상 개인 비서인 Google 어시스턴트의 기능을 확장하는 소프트웨어를 만들 수 있습니다. 사용자는 어시스턴트와의 대화를 통해 식료품 구매, 택시 예약과 같은 작업을 수행할 수 있습니다. 개발자는 어시스턴트 개발자 플랫폼을 사용하여 사용자와 타사 처리 서비스 간의 즐겁고 효과적인 대화 환경을 쉽게 만들고 관리할 수 있습니다.

이 Codelab에서는 Google 어시스턴트용 Actions SDK 개발을 위한 초보자 수준의 개념을 다룹니다. 이전에 플랫폼을 사용해 본 경험이 없어도 괜찮습니다. 이 Codelab에서는 그리핀버그라는 신화 속 세상으로 모험을 떠나는 사용자에게 운세를 알려주는 간단한 Google 어시스턴트 작업을 빌드해 봅니다. Actions SDK 레벨 2 Codelab에서는 이 작업을 좀 더 발전시켜서 사용자의 입력 내용을 바탕으로 사용자의 운세를 맞춤설정합니다.

빌드할 항목

이 Codelab에서는 다음과 같은 함수를 사용하여 간단한 작업을 빌드합니다.

• 인사 메시지로 사용자에게 응답합니다.
• 사용자에게 질문을 합니다. 사용자가 응답하면 작업이 사용자의 선택에 적절하게 응답합니다.
• 사용자가 클릭하여 입력할 수 있는 추천 검색어 칩이 제공됩니다.
• 재사용자인지에 따라 사용자에게 건네는 인사 메시지를 수정합니다.

이 Codelab을 완료하면 완성된 작업은 다음과 같은 대화 흐름을 갖게 됩니다(마이크 옆의 텍스트는 사용자의 입력을, 스피커 옆의 텍스트는 작업의 응답을 나타냄).

학습할 내용

• Actions 콘솔에서 프로젝트를 만드는 방법
• gactions 도구를 사용하여 Actions 콘솔과 로컬 파일 시스템 간에 작업 프로젝트를 푸시하고 가져오는 방법
• 작업 호출 후 사용자에게 프롬프트를 보내는 방법
• 사용자 입력을 처리하고 응답을 반환하는 방법
• Actions 시뮬레이터에서 작업을 테스트하는 방법
• Cloud Functions 편집기를 사용하는 처리를 구현하는 방법

준비물

환경에 다음 도구가 있어야 합니다.

• 원하는 IDE/텍스트 편집기
• NodeJS 및 npm용 셸 명령어를 실행하는 터미널
• Chrome과 같은 웹브라우저

참고: 작업을 빌드하는 데 시각적 도구를 많이 사용하는 것을 선호한다면 Actions Builder(레벨 1) Codelab을 사용하여 Google 어시스턴트 작업 빌드하기를 대신 진행해 보세요. 여기에서는 콘솔 내 Actions Builder IDE를 사용하여 동일한 작업을 빌드합니다.

다음 섹션에서는 개발 환경을 설정하고 작업 프로젝트를 만드는 방법을 설명합니다.

Google 권한 설정 확인하기

이 Codelab에서 빌드하는 작업을 테스트하려면 시뮬레이터가 작업에 액세스할 수 있도록 필요한 권한을 사용 설정해야 합니다.

권한을 사용 설정하려면 다음 단계를 따르세요.

1. 활동 제어 페이지로 이동합니다.
2. 아직 Google 계정으로 로그인하지 않았다면 로그인합니다.
3. 다음 권한을 사용 설정합니다.

• 웹 및 앱 활동
• 웹 및 앱 활동에서 Chrome 방문 기록 및 Google 서비스를 사용하는 사이트, 앱, 기기의 활동 포함 옆의 체크박스를 선택합니다.

작업 프로젝트 만들기

작업 프로젝트는 작업의 컨테이너입니다.

이 Codelab의 작업 프로젝트를 만들려면 다음 단계를 따르세요.

1. Actions 콘솔을 엽니다.
2. New project를 클릭합니다.
3. 프로젝트 이름(예: actions-codelab)을 입력합니다. (내부 참고용 이름입니다. 나중에 프로젝트의 외부 이름을 설정할 수 있습니다.)

4. Create project를 클릭합니다.
5. 어떤 종류의 작업을 빌드하고 싶으신가요? 화면에서 Custom 카드를 선택합니다. Next를 클릭합니다.
6. 어떻게 빌드하고 싶으신가요? 화면에서 Blank project 카드를 선택합니다. 그런 다음 Start building을 클릭합니다.

작업의 프로젝트 ID 저장하기

프로젝트 ID는 작업의 고유 식별자입니다. 이 Codelab의 여러 단계에 프로젝트 ID가 필요합니다.

프로젝트 ID를 검색하려면 다음 단계를 따르세요.

1. Actions 콘솔에서 오른쪽 상단의 세로로 나열된 3개의 점(여기에 아이콘 삽입)을 클릭합니다.
2. Project settings를 클릭합니다.

3. 프로젝트 ID를 복사합니다.

결제 계정 연결하기

나중에 Cloud Functions를 사용하여 이 Codelab에 처리를 배포하려면 결제 계정을 Google Cloud의 프로젝트와 연결해야 합니다. 이미 결제 계정이 있다면 다음 단계를 무시해도 됩니다.

결제 계정을 프로젝트에 연결하려면 다음 단계를 따르세요.

1. Google Cloud Platform 결제 페이지로 이동합니다.
2. Add billing account를 클릭합니다.
3. 결제 정보를 입력하고 Start my free trial 또는 Submit and enable billing을 클릭합니다.
4. 페이지 상단에서 My Projects 탭을 클릭합니다.
5. Codelab의 작업 프로젝트 옆에 있는 Actions 아래에서 점 3개를 클릭합니다.
6. Change billing을 클릭합니다.
7. 드롭다운 메뉴에서 구성한 결제 계정을 선택합니다. Set account를 클릭합니다.

요금이 청구되지 않도록 하려면 이 Codelab의 끝에 있는 'Next steps' 페이지의 'Clean up your project' 섹션에 나와 있는 단계를 따르세요.

gactions 명령줄 인터페이스 설치하기

이 Codelab에서는 gactions 명령줄 인터페이스(CLI) 도구를 사용하여 Actions 콘솔과 로컬 파일 시스템 간에 작업 프로젝트를 동기화합니다.

주요 용어:

• gactions CLI: 작업 프로젝트 파일을 초기화하고 Actions 콘솔로 업데이트를 푸시하며 작업 프로젝트를 배포하는 등의 작업이 가능한 도구입니다.

gactions CLI를 설치하려면 gactions 명령줄 도구 설치 섹션의 안내를 따르세요.

작업 프로젝트 다운로드하기

Actions 콘솔에서 작업 프로젝트를 다운로드하여 작업 개발을 시작합니다.

작업 프로젝트를 다운로드하려면 다음 단계를 따르세요.

1. 새 디렉터리를 만들어 해당 디렉터리로 변경하려면 다음 명령어를 실행합니다.

mkdir myproject
cd myproject

2. 작업 프로젝트의 구성을 로컬 파일 시스템에 복사하려면 다음 명령어를 실행합니다.

gactions pull --project-id <projectID>

파일 구조 이해하기

Actions 콘솔에서 다운로드한 작업 프로젝트는 YAML 파일 구조로 표시됩니다. 다음 이미지는 파일 구조를 대략적으로 보여줍니다.

파일 구조는 다음으로 구성됩니다.

• actions/: 작업 프로젝트를 나타냅니다. 작업이 호출되면 시스템에서는 actions.yaml을 호출하며, 이는 custom/global/actions.intent.MAIN.yaml 파일을 호출합니다.
• custom/: 작업을 수정하는 데 사용할 디렉터리입니다.
• global/: 이 디렉터리에는 플랫폼에서 프로젝트에 자동으로 추가하는 시스템 인텐트가 포함됩니다. 이 Codelab의 뒷부분에서 시스템 인텐트에 관해 자세히 알아봅니다.
• manifest.yaml: '전송 가능'한 정보가 포함된 파일입니다. 즉, 특정 프로젝트에 한정되지 않고 프로젝트 사이를 이동할 수 있습니다.
• settings/: 표시 이름, 기본 언어, 카테고리와 같은 작업 프로젝트의 설정을 나타냅니다.

사용자는 호출을 통해 작업과 대화를 시작합니다. 예를 들어 MovieTime이라는 작업이 있고 MovieTime이 표시 이름이라면 사용자는 "Hey Google, MovieTime에 연결해 줘"와 같은 문장을 말해서 작업을 호출할 수 있습니다. 작업을 프로덕션으로 배포하려면 표시 이름이 있어야 합니다. 그러나 작업을 테스트하기 위해서는 표시 이름을 정의할 필요가 없습니다. 대신 시뮬레이터에서 "테스트 앱에 연결해 줘" 구문을 사용하여 작업을 호출할 수 있습니다. 이 섹션의 뒷부분에서 시뮬레이터에 관해 자세히 알아보세요.

사용자가 작업을 호출한 후 발생하는 결과를 정의하려면 기본 호출을 수정해야 합니다.

주요 용어:

• 기본 호출: 사용자가 작업과의 대화를 시작하는 진입점입니다. 사용자가 "Hey Google, <display name>에 연결해줘"와 비슷한 문구를 말하면 기본 호출이 트리거되어 사용자에게 응답합니다.

호출이 트리거되면 기본적으로 작업은 일반적인 프롬프트를 제공합니다('Start building your Action by defining main invocation.').

주요 용어:

• 프롬프트: 작업이 응답으로 사용자에게 전송하는 내용을 정의합니다. 프롬프트는 단순한 텍스트, 음성 응답 또는 카드, 이미지와 같은 리치 메시지일 수 있습니다.

특수 프롬프트 Canvas를 사용하여 전체 화면 시각 자료를 사용자에게 반환할 수도 있습니다. Canvas에 관한 자세한 내용은 대화형 캔버스 문서를 참고하세요.

다음 섹션에서는 custom/global/actions.intent.MAIN.yaml 파일의 기본 호출 메시지를 맞춤설정합니다.

기본 호출 설정하기

actions.intent.MAIN.yaml 파일에서 기본 호출 프롬프트를 수정할 수 있습니다.

사용자가 작업을 호출할 때 작업에서 사용자에게 보내는 메시지를 수정하려면 다음 단계를 따르세요.

1. 텍스트 편집기에서 custom/global/actions.intent.MAIN.yaml을 엽니다.
2. speech 필드(Start building your action...)의 텍스트를 다음 환영 메시지로 대체합니다. A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of
                Gryffinberg! Based on your clothes, you are not from around these lands.
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. 파일을 저장합니다.

시뮬레이터에서 기본 호출 테스트하기

Actions 콘솔은 작업을 테스트할 수 있는 웹 도구인 시뮬레이터를 제공합니다. 이 인터페이스는 하드웨어 기기 및 설정을 시뮬레이션하므로 스마트 디스플레이, 휴대전화, 스피커 또는 KaiOS에서 실행 중인 것처럼 작업과 연결할 수 있습니다.

참고: Actions Simulator 가이드에서 Actions 콘솔 시뮬레이터를 사용하는 방법에 관한 최신 정보를 확인할 수 있습니다. 다음 단계에 따르던 중 문제가 발생하면 이 가이드를 참고하세요.

이제 작업을 호출하면 사용자가 추가한 맞춤설정 프롬프트('A wondrous greeting, adventurer!...')로 응답해야 합니다.

gactions deploy preview 명령어를 사용하면 작업 프로젝트의 버전을 업데이트하지 않고도 콘솔에서 작업을 테스트할 수 있습니다. 이 명령어를 실행하면 로컬 파일 시스템에서 변경한 사항이 작업 프로젝트의 배포된 버전에 적용되지는 않지만, 미리보기 버전에서 이러한 변경사항을 테스트할 수는 있습니다.

시뮬레이터에서 작업의 기본 호출을 테스트하려면 다음 단계를 따르세요.

1. 테스트를 위해 프로젝트를 Actions 콘솔에 배포하려면 터미널에서 다음 명령어를 실행합니다.

gactions deploy preview

참고: 이 명령어를 실행하면 유효성 검사 문제에 관한 알림이 전송될 수 있습니다. 파일이 푸시되어 있는 동안에는 이 알림을 무시해도 됩니다.

다음과 같은 출력이 표시됩니다.

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. 시뮬레이터에서 작업을 호출하려면 왼쪽 상단의 Input 필드에 Talk to my test app을 입력하고 Enter 키를 누릅니다.

도움말: 사용자가 말하거나 입력하는 내용과 동일한 방식으로 처리되는 Suggestions의 Talk to my test app 추천 검색어 칩을 클릭하거나 마이크 아이콘을 클릭하고 "테스트 앱에 연결해 줘"라고 말해도 작업을 호출할 수 있습니다.

작업의 기본 호출을 트리거하면 어시스턴트가 맞춤설정된 시작 메시지로 응답합니다. 이때는 어시스턴트가 인사로 응답하고 나면 대화가 종료됩니다. 다음 섹션에서는 대화가 이어지도록 작업을 수정해 봅니다.

이벤트 로그 보기

Actions 콘솔의 Test 탭에서는 오른쪽 패널에 이벤트 로그가 표시되며, 여기에서는 대화 기록을 이벤트 로그로 보여줍니다. 각 이벤트 로그는 대화가 이어지는 동안 발생하는 이벤트를 보여줍니다.

작업에는 현재 이벤트 로그가 하나 있으며 사용자의 입력("테스트 앱에 연결해줘")과 작업의 응답을 모두 보여줍니다. 다음 스크린샷은 작업의 이벤트 로그를 보여줍니다.

이벤트 로그에서 Talk to my test app 옆에 있는 아래쪽 화살표를 클릭하면 대화가 이어진 시간순으로 정렬된 이벤트를 볼 수 있습니다.

• userInput: 사용자의 입력("테스트 앱에 연결해줘")에 해당합니다.
• interactionMatch: 사용자의 입력으로 트리거된 작업의 기본 호출 응답에 해당합니다. 화살표를 클릭하여 이 행을 펼치면 기본 응답에 추가한 프롬프트(A wondrous greeting, adventurer!...)를 확인할 수 있습니다.
• endConversation: Main invocation 인텐트에서 선택된 전환에 해당하며, 이것으로 현재 대화를 종료합니다. 전환에 관해서는 이 Codelab의 다음 섹션에서 자세히 알아봅니다.

이벤트 로그를 통해 작업의 진행 상태를 파악할 수 있으며, 문제가 있을 경우 작업을 디버깅하는 데 유용한 도구로 사용할 수도 있습니다. 이벤트 세부정보를 확인하려면 다음 스크린샷에 표시된 것처럼 이벤트 이름 옆의 화살표를 클릭합니다.

사용자가 작업을 호출한 후 발생하는 결과를 정의했으므로 이제 작업의 나머지 대화를 빌드할 수 있습니다. 이 Codelab을 계속하기 전에 작업의 대화가 어떻게 작동하는지 이해할 수 있도록 다음 용어를 숙지하시기 바랍니다.

핵심 용어:

• 테마: 사용자 입력을 처리하고 보통 사용자를 대상으로 응답을 생성하는 작업의 '구성요소'입니다. 맞춤 인텐트로 다른 테마를 활성화하는 경우가 많지만 테마는 다른 방식으로도 활성화될 수 있습니다.
• 맞춤 인텐트: 작업에서 이해할 수 있는 사용자 입력을 정의합니다. 사용자가 이러한 인텐트의 학습 문구를 정의합니다. 사용자가 학습 문구와 일치하거나 비슷한 문구를 말하면 해당하는 인텐트가 일치됩니다.
• 학습 문구: 사용자가 말하는 내용 중 인텐트와 일치하는 문구의 예입니다. 어시스턴트 NLU(자연어 이해) 엔진은 다른 유사한 문구를 포함하도록 이러한 학습 문구를 자연스럽게 확장합니다.
• 전환: 조건이 충족되면 전환할 테마를 정의합니다.

작업에는 테마가 하나 이상 포함될 수 있으며 각 테마를 활성화해야 실행할 수 있습니다. 이 Codelab에서 빌드하는 작업에는 Start라는 테마 하나만 있습니다. 테마를 활성화하는 가장 일반적인 방법은 사용자 입력이 테마 내의 인텐트와 일치할 경우 해당 인텐트가 다른 테마로의 전환을 트리거하고 활성화하도록 작업을 구성하는 것입니다.

예를 들어 사용자에게 동물에 관한 정보를 제공하는 가상의 작업이 있다고 가정해 보겠습니다. 사용자가 이 작업을 호출하면 Main invocation 인텐트가 일치되고 Facts.라는 테마로의 전환이 트리거됩니다. 이 전환은 Facts 테마를 활성화하고, 이 테마는 사용자에게 다음 프롬프트를 전송합니다. Would you like to hear a fact about cats or dogs? Facts 테마 내에 Cat이라는 맞춤 인텐트가 있으며 여기에는 "고양이 상식을 알려줘" 또는 "고양이"와 같이 사용자가 고양이에 관한 상식을 알아보기 위해 말할 수 있는 학습 문구가 포함됩니다. 사용자가 고양이 상식을 물으면 Cat 인텐트가 일치되고 Cat fact.라는 테마로의 전환이 트리거됩니다. Cat fact 테마가 활성화되고 사용자에게 고양이 상식이 포함된 프롬프트가 전송됩니다.

그림 1. Actions SDK로 빌드된 작업의 일반적인 대화 흐름.

테마, 인텐트, 전환이 모여 대화의 로직을 이루며 작업의 대화에서 사용자가 진행할 수 있는 다양한 경로를 정의합니다. 다음 섹션에서는 테마를 만들고, 사용자가 작업을 호출한 후 테마가 활성화되는 방식을 정의합니다.

기본 호출에서 테마로 전환하기

이 섹션에서는 사용자에게 프롬프트를 전송하여 운세를 원하는지 묻는 Start라는 새 테마를 만듭니다. 또한 기본 호출에서 새 Start 테마로의 전환도 추가합니다.

이 테마를 만들고 전환을 추가하려면 다음 단계를 따르세요.

1. 텍스트 편집기에서 custom/global/actions.intent.MAIN.yaml을 엽니다.
2. transitionToScene 필드의 텍스트(actions.scene.END_CONVERSATION)를 transitionToScene: Start로 바꿉니다.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

기본 호출에서 Start 테마로 전환하도록 작업에 알려줍니다.

3. 파일을 저장합니다.
4. 터미널에서 custom 디렉터리에 새 scenes 디렉터리를 만듭니다.

mkdir custom/scenes

5. scenes 디렉터리에서 Start.yaml이라는 새 파일을 만듭니다. 이 파일은 작업의 start 테마를 나타냅니다.

touch custom/scenes/Start.yaml

6. 텍스트 편집기에서 Start.yaml을 엽니다.
7. 다음 코드를 Start.yaml 파일에 붙여 넣습니다.

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

Start.yaml 파일 코드에는 테마의 수명 주기에서 실행되는 첫 번째 단계인 onEnter라는 필드가 있습니다.

핵심 용어:

• OnEnter: 테마가 활성화되면 실행되는 단계입니다. OnEnter는 사용자가 테마에 들어가면 발생하는 결과를 정의합니다.

이 경우 사용자가 처음 Start 테마에 들어가면 프롬프트(Before you continue on your quest...)가 프롬프트 대기열에 추가됩니다.

핵심 용어:

• 프롬프트 대기열: 프롬프트는 프롬프트 대기열의 다른 프롬프트에 추가됩니다. 사용자가 응답하기 전에 어시스턴트는 사용자에게 프롬프트 대기열의 모든 프롬프트를 제시합니다.

추천 검색어 칩 추가하기

추천 검색어 칩은 클릭 가능한 추천 검색어를 사용자에게 제공하며, 작업은 이 추천 검색어를 사용자 입력으로 처리합니다. 이 섹션에서는 화면을 통해 기기에서 사용자를 지원하기 위해 방금 구성한 프롬프트(Before you continue on your quest, would you like your fortune told?) 아래에 표시할 Yes 및 No 추천 검색어 칩을 추가합니다.

Start 테마의 프롬프트에 추천 검색어 칩을 추가하려면 다음 단계를 따르세요.

1. Start.yaml에서 코드를 업데이트하여 다음 코드 스니펫을 일치시킵니다. 여기에는 추천 검색어 칩의 구성을 위한 코드가 포함됩니다.

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. 파일을 저장합니다.

시뮬레이터에서 작업 테스트하기

이때 작업은 기본 호출에서 Start 테마로 전환되고, 사용자에게 운세를 듣고 싶은지를 묻습니다. 추천 검색어 칩은 시뮬레이션된 디스플레이에도 나타나야 합니다.

시뮬레이터에서 작업을 테스트하려면 다음 단계를 따르세요.

1. 터미널에서 다음 명령어를 실행합니다.

gactions deploy preview

다음과 같은 출력이 표시됩니다.

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. Test를 클릭하여 시뮬레이터로 이동합니다.
4. 왼쪽 상단의 Input 필드에 Talk to my test app을 입력합니다. 그런 다음 Enter 키를 누릅니다. 작업이 Main invocation 프롬프트와 추가된 Start 테마 프롬프트인 'Before you continue on your quest, would you like your fortune told?'로 응답하고 추천 검색어 칩이 표시됩니다.

다음 스크린샷은 이러한 상호작용을 보여줍니다.

참고: 이벤트 로그는 현재 세션의 각 시뮬레이터 상호작용을 기록하므로 이 Codelab에서 이전에 이루어진 테스팅의 이벤트 로그는 첫 이벤트 로그로 표시됩니다. 이벤트 로그를 지우려면 Reset Test를 클릭합니다.

5. Yes 또는 No 추천 검색어 칩을 클릭하여 프롬프트에 응답합니다. ('Yes' 또는 'No'라고 말하거나 Input 필드에 Yes 또는 No를 입력할 수도 있습니다.)

프롬프트에 응답하면 작업이 다음과 같이 입력을 이해할 수 없다는 내용의 메시지로 응답합니다. 'Sorry, I didn't catch that. Can you try again?' 아직 'Yes' 또는 'No' 입력을 이해하고 이에 응답하도록 작업을 구성하지 않았으므로 작업은 입력을 NO_MATCH 인텐트와 일치시킵니다.

핵심 용어:

• NO_MATCH: 사용자가 말한 내용인 작업의 다른 인텐트와 일치하지 않을 경우 일치되는 포괄적 인텐트입니다.
• 시스템 인텐트: 기본적으로 구성되어 있어서 사용자가 입력을 제공하지 않는 경우와 같이 일반적인 시스템 이벤트를 처리하는 인텐트입니다. NO_MATCH와 기본 호출에 연결된 인텐트가 시스템 인텐트의 예입니다.

기본적으로 NO_MATCH 시스템 인텐트는 일반적인 응답을 제공하지만 응답을 맞춤설정하여 응답을 이해하지 못했음을 사용자에게 알릴 수 있습니다. 어시스턴트는 사용자의 입력을 세 번 일치시킬 수 없을 때 사용자의 대화를 종료합니다.

yes 및 no 인텐트 추가하기

이제 작업이 제기하는 질문에 사용자가 응답할 수 있으므로 사용자의 응답('Yes' 또는 'No')을 이해하도록 작업을 구성할 수 있습니다. 다음 섹션에서는 사용자가 'Yes' 또는 'No'라고 말할 때 일치시킬 맞춤 인텐트를 만들고 이러한 인텐트를 Start 테마에 추가합니다.

yes 인텐트 만들기

yes 인텐트를 만들려면 다음 단계를 따르세요.

1. 터미널에서 custom 디렉터리에 intents라는 새 디렉터리를 만듭니다.

mkdir custom/intents

2. intents 디렉터리에 yes.yaml이라는 새 파일을 만듭니다.

touch custom/intents/yes.yaml

3. 텍스트 편집기에서 yes.yaml을 엽니다.
4. 학습 문구가 포함된 다음 코드 스니펫을 yes.yaml에 붙여넣습니다.

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. 파일을 저장합니다.

Start 장면에 yes 인텐트 추가하기

이제 작업에서 사용자가 "yes" 인텐트를 표시할 때를 파악할 수 있습니다. 사용자가 Start 프롬프트('Before you continue on your quest, would you like your fortune told?')에 응답하면 사용자는 yes 맞춤 인텐트를 Start 테마에 추가할 수 있습니다.

이 커스텀 인텐트를 Start 테마에 추가하려면 다음 단계를 따르세요.

1. 텍스트 편집기에서 custom/scenes/Start.yaml을 엽니다.
2. Start.yaml 파일의 끝에 intentEvents 및 yes 핸들러를 추가합니다.

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

yes 인텐트가 일치하면 "Your future depends on the item you choose to use for your quest..."라는 프롬프트가 대기열에 추가됩니다. 그러면 Start 테마가 actions.scene.END_CONVERSATION 시스템 테마로 전환되고 프롬프트 대기열의 프롬프트를 전달한 다음 대화를 종료합니다.

시뮬레이터에서 yes 인텐트 테스트하기

이때 작업은 사용자가 운세를 원하는지를 이해하고 적절한 응답을 반환합니다.

시뮬레이션에서 이 인텐트를 테스트하려면 다음 단계를 따르세요.

1. 터미널에서 다음 명령어를 실행합니다.

gactions deploy preview

다음과 같은 출력이 표시됩니다.

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. Test를 클릭하여 시뮬레이터로 이동합니다.
4. 시뮬레이터에서 작업을 테스트하려면 왼쪽 상단의 Input 필드에 Talk to my test app을 입력하고 Enter 키를 누릅니다.
5. Input 필드에 Yes를 입력하고 Enter 키를 누릅니다. 또는 Yes 추천 검색어 칩을 클릭합니다.

작업이 사용자에게 응답하고 운세는 선택한 도움에 따라 달라진다고 말합니다. 이제 yes 인텐트의 End conversation 전환이 구성되었으므로 작업이 세션을 종료합니다.

no 인텐트 만들기

이제 사용자가 운세를 듣고 싶지 않은 경우를 작업이 이해하고 이에 대응할 수 있도록 no 인텐트를 만들 수 있습니다.

이 인텐트를 만들려면 다음 단계를 따르세요.

1. 터미널에서 intents 디렉터리에 no.yaml이라는 새 파일을 만듭니다.

touch custom/intents/no.yaml

2. 텍스트 편집기에서 no.yaml을 엽니다.
3. 다음 학습 문구를 no.yaml 파일에 붙여넣습니다.

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. 파일을 저장합니다.

Start 장면에 no 인텐트 추가하기

이제 사용자가 'No' 또는 'Nope'과 같이 'No'와 비슷한 표현을 할 경우 작업이 이해할 수 있습니다. 사용자가 Start 프롬프트('Before you continue on your quest, would you like your fortune told?')에 응답하므로 no 맞춤 인텐트를 Start 테마에 추가해야 합니다.

Start 테마에 이 인텐트를 추가하려면 다음 단계를 따르세요.

1. 텍스트 편집기에서 custom/scenes/Start.yaml을 엽니다.
2. Start.yaml의 yes 핸들러 아래에 다음 no 핸들러를 추가합니다.

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. 파일을 저장합니다.

시뮬레이터에서 no 인텐트 테스트하기

이때 사용자가 운세를 듣고 싶지 않을 경우 작업이 이를 이해하고 적절한 응답을 반환합니다.

시뮬레이션에서 이 인텐트를 테스트하려면 다음 단계를 따르세요.

1. 터미널에서 다음 명령어를 실행합니다.

gactions deploy preview

다음과 같은 출력이 표시됩니다.

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. Test를 클릭하여 시뮬레이터로 이동합니다.
4. Input 필드에 Talk to my test app을 입력하고 Enter 키를 누릅니다.
5. Input 필드에 No를 입력하고 Enter 키를 누릅니다. 또는 No 추천 검색어 칩을 클릭합니다.

사용자에게 운세를 알려주는 대신 작업이 여정에 행운이 깃들기를 기원해 줍니다. 이제 no 인텐트의 End conversation 전환이 구성되었으므로 작업이 세션을 종료합니다.

현재 작업의 응답은 정적입니다. 프롬프트가 포함된 테마가 활성화되면 작업이 그때마다 동일한 프롬프트를 전송합니다. 이 섹션에서는 동적 대화 응답을 구성하는 로직이 포함된 처리를 구현합니다.

주요 용어:

• 처리: 작업의 로직을 포함하는 코드입니다. 웹훅은 작업 내에서 발생하는 이벤트를 기반으로 처리에 관한 호출을 트리거합니다.

처리는 사용자가 재사용자인지 신규 사용자인지를 식별하고 재사용자에게 표시하는 인사 메시지를 수정합니다. 재사용자에게 표시되는 인사 메시지는 다음과 같이 축약되며 사용자의 재방문을 확인합니다. 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!'

이 Codelab에서는 Cloud Functions 편집기를 사용하여 처리 코드를 수정하고 배포합니다.

주요 용어:

• Cloud Functions 편집기: 작업 프로젝트용 통합 편집기로, Firebase용 Cloud Functions로 처리 코드를 수정하고 배포하는 데 사용할 수 있습니다.

작업이 호출 중 또는 테마 실행의 특정 부분에서 발생한 이벤트의 처리를 알리는 웹훅을 트리거할 수 있습니다. 웹훅이 트리거되면 작업이 이벤트 처리에 사용할 핸들러의 이름과 함께 JSON 페이로드가 포함된 요청을 처리로 전송합니다. 이 핸들러는 일부 로직을 수행하고 해당 JSON 응답을 반환합니다.

처리 빌드하기

이 섹션에서는 처리를 수정하여 재사용자와 신규 사용자가 작업을 호출할 때 서로 다른 프롬프트를 생성합니다.

처리에 이 로직을 추가하려면 다음 단계를 따르세요.

1. 터미널에서 프로젝트의 루트 디렉터리에 있는지 확인하고 새 webhooks 디렉터리를 만듭니다.

mkdir webhooks

2. webhooks 디렉터리에 ActionsOnGoogleFulfillment.yaml이라는 새 파일을 만듭니다.

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. 텍스트 편집기에서 ActionsOnGoogleFulfillment.yaml을 엽니다.
4. ActionsOnGoogleFulfillment.yaml 파일에 greeting 핸들러와 inlineCloudFunction 콘텐츠를 추가합니다.

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

ActionsOnGoogleFulfillment.yaml 파일은 greeting 핸들러와 같은 웹훅 핸들러를 정의하고 Cloud Functions를 웹훅 엔드포인트로 사용하도록 작업에 알립니다.

5. webhooks 디렉터리에 새 ActionsOnGoogleFulfillment 디렉터리를 만듭니다.

mkdir webhooks/ActionsOnGoogleFulfillment

6. ActionsOnGoogleFulfillment 디렉터리에 index.js라는 새 파일을 만듭니다.

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. 텍스트 편집기에서 index.js를 엽니다.
8. 다음 코드를 index.js에 추가합니다.

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

이 코드는 적절한 인사말을 사용자에게 전송하는 greeting 핸들러를 정의합니다.

9. 파일을 저장합니다.
10. ActionsOnGoogleFulfillment 디렉터리에 package.json이라는 새 파일을 만듭니다.

touch webhooks/ActionsOnGoogleFulfillment/package.json

package.json 파일이 웹훅의 종속 항목과 기타 메타데이터를 지정합니다.

11. 텍스트 편집기에서 package.json을 엽니다.
12. 이 GitHub 저장소에서 코드를 복사하여 package.json 파일에 붙여넣습니다.
13. 파일을 저장합니다.

코드 이해하기

처리는 Node.js용 Actions on Google 처리 라이브러리를 사용하며 Google 어시스턴트의 HTTP 요청에 응답합니다.

이전 코드 스니펫에서 greeting 핸들러를 정의하며, 이 핸들러는 사용자가 이전에 lastSeenTime 속성으로 작업을 이용한 적이 있는지 확인합니다. lastSeenTime 속성이 정의되지 않으면 신규 사용자인 경우 신규 사용자를 위한 인사말이 표시됩니다. 그렇지 않으면 메시지가 사용자를 재사용자로 확인하고 수정된 인사말을 생성합니다.

기본 호출을 업데이트하여 웹훅 트리거하기

greeting 함수를 정의했으니 이제 사용자가 작업을 호출하면 작업이 이 함수를 불러올 수 있도록 기본 호출 인텐트에서 greeting 이벤트 핸들러를 구성할 수 있습니다.

새로운 greeting 핸들러를 호출하는 작업을 구성하려면 다음 단계를 따르세요.

1. 텍스트 편집기에서 custom/global/actions.intent.MAIN.yaml을 엽니다.
2. actions.intent.MAIN.yaml의 코드를 다음 코드로 바꿉니다.

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. 파일을 저장합니다.

이제 기본 호출 인텐트가 일치하면 greeting 웹훅 핸들러가 호출됩니다.

시뮬레이터에서 업데이트된 기본 호출 테스트하기

시뮬레이터에서 작업을 테스트하려면 다음 단계를 따르세요.

1. 터미널에서 다음 명령어를 실행합니다.

참고: 이 명령어는 웹훅을 배포하고 종속 항목을 설치하므로 이전 명령어보다 오래 걸릴 수 있습니다.

gactions deploy preview

주의: Cloud Build API에 관한 403 오류 또는 결제 계정 연결에 관한 403 오류가 발생할 경우 결제 계정 연결을 위한 프로젝트의 결제 설정 변경 페이지를 확인합니다. Cloud Functions를 사용하여 배포하려면 결제 계정을 Google Cloud의 프로젝트와 연결해야 합니다. 결제 계정을 연결한 후 gactions deploy preview를 다시 실행합니다. 요금이 청구되지 않도록 하려면 이 Codelab의 끝에 있는 'Next steps' 페이지의 'Clean up your project' 섹션에 나와 있는 단계를 따르세요.

다음과 같은 출력이 표시됩니다.

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. 시뮬레이터에서 작업을 테스트하려면 Input 필드에 Talk to my test app을 입력하고 Enter 키를 누릅니다.

앞서 이 Codelab에서 작업을 테스트 했으므로 다음과 같이 축약된 인사말이 표시됩니다. 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!...'

Actions SDK는 Actions 콘솔에 통합된 웹 기반 IDE인 Actions Builder와 상호 운용이 가능합니다. gactions push 명령어로 콘솔에서 작업의 초안으로 로컬 파일 시스템을 푸시할 수 있습니다. 시뮬레이터에서 작업을 테스트할 수 있는 gactions deploy preview와 달리 gactions push는 로컬 파일의 모든 콘텐츠를 Actions Builder로 옮깁니다.

Actions 콘솔은 작업의 구성을 시각적으로 표시합니다. 매핑된 작업을 시각적으로 표시하면 개발 중에 유용하며 테스트에 사용되는 작업의 버전에는 영향을 주지 않습니다.

참고: gactions push를 사용하면 공동작업 중인 경우 작업 프로젝트의 현재 초안이 재정의됩니다.

작업 프로젝트를 푸시하고 Actions 콘솔에서 확인하려면 다음 단계를 따르세요.

1. 터미널에서 다음 명령어를 실행하여 프로젝트를 Actions 콘솔로 푸시합니다.

gactions push

다음과 같은 출력이 표시됩니다.

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. 제공된 URL을 복사하여 브라우저에 붙여넣습니다.
3. Actions 콘솔의 상단 탐색 메뉴에서 Develop을 클릭합니다.
4. Scenes 옆에 있는 드롭다운 화살표를 클릭하고 Start를 클릭합니다. 다음 스크린샷과 같이 작업의 Start 테마를 시각적으로 표현할 수 있습니다.

축하합니다.

Actions SDK를 사용하여 Google 어시스턴트 작업을 빌드하는 방법에 관한 기본 지식을 배우셨습니다.

학습한 내용

• Actions 콘솔에서 작업 프로젝트를 설정하는 방법
• Actions SDK를 사용하여 로컬 파일 시스템에서 작업 프로젝트를 빌드하는 방법
• 사용자가 작업으로 대화를 시작할 수 있도록 기본 호출에 프롬프트를 추가하는 방법
• 테마, 인텐트, 전환, 추천 검색어 칩, 처리가 포함된 대화 인터페이스를 만드는 방법
• Actions Simulator로 작업을 테스트하는 방법

추가 학습 자료

Google 어시스턴트용 작업을 빌드하는 방법을 자세히 알아보려면 다음 자료를 살펴보세요.

• Google 어시스턴트용 작업 개발에 관한 공식 문서 사이트
• 샘플 코드 및 라이브러리용 Actions on Google GitHub 페이지
• Google 어시스턴트를 다루는 개발자를 위한 공식 Reddit 커뮤니티

Twitter에서 @ActionsOnGoogle을 팔로우하여 최신 소식을 확인하고 #AoGDevs를 포함한 트윗으로 빌드한 결과물을 공유하세요.

프로젝트 정리하기[권장]

주의: 레벨 2 Codelab인 'Actions SDK를 사용하여 Google 어시스턴트 작업 빌드하기(레벨 2)'에서는 이 Codelab에서 만든 프로젝트를 활용하여 빌드합니다. 레벨 2 Codelab 작업을 진행할 계획하는 경우 프로젝트를 삭제하지 마세요. 대신 레벨 2 Codelab 끝에 있는 'Clean-up your project' 섹션에서 삭제하면 됩니다.

요금이 청구되지 않도록 하려면 사용하지 않을 프로젝트를 삭제하는 것이 좋습니다. 이 Codelab에서 만든 프로젝트를 삭제하려면 다음 단계를 따르세요.

1. Cloud 프로젝트 및 리소스를 삭제하려면 Shutting down (deleting) projects 섹션에 나열된 단계를 완료하세요.

주의: Google Cloud Platform 설정 페이지에서 삭제할 프로젝트를 제대로 선택해야 합니다.

2. 선택사항: Actions 콘솔에서 프로젝트를 즉시 삭제하려면 Deleting a project 섹션에 나열된 단계를 완료하세요. 이 단계를 완료하지 않으면 프로젝트가 약 30일 후에 자동으로 삭제됩니다.

피드백 설문조사

끝내기 전에 경험에 관한 짧은 설문조사에 참여해 주세요.