Kart mesajı oluşturma

Google Chat uygulamaları, kısa mesajlara ek olarak alanlarda ve kullanıcılara kart mesajları oluşturabilir. Kartlar, tanımlı bir düzeni, düğmeler gibi etkileşimli kullanıcı arayüzü öğelerini ve resimler gibi rich media öğelerini destekler.

Aşağıdakileri yapmak için kart mesajlarını kullanın:

  • Ayrıntılı bilgi verin
  • Kullanıcılardan bilgi toplama
  • Kullanıcıları bir sonraki adımı atmaya yönlendirin

Bu kılavuzda, eşzamanlı olarak kart mesajlarının nasıl oluşturulacağı (kullanıcıdan mesaj alma veya alana eklenme gibi, bir Google Chat etkinliğine gerçek zamanlı yanıt) ve eşzamansız olarak (Google Chat API kullanarak uygulamadan alana veya kullanıcıya mesaj gönderme) açıklanmaktadır.

Ön koşullar

Bu kılavuzdaki kart mesajlarını oluşturmak için aşağıdakilere ihtiyacınız olacaktır:

Node.js

Not: Bu kılavuzdaki Node.js kod örnekleri, Google Cloud Functions olarak çalışacak şekilde yazılmıştır.

Python

Not: Bu kılavuzdaki Python kod örnekleri, Python 3.9 kullanılarak Google Cloud Functions işlevi olarak çalışacak şekilde yazılmıştır.

Apps Komut Dosyası

Kart mesajının anatomisi

Her kart, iletişim veya mesaj olsun, Google Chat API'deki spaces.messages kaynağındaki bir JSON nesnesidir.

Kart JSON nesnesi aşağıdakilerden oluşur:

  1. Bir veya daha fazla CardWithId nesne içeren cardsV2[] adlı bir dizi.
  2. Kartı tanımlamak ve belirli bir mesajın kapsamında olmak için kullanılan cardId. (Farklı mesajlardaki kartlar aynı kimliğe sahip olabilir.)

  3. Aşağıdakilerden oluşan bir card nesnesi:

    • Başlık, alt başlık ve avatar tarzı resim gibi şeyleri belirten header nesnesi.
    • Her biri en az bir widget içeren bir veya daha fazla section nesne.
    • Bir veya daha fazla widget nesne. Her widget; metin, resimler, düğmeler ve diğer nesne türlerini temsil edebilen birleşik bir nesnedir.

Örneğin, şu kart mesajındaki header, section ve widget nesnelerini inceleyin:

Kart mesajı kullanarak Chat alanında anket yayınlayan Chat uygulaması

Aşağıdaki kod, kart mesajının JSON'unu temsil eder:

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Eşzamanlı kart mesajı oluşturma

Bu örnekte, bir kullanıcı Chat uygulamasında Chat'te bir mesaj oluşturur ve uygulama, gönderenin adını ve avatar resmini gösteren basit, eşzamanlı bir kart mesajı göndererek yanıt verir:

Gönderenin görünen adını ve avatar resmini içeren bir kartla yanıt veren bir Chat uygulaması.

Aşağıdaki kod örneklerinde, Node.js ve Python uygulamaları Google Cloud Functions'da barındırılır. Apps Komut Dosyası örneği Google Apps Komut Dosyası'nda barındırılır.

Chat uygulaması derleyip dağıtma ile ilgili tüm talimatlar için Chat uygulaması oluşturma başlıklı makaleyi inceleyin.

Node.js

düğüm/avatar-bot/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/main.py
from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Apps Komut Dosyası

Apps-script/avatar-bot/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Chat API ile eşzamansız kart mesajı oluşturma

Bu örnek, eşzamansız olarak Chat API ile bir mesaj oluşturur ve Chat uygulamasının eklendiği bir alana gönderir:

Google Chat API ile oluşturulan kart kartı.
Şekil 1: Chat API ile oluşturulan bir kart mesajı.

Python

  1. Çalışma dizininizde chat_create_card_message.py adlı bir dosya oluşturun.

  2. chat_create_card_message.py alanına aşağıdaki kodu ekleyin:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # The message to create.
    body=
    {
      'cardsV2': [{
        'cardId': 'createCardMessage',
        'card': {
          'header': {
            'title': 'A Card Message!',
            'subtitle': 'Created with Chat REST API',
            'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
            'imageType': 'CIRCLE'
          },
          'sections': [
            {
              'widgets': [
                {
                  'buttonList': {
                    'buttons': [
                      {
                        'text': 'Read the docs!',
                        'onClick': {
                          'openLink': {
                            'url': 'https://developers.google.com/chat'
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }]
    }

).execute()

print(result)

  3. Koddaki SPACE kısmını, bir alan adıyla değiştirin. Bu adı Chat API'deki spaces.list() yönteminden veya alanın URL'sinden alabilirsiniz.

  4. Çalışma dizininizde örneği oluşturun ve çalıştırın:

    python3 chat_create_card_message.py

Chat API'de mesajlarla çalışma hakkında daha fazla bilgi için aşağıdaki konulara bakın:

İletişim kutusu aç

İletişim kutuları, Chat uygulamalarının kullanıcılarla etkileşimde bulunmak için açtığı pencereli, kart tabanlı arayüzlerdir. Uygulamalar, kullanıcıların çok adımlı işlemleri tamamlamasına yardımcı olmak için sıralı iletişim kutuları açabilir. Uygulamalar, bir kart mesajının tıklanmasına veya bir eğikleştirme komutuna yanıt olarak iletişim kutularını açabilir.

İletişim kutuları, aşağıdakiler de dahil olmak üzere birçok kullanıcı etkileşimi türü için kullanışlıdır:

  • Kullanıcılardan bilgi toplama
  • Web hizmetleriyle kullanıcıların kimliklerini doğrulama
  • Chat uygulaması ayarlarını yapılandırma

Bu örnekte bir Chat uygulaması, kullanıcının adres defteri için yeni bir kişi oluşturmasına yardımcı olmak için bir iletişim kutusu açar:

Çeşitli widget&#39;ların bulunduğu bir iletişim kutusu.

İletişim kutularını uygulamak için İletişim kutularını aç konusuna bakın.

Kart biçimlendirmesi

Kartların görünümünü biçimlendirmenin birkaç farklı yolu vardır.

Kart metni biçimlendirmesi

Kartların içindeki çoğu metin alanı, küçük bir HTML etiketi alt kümesi kullanılarak temel metin biçimlendirmesini destekler.

Desteklenen etiketler ve amaçları aşağıdaki tabloda gösterilmektedir:

Biçim Örnek Oluşturulan sonuç
Kalın "This is <b>bold</b>." Bu kalın yazılmıştır.
İtalik "This is <i>italics</i>." Bu italik yazılmıştır.
Altı çizili "This is <u>underline</u>." Bu, alt çizgi işaretidir.
Üstü Çizili "This is <s>strikethrough</s>." Bu üstü çizilidir.
Yazı tipi rengi "This is <font color=\"#FF0000\">red font</text>." Bu kırmızı yazı tipi'dir.
Köprü "This is a <a href=\"https://www.google.com\">hyperlink</a>." Bu bir köprüdür.
Süre "This is a time format: <time>2023-02-16 15:00</time>." Saat biçimi şu şekildedir: .
Yeni satır "This is the first line. <br> This is a new line. inç Bu ilk satır.
Bu yeni bir satırdır.

Temel bir mesajın metin gövdesinin, gerçek kullanıcılar için optimize edilen farklı bir işaretleme söz dizimi kullanılarak ayrıştırıldığını unutmayın. Ayrıntılar için Kısa mesaj oluşturma bölümüne bakın.

Yerleşik simgeler

DecoratedText ve ButtonList widget'ları, Google Chat'te bulunan yerleşik simgelerden birini belirtmek için kullanılan icon öğesini destekler:

{
  .
  .
  .
      "knownIcon": "TRAIN",
  .
  .
  .
}

Aşağıdaki tabloda, kart mesajları için kullanılabilen yerleşik simgeler listelenmiştir:

Uçak REAL
OTOBÜS ARA
SAAT ONAY_NUMARASI
AÇIKLAMA DOLAR
E-POSTA EVENT_SEAT
UÇUŞ_GELİR UÇ_KALDIRMA
OTEL HOTEL_ROOM_TYPE
DAVET ET MAP_PIN
ÜYELİK ÇOK İKİ_KULLANICI
KİŞİ TELEFON
RESTAURANT_SİMGESİ ALIŞVERİŞ_ALIŞVERİŞ
STAR MAĞAZA
BİLET EĞİTİM
VİDEO_KAMERA VİDEO_OYNATMA

Özel simgeler

DecoratedText ve ButtonList widget'ları yerleşik simgeleri kullanmanıza veya kendi özel simgelerinizi tanımlamanıza olanak tanır. Özel bir simge belirtmek için, aşağıda gösterildiği gibi iconUrl öğesini kullanın:

{ . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . }