Bu sayfada, Google Dokümanlar kullanıcılarının üçüncü taraf bir hizmetten gelen bağlantıları önizleyebilmesini sağlayan bir Google Workspace Eklentisinin nasıl oluşturulacağı açıklanmaktadır.
Bir Google Workspace eklentisi, hizmetinizin bağlantılarını algılayabilir ve Google Dokümanlar kullanıcılarından bunları önizlemelerini isteyebilir. Destek kayıtları, olası satışlar ve çalışan profillerine bağlantılar gibi birden fazla URL kalıbını önizlemek için bir eklenti yapılandırabilirsiniz.
Kullanıcılar bağlantıları nasıl önizler?
Bir Google Dokümanlar dokümanındaki bağlantıları önizlemek için kullanıcılar akıllı çipler ve kartlarla etkileşime geçer:
Google Dokümanlar, kullanıcılar bir URL yazdığında veya dokümana yapıştırdığında, bağlantıyı akıllı çiple değiştirmelerini ister. Akıllı çip, bağlantı içeriğinin bir simgesini ve kısa başlığını veya açıklamasını gösterir. Kullanıcı fareyle çipin üzerine geldiğinde, dosya veya bağlantı hakkında daha fazla bilgiyi önizleyen bir kart arayüzü görür.
Aşağıdaki videoda bir kullanıcının bir bağlantıyı akıllı çipe dönüştürme ve bir kartın önizlemesini görüntüleme yöntemi gösterilmektedir:
Ön koşullar
Apps Komut Dosyası
- Google Workspace hesabı.
- Bir Google Workspace eklentisi. Eklenti oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.
Node.js
- Google Workspace hesabı.
- Bir Google Workspace eklentisi. Eklenti oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.
Python
- Google Workspace hesabı.
- Bir Google Workspace eklentisi. Eklenti oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.
Java
- Google Workspace hesabı.
- Bir Google Workspace eklentisi. Eklenti oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.
İsteğe bağlı: Üçüncü taraf bir hizmet için kimlik doğrulamayı ayarlayın
Eklentiniz, yetkilendirme gerektiren bir hizmete bağlanırsa kullanıcıların, bağlantıları önizlemek için hizmette kimlik doğrulaması yapmaları gerekir. Diğer bir deyişle, kullanıcılar hizmetinizden bir bağlantıyı ilk kez bir Google Dokümanlar dokümanına yapıştırdığında eklentiniz yetkilendirme akışını çağırmalıdır.
Bir OAuth hizmeti veya özel yetkilendirme istemi oluşturmak için aşağıdaki kılavuzlardan birine bakın:
Eklentinizi Apps Komut Dosyası kullanarak oluşturduysanız Google Workspace eklentisinden Google dışı hizmetlere bağlanma bölümüne bakın.
Eklentinizi farklı bir çalışma zamanı kullanarak oluşturduysanız Eklentinizi bir üçüncü taraf hizmetine bağlama bölümüne bakın.
Eklentiniz için bağlantı önizlemelerini ayarlama
Bu bölümde, eklentiniz için aşağıdaki adımları içeren bağlantı önizlemelerinin nasıl ayarlanacağı açıklanmaktadır:
- Eklentinizin dağıtım kaynağında veya manifest dosyasında bağlantı önizlemelerini yapılandırın.
- Bağlantılarınız için akıllı çip ve kart arayüzünü oluşturun.
Bağlantı önizlemelerini yapılandırma
Bağlantı önizlemelerini yapılandırmak için eklentinizin dağıtım kaynağında veya manifest dosyasında aşağıdaki bölümleri ve alanları belirtin:
- Google Dokümanlar'ı genişletmek için
addOns
bölümünedocs
alanını ekleyin. docs
alanına,runFunction
içerenlinkPreviewTriggers
tetikleyicisini uygulayın (Bu işlevi, Akıllı çipi ve kartı oluşturma başlıklı bölümde tanımlarsınız).linkPreviewTriggers
tetikleyicisinde hangi alanları belirtebileceğiniz hakkında bilgi edinmek için Apps Komut Dosyası manifest dosyaları veya diğer çalışma zamanları için dağıtım kaynakları ile ilgili referans belgelere bakın.Kullanıcıların kendi adlarına bağlantıları önizlemesi için eklentiyi yetkilendirebilmek için
oauthScopes
alanınahttps://www.googleapis.com/auth/workspace.linkpreview
kapsamını ekleyin.
Örneğin, bir destek kaydı hizmetinin bağlantı önizlemelerini yapılandıran bir dağıtım kaynağının oauthScopes
ve addons
bölümüne göz atın:
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
Bu örnekte, Google Workspace eklentisi bir şirketin destek kaydı hizmetinin bağlantılarını önizler. Eklenti, bağlantıları önizlemek için üç URL kalıbı belirtir. Bir bağlantı bir Google Dokümanlar dokümanındaki URL kalıplarından biriyle her eşleştiğinde caseLinkPreview
geri çağırma işlevi, akıllı bir çip ve kart oluşturup görüntüler.
Akıllı çipi ve kartı oluşturma
Bir bağlantı için akıllı çip ve kart döndürmek amacıyla linkPreviewTriggers
nesnesinde belirttiğiniz tüm işlevleri uygulamanız gerekir.
Bir kullanıcı, belirtilen URL kalıbıyla eşleşen bir bağlantıyla etkileşim kurduğunda linkPreviewTriggers
tetikleyicisi tetiklenir ve geri çağırma işlevi docs.matchedUrl.url
etkinlik nesnesini bağımsız değişken olarak geçirir. Bağlantınızın önizlemesi için akıllı çip ve kart oluşturmak üzere bu etkinlik nesnesinin yükünü kullanırsınız.
Örneğin, example.com/cases
URL kalıbını belirten bir eklenti için kullanıcı https://www.example.com/cases/123456
bağlantısını önizlerse aşağıdaki etkinlik yükü döndürülür:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Kart arayüzünü oluşturmak için widget'ları kullanarak bağlantıyla ilgili bilgileri görüntüleyebilirsiniz. Ayrıca, kullanıcıların bağlantıyı açmasına veya içeriğini değiştirmesine izin veren işlemler de oluşturabilirsiniz. Kullanılabilir widget ve işlemlerin listesi için Önizleme kartları için desteklenen bileşenler başlıklı makaleyi inceleyin.
Bağlantı önizlemesi için akıllı çip ve kart oluşturmak üzere:
- Eklentinizin dağıtım kaynağının veya manifest dosyasının
linkPreviewTriggers
bölümünde belirttiğiniz işlevi uygulayın:- İşlev, bağımsız değişken olarak
docs.matchedUrl.url
içeren bir etkinlik nesnesini kabul etmeli ve tek birCard
nesnesi döndürmelidir. - Hizmetiniz için yetkilendirme gerekiyorsa işlev, yetkilendirme akışını da çağırmalıdır.
- İşlev, bağımsız değişken olarak
- Her önizleme kartında, arayüz için widget etkileşimi sağlayan tüm geri çağırma işlevlerini uygulayın. Örneğin, "Bağlantıyı görüntüle" yazan bir düğme eklerseniz bağlantıyı yeni bir pencerede açmak için bir geri çağırma işlevi belirten bir işlem oluşturabilirsiniz. Widget etkileşimleri hakkında daha fazla bilgi için Eklenti işlemleri konusuna bakın.
Aşağıdaki kod, caseLinkPreview
geri çağırma işlevini oluşturur:
Apps Komut Dosyası
Node.js
Python
Java
Önizleme kartları için desteklenen bileşenler
Google Workspace eklentileri, bağlantı önizleme kartları için aşağıdaki widget'ları ve işlemleri destekler:
Apps Komut Dosyası
Kart Hizmeti alanı | Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
İşlem |
Navigation |
işlemi yalnızca updateCard yöntemi desteklenir. |
JSON
Kart (google.apps.card.v1 ) alanı |
Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
İşlem |
Navigation |
işlemi yalnızca updateCard yöntemi desteklenir. |
Tam örnek: Destek kaydı eklentisi
Aşağıdaki örnekte bir şirketin destek kayıtları ve çalışan profillerine bağlantıları önizleyen bir Google Workspace eklentisi bulunmaktadır.
Örnekte aşağıdaki işlemler gerçekleştirilir:
- Önizlemeler,
https://www.example.com/support/cases/1234
gibi destek kayıtlarına bağlantı verir. Akıllı çip bir destek simgesi gösterir ve önizleme kartı, yazışma kimliğini ve açıklamasını içerir. - Destek ekibi aracılarının bağlantılarını (ör.
https://www.example.com/people/rosario-cruz
) önizler. Akıllı çip bir kişi simgesi gösteriyor. Önizleme kartı da çalışanın adını, e-posta adresini, iş unvanını ve profil fotoğrafını içeriyor. - Kullanıcının yerel ayarı İspanyolcaya ayarlanmışsa akıllı çip,
labelText
dilini İspanyolcaya yerelleştirir.
Dağıtım kaynağı
Apps Komut Dosyası
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}