Etkileşimli bir Google Chat uygulamasını Google Workspace eklentisine dönüştürme

Google Chat uygulaması hızlı başlangıç kılavuzuna dayalı olanlar gibi Google Chat API etkileşim etkinliklerini kullanan bir Google Chat uygulaması oluşturup yayınladıysanız bu sayfada, uygulamayı Google Chat'i genişleten bir Google Workspace eklentisine nasıl dönüştüreceğiniz gösterilmektedir.

Dönüştürme işlemiyle Google Chat uygulamanız, Google Workspace eklentileri çerçevesini kullanabilir. Bu sayede Google Chat'te ve Google Workspace'te entegrasyon ve özellikler için yeni olanaklar sunulur. Örneğin, iki dağıtım (bir Google Chat uygulaması ve bir Google Workspace eklentisi) yerine, Google Workspace Marketplace üzerinden tek bir Google Workspace eklentisi dağıtabilirsiniz. Bu eklenti, Chat uygulamalarını Gmail, Takvim ve Dokümanlar gibi diğer Google Workspace ana makine uygulamalarıyla birlikte genişletir.

Sınırlamalar

Dönüşümü başlatmadan önce, Google Chat uygulamanızın temel işlevleri kaybetmeden dönüştürülebilmesi için Google Chat'i genişleten Google Workspace eklentilerinin sınırlamaları başlıklı makaleyi inceleyin.

1. adım: Mevcut Google Chat uygulaması kodunuzu kopyalayın

Dönüşüm işlemi için kod değişiklikleri yapılması gerekir. Canlı Google Chat uygulamanızı etkilememek için kodunuzun bir kopyasını oluşturup bu kopya üzerinde çalışın.

Apps Komut Dosyası

  1. Mevcut Google Chat uygulaması Google Apps Komut Dosyası projenizi açın.
  2. Sol tarafta Genel bakış'ı tıklayın.
  3. Sağ tarafta Kopya oluştur'u tıklayın.
  4. Sol tarafta Proje Ayarları'nı tıklayın.
  5. Google Cloud projesi bölümünde Projeyi değiştir'i tıklayın.
  6. Mevcut Google Chat uygulaması projenizle ilişkili proje numarasını girin.
  7. Projeyi ayarla'yı tıklayın.

HTTP

Mevcut kod tabanınızın bir çatalını veya kopyasını oluşturup canlı Google Chat uygulamanızdan ayrı olarak yeni bir hizmet şeklinde dağıtın.

Uygulamanız Google Cloud'da dağıtılıyorsa ve Google Cloud projesiyle ilişkili özelliklere (ör. varsayılan App Engine kimliği) bağlıysa yeni kod, mevcut Google Chat uygulama projesiyle ilişkili bir hizmete dağıtılmalıdır.

2. adım: Kopyalanan kodu değiştirin

Google Chat'in kullanımını genişleten Google Workspace eklentileri, Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulamalarına kıyasla farklı istek ve yanıt yapıları kullanır. İstekler ve yanıtlar için Google Chat API'leri Event yerine Google Workspace eklentisini EventObject kullanmak üzere kodunuzu güncellemeniz gerekir. Kodunuzu değiştirmek için Kod dönüştürme kılavuzunu kullanın.

3. adım: Test kullanıcıları için Google Workspace eklenti yapılandırmasını etkinleştirin

Google Chat uygulamanız için Google Workspace eklenti ayarlarını yapılandırmak üzere Google Cloud Console'u kullanın:

  1. Google Cloud Console'da Google Chat API yapılandırma sayfasına gidin.

    Google Chat API yapılandırma sayfasına gidin

  2. Etkileşimli Özellikler bölümünde Eklentiye dönüştür'ü tıklayın.

  3. Eklenti yapılandırma ayarlarını etkinleştir'i etkinleştirin.

  4. Görünürlük bölümüne test kullanıcılarınızın e-posta adreslerini ekleyin.

  5. Gerekirse Bağlantı Ayarları'nı, 2. adımda kopyalayıp değiştirdiğiniz Google Chat uygulama kodunuzun dağıtım uç noktası URL'si veya Apps Komut Dosyası dağıtım kimliği ile güncelleyin.

  6. Kaydet ve test et'i tıklayın.

4. adım: Dönüştürülen uygulamayı test edin

3. adımda yapılandırılan test kullanıcı hesaplarını kullanarak Google Workspace eklentisinin işlevselliğini kapsamlı bir şekilde test edin. Tüm özellikleri ve etkileşimleri doğrulayın.

5. adım: Tüm kullanıcılar için dönüşümü tamamlayın

Dönüştürülen Google Workspace eklentisinin doğru çalıştığını doğruladıktan sonra eklentiyi tüm kullanıcıların kullanımına sunabilirsiniz.

  1. Google Cloud Console'da Google Chat API yapılandırma sayfasına gidin.

    Google Chat API yapılandırma sayfasına gidin

  2. Etkileşimli Özellikler bölümünde Eklentiye dönüştür'ü tıklayın. Bir yan panel açılır.

  3. Yan panelde Eklentiye dönüştür'ü tıklayın.

  4. Proje kimliğinizi yazın ve Dönüştür'ü tıklayın.

Google Chat uygulamanız artık Google Chat'i genişleten bir Google Workspace eklentisi.

İsteğe bağlı: Kullanılmayan Google Cloud kaynaklarını temizleme veya boşaltma

İsteğe bağlı olarak, Google Chat uygulamanızı Google Workspace eklentisine dönüştürdükten sonra, artık kullanılmayan Google Chat uygulaması tarafından kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek amacıyla bu kaynakları devre dışı bırakabilirsiniz.

Kod dönüştürme kılavuzu

Bu bölümde, Google Chat API etkileşimi Event biçimi ile Google Workspace eklentisi EventObject biçimi arasındaki eşleme ayrıntılı olarak açıklanmaktadır.

İstek eşleme

Aşağıdaki tabloda, Google Chat API'sindeki alanların Event Google Workspace eklentisindeki karşılık gelen alanlarla nasıl eşlendiği gösterilmektedir. EventObject

Google Chat API etkileşimi Event alanı Google Workspace eklentisi EventObject alanı Notlar
action.actionMethodName Yok Kart etkileşimlerinde yöntem adı, commonEventObject.parameters içinde parametre olarak iletilebilir. İlk iletişim kutusunu açma başlıklı makaleyi inceleyin.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Etkinlik türüne bağlı olarak farklı yüklerde kullanılabilir.
token Yok Doğrulama farklı şekilde yapılır. HTTP Uygulamaları İçin Doğrulama İsteği başlıklı makaleyi inceleyin.
type Yok Etkinlik türü, trigger özelliğinden anlaşılabilir.
user chat.user

Kullanım alanına göre eşleme isteğinde bulunma

Aşağıdaki tabloda, yaygın kullanım alanlarındaki istek yükleri açısından, Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulamaları ile Google Chat'i genişleten Google Workspace eklentileri arasındaki farklar gösterilmektedir.

Kullanım Örneği Chat API etkileşimi Event Yük Google Workspace eklentisi EventObject yükü
Uygulama alana eklendi 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Uygulamayı alandan kaldırma 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Kullanıcı bir uygulamadan @bahsederse 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
Kullanıcı, alana eklemek için bir uygulamadan @ bahsediyor Google Chat'ten gelen bir isteği yanıtlamanız gerekir:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Google Chat'ten gelen iki isteği ele almanız gerekir.

İlk istek:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

İkinci istek:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Eğik çizgi komutu 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Alana uygulama eklemek için eğik çizgi komutu Google Chat'ten gelen bir isteği yanıtlamanız gerekir:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Google Chat'ten gelen iki isteği işlemeniz gerekir.

İlk istek:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

İkinci istek:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Kullanıcı bir kartta veya iletişim kutusunda bir düğmeyi tıkladığında 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

İletişim kutusu etkinlikleri için common.formInputs, widget değerlerini içerir. Google Apps Komut Dosyası örneği:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

İletişim kutusu etkinlikleri için commonEventObject.formInputs, widget değerlerini içerir. Google Apps Komut Dosyası örneği:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
Kullanıcı, uygulama ana sayfası kartına bilgi gönderdiğinde 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
Kullanıcı, hızlı komut kullanarak bir uygulama komutu çağırır. 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Bağlantı önizleme 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
Kullanıcı, kart mesajında veya iletişim kutusunda bir widget'ı güncellerse 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Kullanım alanına göre yanıt eşleme

Google Chat'i genişleten Google Workspace eklentileri, Message nesnesi yerine işlem döndürür. Aşağıdaki tabloda, Google Chat API Message yanıt türleri ile Google Workspace eklentisi işlem karşılıkları eşlenmiştir.

Kullanım Örneği Google Chat API Message Yanıtı Google Workspace eklentisi Chat işlemi yanıtı
Çağrılan alanda mesaj oluşturma 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse isteğe bağlıdır. Daha fazla bilgi için Eğik çizgi komutlarına yanıt verme başlıklı makaleyi inceleyin.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Daha fazla bilgi edinmek için Mesaj gönderme başlıklı makaleyi inceleyin.
İletileri güncelleme 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Daha fazla bilgi edinmek için Mesajı güncelleme (Chat) başlıklı makaleyi inceleyin.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Daha fazla bilgi edinmek için Mesajı güncelleme (eklentiler) başlıklı makaleyi inceleyin.
Bağlantı önizleme 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Daha fazla bilgi edinmek için Bağlantıyı önizleme (Chat) başlıklı makaleyi inceleyin.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Daha fazla bilgi edinmek için Bağlantıyı önizleme(eklentiler) başlıklı makaleyi inceleyin.
İlk iletişim kutusunu açma 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Daha fazla bilgi edinmek için İletişim kutusu açma (Chat) başlıklı makaleyi inceleyin.

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
Gönderdiğiniz kart, onClick işlemleri içeren widget'lar içerebilir. HTTP Google Workspace eklentileri için bir işlev uç noktasını çağırmak üzere şu işlemleri yapılandırın: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Daha fazla bilgi edinmek için İletişim kutusu açma (eklentiler) başlıklı makaleyi inceleyin.
İletişim kutusunu kapatma 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Daha fazla bilgi edinmek için İletişim kutusunu kapatma (Chat) başlıklı makaleyi inceleyin.

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Daha fazla bilgi edinmek için İletişim kutusunu kapatma (eklentiler) başlıklı makaleyi inceleyin.
Harici bir sisteme bağlanma (yapılandırma isteği) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Daha fazla bilgi edinmek için Harici bir sisteme bağlanma başlıklı makaleyi inceleyin.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Daha fazla bilgi için Google Workspace eklentinizi üçüncü taraf hizmetine bağlama başlıklı makaleyi inceleyin.
Etkileşimli widget'larda öğeleri otomatik tamamlama 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Daha fazla bilgi edinmek için Çoklu seçim menüsü ekleme başlıklı makaleyi inceleyin.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Daha fazla bilgi edinmek için Google Chat kullanıcılarından bilgi toplama ve bu bilgileri işleme başlıklı makaleyi inceleyin.

Dönüşümden önce oluşturulan mesajlardaki kart etkileşimlerini yönetme

Bir HTTP Google Chat uygulamasını Google Workspace eklentisine dönüştürdüğünüzde, dönüştürme işleminden önce oluşturulan iletilerdeki kart etkileşimleri özel işlem gerektirir. Google Workspace eklentileri, kartın action.function için tam bir HTTP URL'si kullanırken Google Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulamaları bir işlev adı kullanır. Aşağıdaki tabloda bu farklılıklar özetlenmektedir.

Google Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulaması Google Chat'i genişleten Google Workspace eklentisi
Yapılandırma Google Cloud Console'da tüm etkinlikler için tek bir uç nokta yapılandırabilirsiniz. Kart etkileşimleri uygulanırken bir kartın action yalnızca yürütülecek işlevin adını içerir. Kart tıklama etkinlikleri için ortak HTTP uç noktası çağrılır.

Daha fazla bilgi edinmek için İletişim kutusu açma (Chat) başlıklı makaleyi inceleyin.



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Google Cloud Console'da etkinlik başına uç noktaları isteğe bağlı olarak yapılandırabilirsiniz ancak bu, kart tıklama etkinliklerini içermez. Kart etkileşimleri uygulanırken bir kartın action, çağrılacak HTTP uç noktasının tam URL'sini içermelidir. Düğme başına benzersiz bir HTTP uç noktası ayarlayabilir veya ortak bir uç nokta kullanıp işlemi action.parameters içinde parametre olarak iletebilirsiniz.

Daha fazla bilgi edinmek için İletişim kutusu açma (eklentiler) başlıklı makaleyi inceleyin.



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Dönüşümden önce oluşturulan mesajlarda kart etkileşimlerinin çalışır durumda olması için Google Chat API yapılandırma sayfasında bir Kart Etkileşimi URL'si yapılandırın.

Bu URL yalnızca uygulamanızı dönüştürmeden önce oluşturulan mesajlardaki etkileşimler için kullanılır. Bir kullanıcı bu mesajlardan biriyle etkileşimde bulunduğunda orijinal action.function değeri, __action_method_name__ adlı bir parametre olarak iletilir.

Örnek: Kart tıklaması

Kart Etkileşimi URL'sini https://.../card-interaction-handler olarak yapılandırdıysanız ve bir kullanıcı aşağıdaki işlemle birlikte geçmiş bir iletideki kartı tıklarsa:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Bir etkinlik, yapılandırılmış Kart Etkileşimi URL'nize aşağıdaki biçimde iletilir:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Örnek: Çoklu seçim menüsü

Bir kullanıcı, harici veri kaynağı içeren çoklu seçim menüsüyle etkileşimde bulunursa:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Bir etkinlik, yapılandırılmış Kart Etkileşimi URL'nize aşağıdaki biçimde iletilir:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

HTTP tetikleyicileriniz için Tüm tetikleyicilerde ortak HTTP uç noktası URL'si kullan seçeneğini etkinleştirirseniz ortak URL, Düğme Tıklandı etkinlikleri için de kullanılır.

Chat'i genişleten HTTP Google Workspace eklentileri için istekleri doğrulama

HTTP tabanlı Google Chat uygulamalarında, isteklerin Google'dan geldiğini doğrulayan mantığın Google Workspace eklentisine dönüştürülürken güncellenmesi gerekir.

İstek doğrulama ile ilgili temel farklar şunlardır:

Uygulama Türü Desteklenen Kitle Hizmet Hesabı E-postası
Google Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulaması Proje numarası chat@system.gserviceaccount.com
Google Chat'i genişleten Google Workspace eklentisi Yalnızca HTTP uç noktası Proje başına hizmet hesabı e-postası

Google Workspace eklentiniz için benzersiz hizmet hesabı e-posta adresini, Google Cloud Console'daki Google Chat API yapılandırma sayfasının Google Workspace eklentilerine dönüştürme bölümünde bulabilirsiniz.

Yükseltilmiş Google Workspace eklentinizdeki istekleri doğrulamak için:

  1. Cloud Run işlevlerini kullanıyorsanız eklenti başına hizmet hesabına roles/cloudfunctions.invoker rolünü verin. IAM ile erişime yetki verme başlıklı makaleyi inceleyin.
  2. Taşıyıcı jetonunun imzasını doğrulamak için jeton doğrulama kodunuzu, Google Workspace eklenti hizmeti hesap e-posta adresini kullanacak şekilde güncelleyin. Google'dan gelen istekleri doğrulama başlıklı makaleyi inceleyin.