Google Workspace 부가기능 엔드포인트 인터페이스


서비스 개요

사용자가 지원되는 호스트 애플리케이션(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 객체입니다.

  1. RenderActions: 새 카드를 렌더링하거나 카드 스택을 탐색하거나 UI 작업을 실행합니다(예: {"action": {"navigations": [...]}} 또는 {"renderActions": ...}).
  2. SubmitFormResponse: 카드 렌더링 안내 및 선택적 상태 업데이트 표시기(예: {"renderActions": {...}, "stateChanged": true})를 사용하여 사용자 양식 제출 작업에 응답합니다.
  3. GetAutocompletionResponse: 위젯 자동 완성 필드(예: {"autoComplete": {"items": [...]}})에 동적 텍스트 추천을 제공합니다.
  4. DataActions: 콜백에 의해 트리거된 문서 변형 또는 Chat 스페이스 작업을 수행합니다(예: {"hostAppDataAction": {...}}).
  5. 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