Google Workspace eklentileri uç nokta arayüzü


Hizmete genel bakış

Kullanıcı, desteklenen bir ana makine uygulamasında (Gmail, Google Takvim, Google Drive, Google Chat, Google Dokümanlar, Google E-Tablolar, Google Slaytlar veya Workspace Studio) bir etkileşimi tetiklediğinde ana makine, yapılandırılmış eklenti geri çağırma URL'nize (/*) bir HTTP POST etkinlik yükü gönderir.

Eklenti uç noktanız bir EventObject istek yükü almalı ve Yanıt: HandleEventResponse bölümünde belgelenen beş geçerli JSON yanıt türünden birini döndürmelidir.


Webhook uç nokta sözleşmesi

Yöntem Uç nokta yolu İstek metni Yanıt metni
POST /* (veya yapılandırılmış geri çağırma yolu) EventObject 5 yanıt türünden biri

İstek: EventObject

EventObject; üst düzey meta verileri, ortak etkinlik alanlarını ve barındırılan uygulamayla ilgili bağlamsal ayrıntıları içerir:

Ortak ve yetkilendirme bağlamı

  • commonEventObject: Kullanıcı yerel ayarı, barındırılan uygulama enum (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), kullanıcı platformu, saat dilimi, widget form giriş değerleri (formInputs) ve özel parametreler. CommonEventObject sayfasına bakın.
  • authorizationEventObject: Kullanıcı OAuth erişim jetonları, kullanıcı kimliği jetonları ve sistem tarafından yetkilendirilmiş kapsamlar. AuthorizationEventObject sayfasına bakın.

Barındırılan uygulama olay nesneleri

Geri çağırmayı hangi uygulamanın çağırdığına bağlı olarak aşağıdaki ana makine nesnelerinden biri bulunur:

  • Gmail: İleti kimliği, ileti dizisi kimliği, geçici erişim jetonu ve ileti alıcı listeleri (toRecipients, ccRecipients, bccRecipients). GmailEventObject başlıklı makaleyi inceleyin.
  • Takvim: Etkinlik kimliği, düzenli etkinlik kimliği, takvim kimliği, düzenleyen bilgileri, katılımcılar, konferans verileri ve giriş noktaları. CalendarEventObject sayfasına bakın.
  • Drive: Seçili dosyalar veya klasörler (selectedItems) ve geçerli imleç öğesi meta verileri (activeCursorItem). DriveEventObject sayfasını inceleyin.
  • Chat: Etkinlik türü (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), alan meta verileri, kullanıcı ayrıntıları ve yük verileri. ChatEventObject sayfasına bakın.
  • Workspace Studio: İşlem çağrıları, tetikleyici yaşam döngüsü etkinlikleri, öğe yapılandırmaları, kaynak alma işlemleri ve değişken veri haritaları. WorkflowEventObject sayfasına bakın.
  • Dokümanlar: Doküman kimliği, başlık, dosya kapsamı izin işareti ve eşleşen URL kalıbı. DocsEventObject sayfasına bakın.
  • E-Tablolar: E-tablo kimliği, başlık, dosya kapsamı izin işareti ve eşleşen URL kalıbı. SheetsEventObject sayfasına bakın.
  • Slaytlar: Sunu kimliği, başlık, dosya kapsamı izin işareti ve eşleşen URL kalıbı. SlidesEventObject sayfasına bakın.

Yanıt: HandleEventResponse

Webhook uç noktanız tarafından döndürülen HTTP yanıtı, aşağıdaki beş yanıt türünden birinin örneği olması gereken etiketlenmemiş bir kök JSON nesnesidir:

  1. RenderActions: Yeni kartlar oluşturur, kart yığınlarında gezinir veya kullanıcı arayüzü işlemlerini (ör. {"action": {"navigations": [...]}} veya {"renderActions": ...}) yürütür.
  2. SubmitFormResponse: Kart oluşturma talimatları ve isteğe bağlı bir durum güncelleme göstergesi (ör. {"renderActions": {...}, "stateChanged": true}) ile kullanıcı form gönderme işlemine yanıt verir.
  3. GetAutocompletionResponse: Widget otomatik tamamlama alanları (ör. {"autoComplete": {"items": [...]}}) için dinamik metin önerileri sağlar.
  4. DataActions: Geri çağırma tarafından tetiklenen doküman mutasyonlarını veya Chat alanı işlemlerini (ör. {"hostAppDataAction": {...}}) gerçekleştirir.
  5. AuthorizationError: Kullanıcıdan harici üçüncü taraf kimlik bilgilerini yetkilendirmesini ister veya ek Google OAuth kapsamları (ör. {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}) talep eder.

Bağımsız OpenAPI 3.0 spesifikasyonu ve JSON şemaları

Geri çağırma uç noktanız için sunucu taslaklarını, SDK istemci kitaplıklarını veya yük doğrulama şemalarını otomatik olarak oluşturmak istiyorsanız aşağıdaki spesifikasyon dosyalarına bakın:

  • OpenAPI 3.0.3 spesifikasyonu: addon_callback_openapi.json
  • JSON şeması tanımları: endpoint_interface.schema.json
    • İstek şeması parçası: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Yanıt şeması parçası: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse