Interfejs punktu końcowego dodatków do Google Workspace


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. Zobacz CommonEventObject.
  • authorizationEventObject: tokeny dostępu OAuth użytkownika, tokeny identyfikacji użytkownika i zakresy autoryzowane przez system. Zobacz AuthorizationEventObject.

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). Zobacz GmailEventObject.
  • 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). Zobacz DriveEventObject.
  • Google Chat: typ zdarzenia (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), metadane pokoju, dane użytkownika i dane ładunku. Zobacz ChatEventObject.
  • 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:

  1. RenderActions: renderuje nowe karty, porusza się po stosach kart lub wykonuje działania w interfejsie (np. {"action": {"navigations": [...]}} lub {"renderActions": ...}).
  2. 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}).
  3. GetAutocompletionResponse: udostępnia dynamiczne sugestie tekstowe dla pól autouzupełniania widżetów (np. {"autoComplete": {"items": [...]}}).
  4. DataActions: wykonuje zmiany w dokumencie lub działania w pokoju czatu wywołane przez wywołanie zwrotne (np. {"hostAppDataAction": {...}}).
  5. 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