Przegląd usługi
Gdy użytkownik wywoła interakcję w obsługiwanej aplikacji hostowanej (Gmail, Kalendarz Google, Dysk Google, Google Chat, Dokumenty Google, Arkusze Google, Prezentacje Google lub Workspace Studio), host wysyła ładunek zdarzenia HTTP POST do skonfigurowanego adresu URL wywołania zwrotnego dodatku (/*).
Punkt końcowy dodatku musi otrzymać ładunek żądania EventObject i zwrócić jeden z 5 prawidłowych typów odpowiedzi JSON udokumentowanych w sekcji Odpowiedź: HandleEventResponse.
Umowa dotycząca punktu końcowego webhooka
| Metoda | Ścieżka punktu końcowego | Treść żądania | Treść odpowiedzi |
|---|---|---|---|
POST |
/* (lub skonfigurowana ścieżka wywołania zwrotnego) |
EventObject |
Jeden z 5 typów odpowiedzi |
Prośba: EventObject
EventObject zawiera metadane najwyższego poziomu, wspólne pola zdarzeń i szczegóły kontekstowe aplikacji hosta:
Kontekst wspólny i autoryzacji
commonEventObject: region użytkownika, typ wyliczeniowy aplikacji hostowanej (GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), platforma użytkownika, strefa czasowa, wartości wejściowe formularza widżetu (formInputs) i parametry niestandardowe. ZobaczCommonEventObject.authorizationEventObject: tokeny dostępu OAuth użytkownika, tokeny identyfikacji użytkownika i zakresy autoryzowane przez system. ZobaczAuthorizationEventObject.
Obiekty zdarzeń aplikacji hostowanej
W zależności od tego, która aplikacja wywołuje funkcję zwrotną, obecny jest jeden z tych obiektów hosta:
- Gmail identyfikator wiadomości, identyfikator wątku, tymczasowy token dostępu i listy odbiorców wiadomości (
toRecipients,ccRecipients,bccRecipients). ZobaczGmailEventObject. - Kalendarz: identyfikator wydarzenia, identyfikator wydarzenia cyklicznego, identyfikator kalendarza, informacje o organizatorze, uczestnicy, dane rozmowy wideo i punkty wejścia. Zobacz
CalendarEventObject. - Dysk: wybrane pliki lub foldery (
selectedItems) i metadane elementu, na którym znajduje się kursor (activeCursorItem). ZobaczDriveEventObject. - Google Chat: typ zdarzenia (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), metadane pokoju, dane użytkownika i dane ładunku. ZobaczChatEventObject. - Workspace Studio: wywołania działań, zdarzenia cyklu życia aktywatora, konfiguracje elementów, pobieranie zasobów i mapowanie danych zmiennych.
Zobacz
WorkflowEventObject. - Dokumenty: identyfikator dokumentu, tytuł, flaga uprawnień na poziomie pliku i dopasowany wzorzec adresu URL. Zobacz
DocsEventObject. - Arkusze: identyfikator arkusza kalkulacyjnego, tytuł, flaga uprawnień na poziomie pliku i dopasowany wzorzec adresu URL. Zobacz
SheetsEventObject. - Prezentacje: identyfikator prezentacji, tytuł, flaga uprawnień na poziomie pliku i dopasowany wzorzec adresu URL. Zobacz
SlidesEventObject.
Odpowiedź: HandleEventResponse
Odpowiedź HTTP zwracana przez punkt końcowy webhooka to nieoznaczony tagiem główny obiekt JSON, który musi być instancją jednego z tych 5 typów odpowiedzi:
RenderActions: renderuje nowe karty, porusza się po stosach kart lub wykonuje działania w interfejsie (np.{"action": {"navigations": [...]}}lub{"renderActions": ...}).SubmitFormResponse: odpowiada na działanie użytkownika polegające na przesłaniu formularza, podając instrukcje renderowania karty i opcjonalny wskaźnik aktualizacji stanu (np.{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: udostępnia dynamiczne sugestie tekstowe dla pól autouzupełniania widżetów (np.{"autoComplete": {"items": [...]}}).DataActions: wykonuje zmiany w dokumencie lub działania w pokoju czatu wywołane przez wywołanie zwrotne (np.{"hostAppDataAction": {...}}).AuthorizationError: prosi użytkownika o autoryzację zewnętrznych danych logowania innych firm lub żąda dodatkowych zakresów protokołu OAuth Google (np.{"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).
Samodzielna specyfikacja OpenAPI 3.0 i schematy JSON
Aby automatycznie wygenerować kody pośredniczące serwera, biblioteki klienta pakietu SDK lub schematy sprawdzania poprawności ładunku dla punktu końcowego wywołania zwrotnego, zapoznaj się z tymi plikami specyfikacji:
- Specyfikacja OpenAPI 3.0.3:
addon_callback_openapi.json - Definicje schematu JSON:
endpoint_interface.schema.json- Fragment schematu żądania:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - Fragment schematu odpowiedzi:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- Fragment schematu żądania: