Bu sayfa, Cloud Translation API ile çevrilmiştir.

Google Chat kullanıcılarından bilgi toplama ve işleme

Bu kılavuzda, Google Chat uygulamalarının kart tabanlı arayüzlerde form girişleri oluşturarak kullanıcılardan nasıl bilgi toplayıp işleyebileceği açıklanmaktadır.

Çeşitli widget'ların yer aldığı bir iletişim kutusu. — **Şekil 1**: İletişim bilgilerini toplamak için iletişim kutusu açan bir Chat uygulaması.

**Şekil 1**: İletişim bilgilerini toplamak için iletişim kutusu açan bir Chat uygulaması.

Chat uygulamaları, Chat'te veya Chat dışında işlem yapmak için kullanıcılardan bilgi ister. Örneğin:

Ayarları yapılandırın. Örneğin, kullanıcıların bildirim ayarlarını özelleştirmesine veya Chat uygulamasını bir ya da daha fazla alana yapılandırıp eklemesine izin vermek için.
Diğer Google Workspace uygulamalarında bilgi oluşturma veya güncelleme Örneğin, kullanıcıların Google Takvim etkinliği oluşturmasına izin verin.
Kullanıcıların diğer uygulamalardaki veya web hizmetlerindeki kaynaklara erişmesine ve bunları güncellemesine izin verin. Örneğin, bir Chat uygulaması, kullanıcıların destek kaydının durumunu doğrudan bir Chat alanından güncellemesine yardımcı olabilir.

Ön koşullar

HTTP

Google Chat'i genişleten bir Google Workspace eklentisi Bir tane oluşturmak için HTTP hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Google Chat'i genişleten bir Google Workspace eklentisi Bir tane oluşturmak için Apps Komut Dosyası hızlı başlangıç kılavuzunu tamamlayın.

Kartları kullanarak form oluşturma

Chat uygulamaları, bilgi toplamak için formlar ve girişler tasarlayıp bunları kartlara yerleştirir. Chat uygulamaları, kullanıcılara kart göstermek için aşağıdaki Chat arayüzlerini kullanabilir:

Bir veya daha fazla kart içeren sohbet mesajları
İletişim kutuları: İletilerden ve ana sayfalardan yeni bir pencerede açılan kartlardır.

Chat uygulamaları, aşağıdaki widget'ları kullanarak kart oluşturabilir:

Kullanıcılardan bilgi isteyen form girişi widget'ları. İsteğe bağlı olarak, kullanıcıların bilgileri doğru şekilde girip biçimlendirmesini sağlamak için form girişi widget'larına doğrulama ekleyebilirsiniz. Sohbet uygulamaları aşağıdaki form girişi widget'larını kullanabilir:
- Serbest biçimli veya önerilen metin için metin girişleri (textInput).
- Seçim girişleri (selectionInput), onay kutuları, radyo düğmeleri ve açılır menüler gibi seçilebilir kullanıcı arayüzü öğeleridir. Seçim girişi widget'ları, Google Workspace verilerindeki (ör. Chat alanı) veya dinamik bir veri kaynağındaki öğeleri de doldurup önerebilir. Ayrıntılar için Çoklu seçim menüsü ekleme başlıklı bölümü inceleyin.
- Tarih ve saat girişleri için tarih ve saat seçiciler (dateTimePicker)
Kullanıcıların karta girdikleri değerleri gönderebilmeleri için düğme widget'ı. Kullanıcı düğmeyi tıkladıktan sonra Chat uygulaması aldığı bilgileri işleyebilir.

Aşağıdaki örnekte, bir kart metin girişi, tarih/saat seçici ve seçim girişi kullanarak iletişim bilgilerini topluyor:

Bilgi toplamak için kullanabileceğiniz etkileşimli widget'larla ilgili daha fazla örnek için Google Chat API belgelerindeki Etkileşimli kart veya iletişim kutusu tasarlama başlıklı makaleye bakın.

Çoklu seçim menüsü ekleme

Chat uygulamaları, seçim öğelerini özelleştirmek veya kullanıcıların dinamik bir veri kaynağındaki öğeleri seçmesine izin vermek için SelectionInput türünde bir widget olan çoklu seçim menülerini kullanabilir. Örneğin, aşağıdaki kartta, kullanıcıların bir kişi listesinden dinamik olarak seçim yapabileceği çoklu seçim menüsü gösteriliyor:

Çoklu seçim menüsündeki öğeleri aşağıdaki veri kaynaklarından doldurabilirsiniz:

Google Workspace verileri (kullanıcıların veya kullanıcının üyesi olduğu Chat alanları dahil) Menüye yalnızca aynı Google Workspace kuruluşundaki öğeler eklenir.
İlişkisel veritabanı gibi harici veri kaynakları Örneğin, bir kullanıcının müşteri ilişkileri yönetimi (CRM) sistemindeki satış potansiyel müşterileri listesinden seçim yapmasına yardımcı olmak için çoklu seçim menülerini kullanabilirsiniz.

Google Workspace veri kaynağından öğe doldurma

Google Workspace veri kaynaklarını kullanmak için SelectionInput widget'ında platformDataSource alanını belirtin. Diğer seçim girişi türlerinin aksine, bu seçim öğeleri Google Workspace'ten dinamik olarak alındığından nesneleri SelectionItem ile atlıyorsunuz.

Aşağıdaki kodda, Google Workspace kullanıcılarının bulunduğu çoklu seçim menüsü gösterilmektedir. Kullanıcıları doldurmak için seçim girişi commonDataSource değerini USER olarak ayarlar:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Aşağıdaki kodda, Chat alanlarının çoklu seçim menüsü gösterilmektedir. Boşlukları doldurmak için seçim girişi hostAppDataSource alanını belirtir. Çoklu seçim menüsü, defaultToCurrentSpace öğesini true olarak da ayarlar. Bu sayede, geçerli alan menüdeki varsayılan seçim olur:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Öğeleri harici bir veri kaynağından doldurma

Çoklu seçim menüleri, üçüncü taraf veya harici veri kaynaklarındaki öğelerle de doldurulabilir. Harici bir veri kaynağı kullanmak için externalDataSource alanını SelectionInput widget'ında belirtirsiniz. Bu alan, veri kaynağındaki öğeleri sorgulayan ve döndüren işlevi içerir.

Harici bir veri kaynağına yapılan istekleri azaltmak için kullanıcılar menüye yazmadan önce çoklu seçim menüsünde görünen önerilen öğeleri ekleyebilirsiniz. Örneğin, kullanıcı için son aranan kişileri doldurabilirsiniz. Önerilen öğeleri harici bir veri kaynağından doldurmak için statik SelectionItem nesnelerini belirtin.

Aşağıdaki kod, öğeleri harici bir veri kaynağından sorgulayan ve dolduran çoklu seçim menüsünü gösterir:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

FUNCTION yerine, harici veritabanını sorgulayan HTTP URL'sini veya Apps Komut Dosyası işlev adını yazın. Önerilen öğelerin nasıl döndürüleceğini gösteren eksiksiz bir örnek için Birden fazla öğe önerme bölümüne bakın.

Etkileşimli widget'lardan veri alma

Kullanıcılar bir düğmeyi her tıkladığında, etkileşimle ilgili bilgilerle birlikte Chat uygulamalarının işlemi tetiklenir. Etkinlik yükünün commonEventObject bölümünde, formInputs nesnesi kullanıcının girdiği tüm değerleri içerir.

Değerleri, commonEventObject.formInputs.WIDGET_NAME nesnesinden alabilirsiniz. Burada WIDGET_NAME, widget için belirttiğiniz name alanıdır. Değerler, widget için belirli bir veri türü olarak döndürülür.

Aşağıda, bir kullanıcının her widget için değer girdiği bir etkinlik nesnesinin bir bölümü gösterilmektedir:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Chat uygulamanız, verileri almak için kullanıcıların widget'lara girdiği değerleri almak üzere etkinlik nesnesini işler. Aşağıdaki tabloda, belirli bir form girişi widget'ının değerinin nasıl alınacağı gösterilmektedir. Tabloda, her widget için widget'ın kabul ettiği veri türü, değerin etkinlik nesnesinde depolandığı yer ve örnek bir değer gösterilir.

Form girişi widget'ı	Giriş verilerinin türü	Etkinlik nesnesinden giriş değeri	Örnek değer
`textInput`	`stringInputs`	`event.commonEventObject.formInputs.contactName.stringInputs.value[0]`	`Kai O`
`selectionInput`	`stringInputs`	İlk veya tek değeri almak için `event.commonEventObject.formInputs.contactType.stringInputs.value[0]`	`Personal`
Yalnızca tarihleri kabul eden `dateTimePicker`.	`dateInput`	`event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch`.	`1000425600000`

Chat uygulaması verileri aldıktan sonra aşağıdakilerden herhangi birini yapabilir:

Çoklu seçim menüsü içeren kartlarda, kullanıcının menüye yazdıklarına göre öğeleri doldurun veya önerin.
Kullanıcının bilgilerini inceleyebilmesi veya formun bir sonraki bölümüne geçebilmesi için verileri başka bir karta aktarın.
Kullanıcının formu başarıyla doldurduğunu onaylamak için kullanıcıya yanıt verin.

Çoklu seçim öğeleri önerme

Bir kartta öğeleri harici bir veri kaynağından dolduran çoklu seçim menüsü varsa Chat uygulaması, kullanıcıların menüye yazdıklarına göre önerilen öğeleri döndürebilir. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başlarsa Chat uygulamanız, kullanıcı yazmayı bitirmeden önce Atlanta otomatik olarak önerebilir. Sohbet uygulaması en fazla 100 öğe önerebilir.

Çoklu seçim menüsünde öğe önermek ve dinamik olarak doldurmak için karttaki SelectionInput widget'ında harici veri kaynağını sorgulayan bir işlev belirtilmelidir. Önerilen öğeleri döndürmek için işlev aşağıdakileri yapmalıdır:

Kullanıcılar menüye yazdığında Chat uygulamasının aldığı etkinlik nesnesini işleyin.
Etkinlik nesnesinden, kullanıcının yazdığı değeri alın. Bu değer, event.commonEventObject.parameters["autocomplete_widget_query"] alanında gösterilir.
Kullanıcıya önerilecek bir veya daha fazla SelectionItems almak için kullanıcı girişi değerini kullanarak veri kaynağını sorgulayın.
İşlem RenderActions öğesini modifyCard ile döndürerek önerilen öğeleri döndürün.

Aşağıdaki kod örneğinde, bir Chat uygulamasının karttaki çoklu seçim menüsünde öğeleri nasıl dinamik olarak önerdiği gösterilmektedir. Kullanıcı menüye yazdığında, widget'ın externalDataSource alanında sağlanan işlev veya uç nokta, harici bir veri kaynağını sorgular ve kullanıcının seçebileceği öğeler önerir.

Node.js

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

FUNCTION_URL kısmını, harici veri kaynağını sorgulayan HTTP uç noktasıyla değiştirin.

Apps Komut Dosyası

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Verileri başka bir karta aktarma

Bir kullanıcı karttan bilgi gönderdikten sonra, aşağıdakilerden herhangi birini yapmak için ek kartlar döndürmeniz gerekebilir:

Farklı bölümler oluşturarak kullanıcıların daha uzun formları tamamlamasına yardımcı olun.
Kullanıcıların, ilk karttaki bilgileri önizleyip onaylamasına izin verin. Böylece, yanıtlarını göndermeden önce inceleyebilirler.
Formun kalan kısımlarını dinamik olarak doldurun. Örneğin, bir Chat uygulaması, kullanıcıları randevu oluşturmaya yönlendirmek için randevu nedenini soran bir ilk kart gösterebilir ve ardından randevu türüne göre uygun zamanları sağlayan başka bir kartı doldurabilir.

İlk karttan girilen verileri aktarmak için aşağıdaki örnekte gösterildiği gibi, widget'ın name ve kullanıcının girdiği değeri içeren actionParameters ile button widget'ını oluşturabilirsiniz:

Node.js

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Apps Komut Dosyası

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Burada WIDGET_NAME, widget'ın name, USER_INPUT_VALUE ise kullanıcının girdiği değerdir. Örneğin, bir kişinin adını toplayan bir metin girişi için widget adı contactName, örnek değer ise Kai O olur.

Kullanıcı düğmeyi tıkladığında Chat uygulamanız, veri alabileceğiniz bir etkinlik nesnesi alır.

Form gönderimine yanıt verme

Kart mesajından veya iletişim kutusundan verileri aldıktan sonra Chat uygulaması, verilerin alındığını onaylayarak ya da hata döndürerek yanıt verir.

Aşağıdaki örnekte, bir sohbet uygulaması, kart mesajından gönderilen bir formu başarıyla aldığını onaylamak için kısa mesaj gönderiyor.

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle message payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Apps Komut Dosyası

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Bir iletişim kutusunu işleyip kapatmak için RenderActions nesnesi döndürürsünüz. Bu nesne, onay mesajı göndermek, orijinal mesajı veya kartı güncellemek ya da yalnızca iletişim kutusunu kapatmak isteyip istemediğinizi belirtir. Adımlar için İletişim kutusunu kapatma başlıklı makaleyi inceleyin.

Sorun giderme

Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" mesajı gösterilir. veya "İsteğiniz işlenemiyor." Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç üretir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmese de Chat uygulamaları için hata günlüğü kaydı etkinleştirildiğinde hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hataları ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.

Google Chat kullanıcılarından bilgi toplama ve işleme Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Ön koşullar

HTTP

Apps Komut Dosyası

Kartları kullanarak form oluşturma

Çoklu seçim menüsü ekleme

Google Workspace veri kaynağından öğe doldurma

JSON

JSON

Öğeleri harici bir veri kaynağından doldurma

JSON

Etkileşimli widget'lardan veri alma

Çoklu seçim öğeleri önerme

Node.js

Apps Komut Dosyası

Verileri başka bir karta aktarma

Node.js

Apps Komut Dosyası

Form gönderimine yanıt verme

Node.js

Apps Komut Dosyası

Sorun giderme

Google Chat kullanıcılarından bilgi toplama ve işleme