부가 작업

부가기능 작업은 위젯에 상호작용 동작을 제공합니다. 작업을 만들면 사용자가 위젯을 선택하거나 업데이트할 때 발생하는 상황을 정의할 수 있습니다.

대부분의 경우 Apps Script 카드 서비스에서 제공하는 Action 객체를 사용하여 부가기능 작업을 정의할 수 있습니다. 각 Action는 생성 시 콜백 함수와 연결됩니다. 사용자가 위젯과 상호작용할 때 선택한 단계를 실행하도록 콜백 함수를 구현합니다. 또한 Action을 위젯에 연결해야 합니다. 이때 Action 콜백을 트리거하는 상호작용의 종류를 정의하는 적절한 위젯 핸들러 함수를 사용합니다.

다음 일반 프로세스를 사용하여 Action로 위젯을 구성합니다.

1. 실행해야 하는 콜백 함수와 필요한 매개변수를 지정하여 Action 객체를 만듭니다.
2. Action 객체를 사용하여 위젯에서 적절한 위젯 핸들러 함수를 호출합니다.
3. 필요한 동작을 실행하도록 콜백 함수를 구현합니다.

참고: Action 객체를 CardAction 객체와 혼동하지 마세요. CardAction 객체는 카드 헤더 메뉴 항목이고 Action 객체는 UI와의 사용자 상호작용에 대한 응답을 정의합니다.

위젯 핸들러 함수

위젯을 특정 Action 또는 기타 동작에 연결하려면 위젯 핸들러 함수를 사용합니다. 핸들러 함수는 어떤 종류의 상호작용(예: 위젯 클릭 또는 텍스트 필드 수정)이 작업 동작을 트리거하는지 결정합니다. 핸들러 함수는 작업이 완료된 후 UI가 취하는 단계를 정의합니다(있는 경우).

다음 표에는 위젯의 다양한 핸들러 유형과 함께 사용되는 위젯이 나와 있습니다.

핸들러 함수	작업을 트리거합니다.	적용 가능한 위젯	설명
setOnChangeAction()	위젯 값이 변경됨	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	위젯이 포커스를 잃을 때(예: 사용자가 입력에 텍스트를 입력하고 Enter 키를 누를 때) Apps Script 함수를 실행하는 Action를 설정합니다. 핸들러는 호출하는 함수에 이벤트 객체를 자동으로 전달합니다. 선택한 경우 이 이벤트 객체에 추가 매개변수 정보를 삽입할 수 있습니다.
setOnClickAction()	사용자가 위젯을 클릭합니다.	CardAction Image ImageButton DecoratedText TextButton	사용자가 위젯을 클릭할 때 Apps Script 함수를 실행하는 Action을 설정합니다. 핸들러는 호출하는 함수에 이벤트 객체를 자동으로 전달합니다. 이 이벤트 객체에 선택적 매개변수 정보를 삽입할 수 있습니다.
setComposeAction()	사용자가 위젯을 클릭합니다.	CardAction Image ImageButton DecoratedText TextButton	Gmail에만 해당합니다. 이메일 초안을 빌드한 후 Gmail UI 작성 창에서 사용자에게 해당 초안을 표시하는 Action를 설정합니다. Gmail에서 새 메일로 또는 열려 있는 메일에 대한 답장으로 초안을 작성할 수 있습니다. 핸들러가 초안 빌드 콜백 함수를 호출하면 이벤트 객체를 콜백 함수에 전달합니다. 자세한 내용은 Compose draft messages(Compose 초안 메시지)를 참고하세요.
setOnClickOpenLinkAction()	사용자가 위젯을 클릭합니다.	CardAction Image ImageButton DecoratedText TextButton	사용자가 위젯을 클릭할 때 URL을 열도록 Action을 설정합니다. URL을 구성해야 하거나 링크가 열리기 전에 다른 작업이 실행되어야 하는 경우 이 핸들러를 사용합니다. 그렇지 않으면 일반적으로 setOpenLink()를 사용하는 것이 더 간단합니다. 새 창에서만 URL을 열 수 있습니다. 닫으면 UI가 부가기능을 다시 로드하도록 할 수 있습니다.
setOpenLink()	사용자가 위젯을 클릭합니다.	CardAction Image ImageButton DecoratedText TextButton	사용자가 위젯을 클릭하면 URL을 바로 엽니다. URL을 알고 열기만 하면 되는 경우 이 핸들러를 사용하고, 그렇지 않으면 setOnClickOpenLinkAction()를 사용하세요. 새 창 또는 오버레이에서 URL을 열 수 있습니다. 닫으면 UI에서 부가기능을 다시 로드하도록 할 수 있습니다.
setSuggestionsAction()	사용자가 입력에 텍스트를 입력합니다.	TextInput	사용자가 텍스트 입력 위젯에 텍스트를 입력할 때 Apps Script 함수를 실행하는 Action를 설정합니다. 핸들러는 호출하는 함수에 이벤트 객체를 자동으로 전달합니다. 자세한 내용은 텍스트 입력의 자동 완성 제안을 참고하세요.

콜백 함수

콜백 함수는 Action가 트리거될 때 실행됩니다. 콜백 함수는 Apps Script 함수이므로 다른 스크립트 함수가 할 수 있는 거의 모든 작업을 실행할 수 있습니다.

경고: Apps Script 카드 서비스는 콜백 함수의 실행 시간을 최대 30초로 제한합니다. 실행 시간이 이보다 길어지면 Action에 응답하여 애드온 UI의 카드 표시가 제대로 업데이트되지 않을 수 있습니다.

콜백 함수는 특정 응답 객체를 반환하기도 합니다. 이러한 유형의 응답은 콜백 실행이 완료된 후 발생해야 하는 추가 작업을 나타냅니다(예: 새 카드 표시 또는 자동 완성 제안 표시). 콜백 함수가 특정 응답 객체를 반환해야 하는 경우 카드 서비스의 빌더 클래스를 사용하여 해당 객체를 생성합니다.

다음 표는 특정 작업에 대해 콜백 함수가 특정 응답 객체를 반환해야 하는 시점을 보여줍니다. 이러한 작업은 모두 부가기능이 확장하는 특정 호스트 애플리케이션과 독립적입니다.

시도된 작업	콜백 함수는 다음을 반환해야 합니다.
카드 간 이동	ActionResponse
Notification 표시	ActionResponse
setOnClickOpenLinkAction()을 사용하여 링크 열기	ActionResponse
자동 완성 추천 표시	SuggestionResponse
범용 작업 사용	UniversalActionResponse
기타 작업	Nothing

Google Workspace 호스트 애플리케이션 작업

이러한 작업 외에도 각 호스트 애플리케이션에는 해당 호스트에서만 실행할 수 있는 자체 작업 집합이 있습니다. 자세한 내용은 다음 가이드를 참고하세요.

• 캘린더 작업
• 채팅 작업
• 액션 유도
• Gmail 작업
• 편집기 작업

참고: 응답 빌더 클래스를 사용할 때는 build()를 호출하여 응답 객체를 생성해야 합니다. 그렇지 않으면 오류가 발생합니다.

참고: 범용 작업은 프로젝트 매니페스트에 정의되며 Action 객체가 필요하지 않지만 콜백 함수는 UniversalActionResponse를 반환해야 합니다.

작업 이벤트 객체

애드온이 Action를 트리거하면 UI가 자동으로 JSON 이벤트 객체를 구성하고 이를 Action 콜백 함수의 인수로 전달합니다. 이 이벤트 객체에는 표시된 카드의 모든 대화형 위젯의 현재 값과 같은 사용자의 현재 클라이언트 측 컨텍스트에 관한 정보가 포함되어 있습니다.

작업 이벤트 객체에는 포함된 정보를 정리하는 특정 JSON 구조가 있습니다. 홈페이지 트리거가 실행되어 홈페이지를 만들 때나 컨텍스트 트리거가 실행되어 부가기능 표시를 업데이트할 때도 동일한 구조가 사용됩니다.

이벤트 객체 구조에 대한 전체 설명은 이벤트 객체를 참고하세요.

참고: Gmail 부가기능은 이 이벤트 객체 구조의 간소화된 버전을 사용했으며, 이는 현재 지원 중단되었습니다. 이전 버전과의 호환성을 위해 모든 원래 Gmail 부가기능 이벤트 객체 필드는 새 이벤트 객체 구조 내에 계속 포함됩니다 (이벤트 객체 구조 참고). 하지만 동일한 정보가 일반 이벤트 및 Gmail 이벤트 객체 하위 구조에 재현됩니다. Gmail 부가기능을 Google Workspace 부가기능으로 업그레이드하는 경우 업데이트된 이벤트 객체 필드를 사용하도록 코드를 조정해야 합니다. 결국 원래 Gmail 이벤트 객체 필드가 삭제되기 때문입니다.