HTTP Google Chat uygulaması oluşturma

Bu sayfada, HTTP hizmeti kullanarak Google Chat'te çalışan bir Google Workspace eklentisinin nasıl oluşturulacağı açıklanmaktadır.

Bu hızlı başlangıç kılavuzunda, Google Cloud hizmetlerini kullanarak nasıl HTTP hizmeti oluşturacağınız gösterilmektedir. Sohbet uygulamasını oluşturmak için, kullanıcının mesajına yanıt vermek üzere Sohbet uygulamasının kullandığı bir Cloud Run işlevi yazıp dağıtırsınız.

HTTP mimarisinde, aşağıdaki şemada gösterildiği gibi HTTP kullanarak Chat'i Google Cloud veya şirket içi bir sunucuyla entegre olacak şekilde yapılandırırsınız:

Şirket içi sunucuda web hizmeti kullanan bir Chat uygulamasının mimarisi.

Yukarıdaki şemada, bir HTTP Chat uygulamasıyla etkileşimde bulunan kullanıcının bilgi akışı şu şekildedir:

  1. Kullanıcı, Chat'te bir Chat uygulamasına doğrudan mesaj veya Chat alanı üzerinden mesaj gönderir.
  2. Chat uygulaması mantığını içeren bir bulut veya şirket içi sistem olan web sunucusuna bir HTTP isteği gönderilir.
  3. İsteğe bağlı olarak, Chat uygulaması mantığı Google Workspace hizmetleriyle (ör. Takvim ve E-Tablolar), diğer Google hizmetleriyle (ör. Haritalar, YouTube ve Vertex AI) veya diğer web hizmetleriyle (ör. proje yönetim sistemi ya da destek kaydı aracı) entegre edilebilir.
  4. Web sunucusu, Chat'teki Chat uygulaması hizmetine bir HTTP yanıtı geri gönderir.
  5. Yanıt, kullanıcıya iletilir.
  6. İsteğe bağlı olarak, Chat uygulaması mesajları eşzamansız olarak yayınlamak veya başka işlemler gerçekleştirmek için Chat API'yi çağırabilir.

Bu mimari, farklı programlama dilleri kullanılarak tasarlanabilen bu sohbet uygulamaları sayesinde sisteminizde zaten bulunan mevcut kitaplıkları ve bileşenleri kullanma esnekliği sunar.

Hedefler

  • Ortamınızı ayarlayın.
  • Cloud Run işlevi oluşturma ve dağıtma
  • Chat uygulaması için bir Google Workspace eklentisi yapılandırın.
  • Uygulamayı test edin.

Ön koşullar

Ortamı ayarlama

Google API'lerini kullanmadan önce bir Google Cloud projesinde etkinleştirmeniz gerekir. Tek bir Google Cloud projesinde bir veya daha fazla API'yi etkinleştirebilirsiniz.
  • Google Cloud Console'da Cloud Build API, Cloud Functions API, Cloud Pub/Sub API, Cloud Logging API, Artifact Registry API ve Cloud Run API'yi etkinleştirin.

    API'leri etkinleştirme

Cloud Run işlevi oluşturma ve dağıtma

Gönderenin görünen adını ve avatar resmini içeren bir sohbet kartı oluşturan ve dağıtan bir Cloud Run işlevi oluşturun. Chat uygulaması bir mesaj aldığında işlevi çalıştırır ve kartla yanıt verir.

Chat uygulamanız için işlev oluşturup dağıtmak üzere aşağıdaki adımları tamamlayın:

Node.js

  1. Google Cloud Console'da Cloud Run sayfasına gidin:

    Cloud Run'a git

    Chat uygulamanızın projesinin seçildiğinden emin olun.

  2. Write a function'ı (İşlev yaz) tıklayın.

  3. Hizmet oluştur sayfasında işlevinizi ayarlayın:

    1. Hizmet adı alanına addonchatapp girin.
    2. Bölge listesinden bir bölge seçin.
    3. Çalışma zamanı listesinde Node.js'nin en son sürümünü seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. Oluştur'u tıklayın ve Cloud Run'ın hizmeti oluşturmasını bekleyin. Konsol sizi Kaynak sekmesine yönlendirir.
  4. Kaynak sekmesinde:

    1. Giriş noktası bölümünde varsayılan metni silip avatarApp değerini girin.
    2. index.js dosyasının içeriğini aşağıdaki kodla değiştirin:
    node/chat/avatar-app/index.js
    import { http } from '@google-cloud/functions-framework';
    
    // The ID of the slash command "/about".
    // You must use the same ID in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = 1;
    
    /**
     * Handle requests from Google Workspace add on
     *
     * @param {Object} req Request sent by Google Chat
     * @param {Object} res Response to be sent back to Google Chat
     */
    http('avatarApp', (req, res) => {
      const chatEvent = req.body.chat;
      let message;
      if (chatEvent.appCommandPayload) {
        message = handleAppCommand(chatEvent);
      } else {
        message = handleMessage(chatEvent);
      }
      res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
        message: message
      }}}});
    });
    
    /**
     * Responds to an APP_COMMAND event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleAppCommand(event) {
      switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
        case ABOUT_COMMAND_ID:
          return {
            text: 'The Avatar app replies to Google Chat messages.'
          };
      }
    }
    
    /**
     * Responds to a MESSAGE event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleMessage(event) {
      // Stores the Google Chat user as a variable.
      const chatUser = event.messagePayload.message.sender;
      const displayName = chatUser.displayName;
      const avatarUrl = chatUser.avatarUrl;
      return {
        text: 'Here\'s your avatar',
        cardsV2: [{
          cardId: 'avatarCard',
          card: {
            name: 'Avatar Card',
            header: {
              title: `Hello ${displayName}!`,
            },
            sections: [{ widgets: [{
              textParagraph: { text: 'Your avatar picture: ' }
            }, {
              image: { imageUrl: avatarUrl }
            }]}]
          }
        }]
      };
    }
    1. Kaydet ve yeniden dağıt'ı tıklayın.

Python

  1. Google Cloud Console'da Cloud Run sayfasına gidin:

    Cloud Run'a git

    Chat uygulamanızın projesinin seçildiğinden emin olun.

  2. Write a function'ı (İşlev yaz) tıklayın.

  3. Hizmet oluştur sayfasında işlevinizi ayarlayın:

    1. Hizmet adı alanına addonchatapp girin.
    2. Bölge listesinden bir bölge seçin.
    3. Çalışma zamanı listesinde Python'ın en son sürümünü seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. Oluştur'u tıklayın ve Cloud Run'ın hizmeti oluşturmasını bekleyin. Konsol sizi Kaynak sekmesine yönlendirir.
  4. Kaynak sekmesinde:

    1. Giriş noktası bölümünde varsayılan metni silip avatar_app değerini girin.
    2. main.py dosyasının içeriğini aşağıdaki kodla değiştirin:
    python/chat/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # You must use the same ID in the Google Chat API configuration.
    ABOUT_COMMAND_ID = 1
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
      """Handle requests from Google Workspace add on
    
      Args:
        flask.Request req: the request sent by Google Chat
    
      Returns:
        Mapping[str, Any]: the response to be sent back to Google Chat
      """
      chat_event = req.get_json(silent=True)["chat"]
      if chat_event and "appCommandPayload" in chat_event:
        message = handle_app_command(chat_event)
      else:
        message = handle_message(chat_event)
      return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
          "message": message
      }}}}
    
    def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to an APP_COMMAND event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
        return {
          "text": "The Avatar app replies to Google Chat messages.",
        }
      return {}
    
    def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to a MESSAGE event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      # Stores the Google Chat user as a variable.
      chat_user = event["messagePayload"]["message"]["sender"]
      display_name = chat_user.get("displayName", "")
      avatar_url = chat_user.get("avatarUrl", "")
      return {
        "text": "Here's your avatar",
        "cardsV2": [{
          "cardId": "avatarCard",
          "card": {
            "name": "Avatar Card",
            "header": {
              "title": f"Hello {display_name}!"
            },
            "sections": [{ "widgets": [
              { "textParagraph": { "text": "Your avatar picture:" }},
              { "image": { "imageUrl": avatar_url }},
            ]}]
          }
        }]
      }
    1. Kaydet ve yeniden dağıt'ı tıklayın.

Java

  1. Google Cloud Console'da Cloud Run sayfasına gidin:

    Cloud Run'a git

    Chat uygulamanızın projesinin seçildiğinden emin olun.

  2. Write a function'ı (İşlev yaz) tıklayın.

  3. Hizmet oluştur sayfasında işlevinizi ayarlayın:

    1. Hizmet adı alanına addonchatapp girin.
    2. Bölge listesinden bir bölge seçin.
    3. Runtime (Çalışma zamanı) listesinde Java'nın en son sürümünü seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. Oluştur'u tıklayın ve Cloud Run'ın hizmeti oluşturmasını bekleyin. Konsol sizi Kaynak sekmesine yönlendirir.
  4. Kaynak sekmesinde:

    1. Giriş noktası bölümünde varsayılan metni silip App değerini girin.
    2. Varsayılan Java dosyasını src/main/java/com/google/chat/avatar/App.java olarak yeniden adlandırın.
    3. App.java dosyasının içeriğini aşağıdaki kodla değiştirin:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;
    
    import com.google.api.services.chat.v1.model.CardWithId;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
    import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
    import com.google.api.services.chat.v1.model.Message;
    import com.google.cloud.functions.HttpFunction;
    import com.google.cloud.functions.HttpRequest;
    import com.google.cloud.functions.HttpResponse;
    import com.google.gson.Gson;
    import com.google.gson.JsonObject;
    import java.util.List;
    
    public class App implements HttpFunction {
      // The ID of the slash command "/about".
      // You must use the same ID in the Google Chat API configuration.
      private static final int ABOUT_COMMAND_ID = 1;
    
      private static final Gson gson = new Gson();
    
      /**
       * Handle requests from Google Workspace add on
       * 
       * @param request the request sent by Google Chat
       * @param response the response to be sent back to Google Chat
       */
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
        JsonObject chatEvent = event.getAsJsonObject("chat");
        Message message;
        if (chatEvent.has("appCommandPayload")) {
          message = handleAppCommand(chatEvent);
        } else {
          message = handleMessage(chatEvent);
        }
        JsonObject createMessageAction = new JsonObject();
        createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
        JsonObject chatDataAction = new JsonObject();
        chatDataAction.add("createMessageAction", createMessageAction);
        JsonObject hostAppDataAction = new JsonObject();
        hostAppDataAction.add("chatDataAction", chatDataAction);
        JsonObject dataActions = new JsonObject();
        dataActions.add("hostAppDataAction", hostAppDataAction);
        response.getWriter().write(gson.toJson(dataActions));
      }
    
      /**
       * Handles an APP_COMMAND event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleAppCommand(JsonObject event) throws Exception {
        switch (event.getAsJsonObject("appCommandPayload")
          .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
          case ABOUT_COMMAND_ID:
            return new Message()
              .setText("The Avatar app replies to Google Chat messages.");
          default:
            return null;
        }
      }
    
      /**
       * Handles a MESSAGE event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleMessage(JsonObject event) throws Exception {
        // Stores the Google Chat user as a variable.
        JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
        String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
        return new Message()
          .setText("Here's your avatar")
          .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
              .setName("Avatar Card")
              .setHeader(new GoogleAppsCardV1CardHeader()
                .setTitle(String.format("Hello %s!", displayName)))
              .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
                  .setText("Your avatar picture:")),
                new GoogleAppsCardV1Widget()
                  .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
      }
    }
  5. pom.xml dosyasının içeriğini aşağıdaki kodla değiştirin:

    java/chat/avatar-app/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>com.google.chat</groupId>
      <artifactId>avatar-app</artifactId>
      <version>1.0-SNAPSHOT</version>
    
      <properties>
        <maven.compiler.target>17</maven.compiler.target>
        <maven.compiler.source>17</maven.compiler.source>
      </properties>
    
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>functions-framework-api</artifactId>
          <version>1.1.4</version>
        </dependency>
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.9.1</version>
        </dependency>
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-chat</artifactId>
          <version>v1-rev20230115-2.0.0</version>
        </dependency>
      </dependencies>
    
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
            <excludes>
              <exclude>.google/</exclude>
            </excludes>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </project>
    1. Kaydet ve yeniden dağıt'ı tıklayın.

Cloud Run hizmeti ayrıntıları sayfası açılır. İşlevin dağıtılmasını bekleyin.

Eklentiyi yapılandırma

Cloud Run işlevi dağıtıldıktan sonra eklenti oluşturmak ve Google Chat uygulamasını dağıtmak için aşağıdaki adımları uygulayın:

  1. Google Cloud Console'da Cloud Run sayfasına gidin:

    Cloud Run'a git

    Cloud Run'ı etkinleştirdiğiniz projenin seçildiğinden emin olun.

  2. İşlevler listesinde addonchatapp'i tıklayın.

  3. Hizmet ayrıntıları sayfasında, işlevin URL'sini kopyalayın. URL, run.app ile bitiyor.

  4. Google Cloud arama alanında "Google Chat API"yi arayın, ardından Google Chat API'yi ve Yönet'i tıklayın.

    Chat API'ye gitme

  5. Yapılandırma'yı tıklayın ve Google Chat uygulamasını ayarlayın:

    1. Uygulama adı alanına Add-on Chat app yazın.
    2. Avatar URL'si bölümüne https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png girin.
    3. Açıklama bölümüne Add-on Chat app girin.
    4. İşlevsellik bölümünde Alanlara ve grup görüşmelerine katılma'yı seçin.
    5. Bağlantı ayarları bölümünde HTTP uç nokta URL'si'ni seçin.
    6. Hizmet hesabı e-posta adresini kopyalayın. Eklentinizi işlevinizi çağırması için yetkilendirirken bu e-postaya ihtiyacınız vardır.
    7. Tetikleyiciler bölümünde Tüm tetikleyiciler için ortak bir HTTP uç noktası URL'si kullanın'ı seçin ve Cloud Run işlevi tetikleyicisinin URL'sini kutuya yapıştırın.
    8. Görünürlük bölümünde Bu Google Chat uygulamasını alanınızdaki belirli kişiler ve gruplar için kullanılabilir yapın'ı seçip e-posta adresinizi girin.
    9. Günlükler bölümünde Günlüğe kaydetme işlemine hata günlüğü ekle'yi seçin.
  6. Kaydet'i tıklayın.

Ardından, Chat uygulamasına Cloud Run işlevini çağırma yetkisi verin.

Google Chat'in işlevinizi çağırmasına izin verme

Google Workspace eklentisinin işlevinizi çağırmasına izin vermek için Cloud Run Hizmeti Çağırıcı rolüyle Google Workspace eklentisi hizmet hesabını ekleyin.

  1. Google Cloud Console'da Cloud Run sayfasına gidin:

    Cloud Run'a git

  2. Cloud Run hizmetleri listesinde, alıcı işlevin yanındaki onay kutusunu işaretleyin. (İşlevin kendisini tıklamayın.)

  3. İzinler'i tıklayın. İzinler paneli açılır.

  4. Ana hesap ekle'yi tıklayın.

  5. Yeni ana hesaplar bölümünde, Chat uygulamanızla ilişkili Google Workspace eklenti hizmeti hesabının e-posta adresini girin.

    Hizmet hesabı e-posta adresi, Chat API yapılandırma sayfasındaki Bağlantı ayarları > HTTP uç nokta URL'si > Hizmet Hesabı E-postası bölümünde yer alır:

    Chat API yapılandırmasına gitme

  6. Rol seçin bölümünde Cloud Run > Cloud Run Hizmeti Çağırıcı'yı seçin.

  7. Kaydet'i tıklayın.

Chat uygulaması, Chat'teki mesajları almaya ve yanıtlamaya hazırdır.

Chat uygulamanızı test etme

Chat uygulamanızı test etmek için Chat uygulamasıyla doğrudan mesajlaşma alanı açıp mesaj gönderin:

  1. Kendinizi güvenilir test kullanıcıları arasına eklerken sağladığınız Google Workspace hesabını kullanarak Google Chat'i açın.

    Google Chat'e gidin.

  2. Yeni sohbet'i tıklayın.
  3. 1 veya daha fazla kişi ekle alanına Chat uygulamanızın adını yazın.
  4. Sonuçlardan Chat uygulamanızı seçin. Doğrudan mesaj açılır.

  5. Uygulamayla yeni doğrudan mesajda Hello yazıp enter tuşuna basın.

Chat uygulamasının mesajında, gönderenin adını ve avatar resmini gösteren bir kart bulunur. Bu durum, aşağıdaki resimde gösterilmiştir:

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

Güvenilir test kullanıcıları ekleme ve etkileşimli özellikleri test etme hakkında daha fazla bilgi edinmek için Google Chat uygulamaları için etkileşimli özellikleri test etme 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.

Temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek istiyorsanız Cloud projesini silmenizi öneririz.

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin. Şunu tıklayın: Menü > IAM ve Yönetici > Kaynakları Yönetin.

    Resource Manager'a gidin

  2. Proje listesinde, silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.