서비스 개요
사용자가 지원되는 호스트 애플리케이션(Gmail, Google Calendar, Google Drive, Google Chat, Google Docs, Google Sheets, Google Slides 또는 Workspace Studio)에서 상호작용을 트리거하면 호스트는 구성된 부가기능 콜백 URL(/*)에 HTTP POST 이벤트 페이로드를 전송합니다.
부가기능 엔드포인트는 EventObject 요청 페이로드를 수신하고 응답: HandleEventResponse에 문서화된 5가지 유효한 JSON 응답 유형 중 하나를 반환해야 합니다.
웹훅 엔드포인트 계약
| 메서드 | 엔드포인트 경로 | 요청 본문 | 응답 본문 |
|---|---|---|---|
POST |
/*(또는 구성된 콜백 경로) |
EventObject |
5가지 응답 유형 중 하나 |
요청: EventObject
EventObject에는 최상위 메타데이터, 일반 이벤트 필드, 호스트 애플리케이션 컨텍스트 세부정보가 포함됩니다.
일반 및 승인 컨텍스트
commonEventObject: 사용자 언어, 호스트 애플리케이션 enum(GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), 사용자 플랫폼, 시간대, 위젯 양식 입력 값(formInputs), 맞춤 매개변수입니다.CommonEventObject을 참고하세요.authorizationEventObject: 사용자 OAuth 액세스 토큰, 사용자 ID 토큰, 시스템 승인 범위입니다.AuthorizationEventObject를 참조하세요.
호스트 애플리케이션 이벤트 객체
콜백을 호출하는 애플리케이션에 따라 다음 호스트 객체 중 하나가 있습니다.
- Gmail: 메일 ID, 대화목록 ID, 임시 액세스 토큰, 메일 수신자 목록(
toRecipients,ccRecipients,bccRecipients).GmailEventObject를 참조하세요. - Calendar: 일정 ID, 반복 일정 ID, 캘린더 ID, 주최자 정보, 참석자, 회의 데이터, 진입점
CalendarEventObject을 참고하세요. - Drive: 선택한 파일 또는 폴더(
selectedItems) 및 현재 커서 항목 메타데이터(activeCursorItem).DriveEventObject를 참고하세요. - 채팅: 이벤트 유형(
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), 스페이스 메타데이터, 사용자 세부정보, 페이로드 데이터ChatEventObject을 참고하세요. - Workspace Studio: 작업 호출, 트리거 수명 주기 이벤트, 요소 구성, 리소스 검색, 변수 데이터 매핑
WorkflowEventObject을 참고하세요. - Docs: 문서 ID, 제목, 파일 범위 권한 플래그, 일치하는 URL 패턴
DocsEventObject을 참고하세요. - Sheets: 스프레드시트 ID, 제목, 파일 범위 권한 플래그, 일치하는 URL 패턴
SheetsEventObject을 참고하세요. - Slides: 프레젠테이션 ID, 제목, 파일 범위 권한 플래그, 일치하는 URL 패턴
SlidesEventObject을 참고하세요.
응답: HandleEventResponse
웹훅 엔드포인트에서 반환하는 HTTP 응답은 다음 5가지 응답 유형 중 하나의 인스턴스여야 하는 태그가 지정되지 않은 루트 JSON 객체입니다.
RenderActions: 새 카드를 렌더링하거나 카드 스택을 탐색하거나 UI 작업을 실행합니다(예:{"action": {"navigations": [...]}}또는{"renderActions": ...}).SubmitFormResponse: 카드 렌더링 안내 및 선택적 상태 업데이트 표시기(예:{"renderActions": {...}, "stateChanged": true})를 사용하여 사용자 양식 제출 작업에 응답합니다.GetAutocompletionResponse: 위젯 자동 완성 필드(예:{"autoComplete": {"items": [...]}})에 동적 텍스트 추천을 제공합니다.DataActions: 콜백에 의해 트리거된 문서 변형 또는 Chat 스페이스 작업을 수행합니다(예:{"hostAppDataAction": {...}}).AuthorizationError: 사용자에게 외부 서드 파티 사용자 인증 정보를 승인하라는 메시지를 표시하거나 추가 Google OAuth 범위(예:{"basicAuthorizationPrompt": {"authorizationUrl": "..."}})를 요청합니다.
독립형 OpenAPI 3.0 사양 및 JSON 스키마
콜백 엔드포인트의 서버 스텁, SDK 클라이언트 라이브러리 또는 페이로드 유효성 검사 스키마를 자동으로 생성하려면 다음 사양 파일을 참고하세요.
- OpenAPI 3.0.3 사양:
addon_callback_openapi.json - JSON 스키마 정의:
endpoint_interface.schema.json- 요청 스키마 프래그먼트:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - 응답 스키마 프래그먼트:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- 요청 스키마 프래그먼트: