Bu sayfada, Google Dokümanlar kullanıcılarının Google Dokümanlar'dan üçüncü taraf hizmetinde destek kaydı veya proje görevi gibi kaynaklar oluşturmasına olanak tanıyan bir Google Workspace eklentisinin nasıl oluşturulacağı açıklanmaktadır.
Google Workspace eklentisi kullanarak hizmetinizi Dokümanlar'daki @ menüsüne ekleyebilirsiniz. Eklenti, kullanıcıların Dokümanlar'daki bir form iletişim kutusu aracılığıyla hizmetinizde kaynak oluşturmasına olanak tanıyan menü öğeleri ekler.
Kullanıcılar kaynakları nasıl oluşturur?
Kullanıcılar, Google Dokümanlar dokümanından hizmetinizde kaynak oluşturmak için dokümana @ yazıp @ menüsünden hizmetinizi seçebilir:
Kullanıcılar bir dokümana @ yazıp hizmetinizi seçtiğinde, kaynak oluşturmak için ihtiyaç duydukları form girişlerini içeren bir kart gösterirsiniz. Kullanıcı kaynak oluşturma formunu gönderdikten sonra eklentiniz, kaynağı hizmetinizde oluşturur ve kaynağı işaret eden bir URL oluşturur.
Eklenti, oluşturulan kaynak için dokümana bir çip ekler. Kullanıcılar işaretçiyi bu çipin üzerinde tuttuğunda eklentinin ilişkili bağlantı önizleme tetikleyicisi çağrılır. Eklentinizin, bağlantı önizleme tetikleyicileriniz tarafından desteklenen bağlantı kalıplarına sahip çipler eklediğinden emin olun.
Kaynak oluşturmayı yapılandırmak için eklentinizin manifest dosyasında aşağıdaki bölümleri ve alanları belirtin:
docs alanındaki addOns bölümünün altında, runFunction içeren createActionTriggers tetikleyicisini uygulayın. (Bu işlevi Form kartlarını oluşturma bölümünde tanımlarsınız.)
Kullanıcıların kaynak oluşturmak için eklentiyi yetkilendirebilmesi amacıyla oauthScopes alanına https://www.googleapis.com/auth/workspace.linkcreate kapsamını ekleyin.
Daha açık belirtmek gerekirse bu kapsam, eklentinin kullanıcıların kaynak oluşturma formuna gönderdiği bilgileri okumasına ve bu bilgilere dayalı olarak dokümana akıllı çip eklemesine olanak tanır.
Örneğin, aşağıdaki destek kaydı hizmeti için kaynak oluşturmayı yapılandıran bir manifest'in addons bölümüne bakın:
{"oauthScopes":["https://www.googleapis.com/auth/workspace.linkpreview","https://www.googleapis.com/auth/workspace.linkcreate"],"addOns":{"docs":{"linkPreviewTriggers":[...],"createActionTriggers":[{"id":"createCase","labelText":"Create support case","localizedLabelText":{"es":"Crear caso de soporte"},"runFunction":"createCaseInputCard","logoUrl":"https://www.example.com/images/case.png"}]}}}
Örnekte, Google Workspace eklentisi kullanıcıların destek kaydı oluşturmasına olanak tanır.
Her createActionTriggers tetikleyicisinde aşağıdaki alanlar bulunmalıdır:
Benzersiz bir kimlik
Dokümanlar @ menüsünde görünen bir metin etiketi
@ menüsündeki etiket metninin yanında görünen bir simgeyi işaret eden logo URL'si
Bir Apps Komut Dosyası işlevine veya kart döndüren bir HTTP uç noktasına referans veren geri çağırma işlevi
Form kartlarını oluşturma
Dokümanlar @ menüsünden hizmetinizde kaynak oluşturmak için createActionTriggers nesnesinde belirttiğiniz tüm işlevleri uygulamanız gerekir.
Kullanıcı menü öğelerinizden biriyle etkileşime geçtiğinde ilgili createActionTriggers tetikleyici etkinleştirilir ve geri çağırma işlevi, kaynağı oluşturmak için form girişleri içeren bir kart gösterir.
Desteklenen öğeler ve işlemler
Kart arayüzünü oluşturmak için kullanıcıların kaynağı oluşturmak üzere ihtiyaç duyduğu bilgileri ve girişleri görüntülemek üzere widget'ları kullanırsınız. Google Workspace eklenti widget'larının ve işlemlerinin çoğu aşağıdaki istisnalar dışında desteklenir:
Kart altbilgileri desteklenmez.
Bildirimler desteklenmez.
Gezinme için yalnızca updateCard gezinme desteklenir.
Form girişleri içeren kart örneği
Aşağıdaki örnekte, kullanıcı @ menüsünden Destek kaydı oluştur'u seçtiğinde bir kart gösteren bir Apps Script geri çağırma işlevi gösterilmektedir:
createCaseInputCard işlevi aşağıdaki kartı oluşturur:
Kartta metin girişleri, açılır menü ve onay kutusu bulunur. Ayrıca, oluşturma formunun gönderimini işlemek için başka bir işlevi çalıştıran onClick işlemi içeren bir metin düğmesi de vardır.
Kullanıcı formu doldurup Oluştur'u tıkladıktan sonra eklenti, form girişlerinionClick işlem işlevine (örneğimizde submitCaseCreationForm olarak adlandırılır) gönderir. Bu noktada eklenti, girişleri doğrulayabilir ve üçüncü taraf hizmetinde kaynağı oluşturmak için kullanabilir.
Form gönderimlerini işleme
Kullanıcı oluşturma formunu gönderdikten sonra onClick işlemiyle ilişkili işlev çalıştırılır. İdeal bir kullanıcı deneyimi için eklentiniz hem başarılı hem de hatalı form gönderimlerini işlemelidir.
Başarılı kaynak oluşturma işlemini işleme
Eklentinizin onClick işlevi, üçüncü taraf hizmetinizde kaynağı oluşturur ve onu işaret eden bir URL oluşturur.
Çip oluşturmak için kaynağın URL'sini Docs'a geri iletmek amacıyla onClick işlevi, renderActions.action.links içinde bir bağlantıyı işaret eden tek bir öğe içeren bir SubmitFormResponse döndürmelidir. Bağlantı başlığı, oluşturulan kaynağın başlığını, URL ise bu kaynağı göstermelidir.
Aşağıdaki örnekte, oluşturulmuş bir kaynak için SubmitFormResponse gösterilmektedir:
SubmitFormResponse döndürüldükten sonra modal iletişim kutusu kapanır ve eklenti dokümana bir çip ekler.
Kullanıcılar işaretçiyi bu çipin üzerine getirdiğinde ilişkili bağlantı önizleme tetikleyicisi çağrılır. Eklentinizin, bağlantı önizleme tetikleyicileriniz tarafından desteklenmeyen bağlantı kalıplarına sahip çipler eklemediğinden emin olun.
Hataları işleme
Kullanıcı geçersiz alanlar içeren bir formu göndermeye çalışırsa eklenti, bağlantı içeren bir SubmitFormResponse döndürmek yerine updateCard gezinme öğesi kullanarak hata görüntüleyen bir oluşturma işlemi döndürmelidir.
Bu sayede kullanıcı, hatasını görüp tekrar deneyebilir. Apps Komut Dosyası için updateCard(card), diğer çalışma ortamları için updateCard bölümüne bakın. Bildirimler ve pushCard gezinmeleri desteklenmez.
Hata işleme örneği
Aşağıdaki örnekte, kullanıcı formu gönderdiğinde çağrılan kod gösterilmektedir. Girişler geçersizse kart güncellenir ve hata mesajları gösterilir. Girişler geçerliyse eklenti, oluşturulan kaynağın bağlantısını içeren bir SubmitFormResponse döndürür.
Aşağıdaki örnekte, bir şirketin destek kaydı bağlantılarını önizleyen ve kullanıcıların Google Dokümanlar'dan destek kaydı oluşturmasına olanak tanıyan bir Google Workspace eklentisi gösterilmektedir.
Örnekte aşağıdakiler yapılır:
Dokümanlar @ menüsünden destek kaydı oluşturmak için form alanları içeren bir kart oluşturur.
Form girişlerini doğrular ve geçersiz girişler için hata mesajları döndürür.
Oluşturulan destek kaydının adını ve bağlantısını Dokümanlar belgesine akıllı çip olarak ekler.
Destek kaydının bağlantısını (ör. https://www.example.com/support/cases/1234) önizler. Akıllı çipte bir simge, önizleme kartında ise destek kaydı adı, öncelik ve açıklama gösterilir.
[null,null,["Son güncelleme tarihi: 2025-02-14 UTC."],[[["This guide details building a Google Workspace add-on to create and manage external resources (like support cases) directly within Google Docs."],["Users can create resources via a form within Docs, which then inserts a smart chip linking to the resource in the external service."],["The add-on requires configuration in the manifest file and utilizes Apps Script, Node.js, Python, or Java for development."],["Comprehensive code samples are provided to guide developers through card creation, form submission, and error handling."],["Smart chips representing the created resources offer link previews, enhancing user experience and information access."]]],[]]