HTTP Google Chat uygulaması oluşturma

Bu sayfada, HTTP Chat uygulaması oluşturma açıklanmaktadır. Bu mimariyi uygulamanın farklı yolları vardır. Google Cloud'da Cloud Functions, Cloud Run ve App Engine'i kullanabilirsiniz. Bu hızlı başlangıçta, Chat uygulamasının kullanıcının mesajına yanıt vermek için kullandığı bir Cloud Functions işlevi yazıp dağıtacaksınız.

Bu mimariyle, 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ırabilirsiniz:

Ş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. Bir kullanıcı, Chat'te doğrudan mesaj veya Chat alanı üzerinden bir Chat uygulamasına mesaj gönderir.
  2. Chat uygulaması mantığını içeren bir bulut veya şirket içi sistem olan bir web sunucusuna HTTP isteği gönderilir.
  3. İsteğe bağlı olarak, Chat uygulaması mantığı Google Workspace hizmetleri (ör. Takvim ve E-Tablolar), diğer Google hizmetleri (ö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 Functions işlevi oluşturma ve dağıtma
  • Uygulamayı Chat'te yayınlayı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 Google Chat API, 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 Functions işlevi oluşturma ve dağıtma

Gönderenin görünen adını ve avatar resmini içeren bir Chat kartı oluşturan Cloud Functions işlevi oluşturup dağıtın. 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 Functions sayfasına gidin:

    Cloud Functions'a gitme

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

  2. Create Function'ı (İşlev oluştur) tıklayın.

  3. İşlev oluşturma sayfasında işlevinizi ayarlayın:

    1. Ortam'da Cloud Run işlevi'ni seçin.
    2. İşlev adı alanına QuickStartChatApp girin.
    3. Bölge'de bir bölge seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. İleri'yi tıklayın.
  4. Çalışma zamanı bölümünde Node.js'nin en son sürümünü seçin.

  5. Kaynak kodu bölümünde Satır İçi Düzenleyici'yi seçin.

  6. Giriş noktası bölümünde varsayılan metni silip avatarApp değerini girin.

  7. index.js dosyasının içeriğini aşağıdaki kodla değiştirin:

    node/avatar-app/index.js
    const functions = require('@google-cloud/functions-framework');
    
    // Command IDs (configure these in Google Chat API)
    const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
    const HELP_COMMAND_ID = 2; // ID for the "Help" quick command
    
    /**
     * Google Cloud Function that handles HTTP requests from Google Chat.
     *
     * @param {Object} req - The HTTP request object sent from Google Chat.
     * @param {Object} res - The HTTP response object.
     */
    functions.http('avatarApp', (req, res) => {
      const event = req.body;
    
      if (event.appCommandMetadata) {
        handleAppCommands(event, res);
      } else {
        handleRegularMessage(event, res);
      }
    });
    
    /**
     * Handles slash and quick commands.
     *
     * @param {Object} event - The Google Chat event.
     * @param {Object} res - The HTTP response object.
     */
    function handleAppCommands(event, res) {
      const {appCommandId, appCommandType} = event.appCommandMetadata;
    
      switch (appCommandId) {
        case ABOUT_COMMAND_ID:
          return res.send({
            privateMessageViewer: event.user,
            text: 'The Avatar app replies to Google Chat messages.'
          });
        case HELP_COMMAND_ID:
          return res.send({
            privateMessageViewer: event.user,
            text: 'The Avatar app replies to Google Chat messages.'
          });
      }
    }
    
    /**
     * Handles regular messages (not commands).
     *
     * @param {Object} event - The Google Chat event.
     * @param {Object} res - The HTTP response object.
     */
    function handleRegularMessage(event, res) {
      const messageData = createMessage(event.user);
      res.send(messageData);
    }
    
    /**
     * Creates a card message with the user's avatar.
     *
     * @param {Object} user - The user who sent the message.
     * @param {string} user.displayName - The user's display name.
     * @param {string} user.avatarUrl - The URL of the user's avatar.
     * @return {Object} - The card message object.
     */
    function createMessage({displayName, 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}},
              ],
            }],
          },
        }],
      };
    }

  8. Dağıt'ı tıklayın.

Python

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

    Cloud Functions'a gitme

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

  2. Create Function'ı (İşlev oluştur) tıklayın.

  3. İşlev oluşturma sayfasında işlevinizi ayarlayın:

    1. Ortam'da Cloud Run işlevi'ni seçin.
    2. İşlev adı alanına QuickStartChatApp girin.
    3. Bölge'de bir bölge seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. İleri'yi tıklayın.
  4. Çalışma zamanı bölümünde en son Python sürümünü seçin.

  5. Kaynak kodu bölümünde Satır İçi Düzenleyici'yi seçin.

  6. Giriş noktası bölümünde varsayılan metni silip avatar_app değerini girin.

  7. main.py dosyasının içeriğini aşağıdaki kodla değiştirin:

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # Command IDs (configure these in Google Chat API)
    ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
    HELP_COMMAND_ID = 2  # ID for the "Help" quick command
    
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
        """Google Cloud Function that handles HTTP requests from Google Chat.
    
        Args:
            flask.Request: the request
    
        Returns:
            Mapping[str, Any]: the response
        """
        event = req.get_json(silent=True)
    
        if event and "appCommandMetadata" in event:
            return handle_app_commands(event)
        else:
            return handle_regular_message(event)
    
    
    def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
        """Handles slash and quick commands.
    
        Args:
            Mapping[str, Any] event: The Google Chat event.
    
        Returns:
            Mapping[str, Any]: the response
        """
        app_command_id = event["appCommandMetadata"]["appCommandId"]
    
        if app_command_id == ABOUT_COMMAND_ID:
            return {
                "privateMessageViewer": event["user"],
                "text": "The Avatar app replies to Google Chat messages.",
            }
        elif app_command_id == HELP_COMMAND_ID:
            return {
                "privateMessageViewer": event["user"],
                "text": "The Avatar app replies to Google Chat messages.",
            }
        return {}
    
    
    
    
    def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
        """Handles regular messages (not commands).
    
        Args:
            Mapping[str, Any] event: The Google Chat event.
    
        Returns:
            Mapping[str, Any]: the response
        """
    
        if not event or "user" not in event:
            return "Invalid request."
    
        message_data = create_message(event["user"])
        return message_data
    
    
    def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
        """Creates a card message with the user's avatar.
    
        Args:
            Mapping[str, Any] user: The user who sent the message.
    
        Returns:
            Mapping[str, Any]: a card with the user's avatar.
        """
        display_name = user.get("displayName", "")
        avatar_url = 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}},
                                ]
                            }
                        ],
                    },
                }
            ],
        }

  8. Dağıt'ı tıklayın.

Java

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

    Cloud Functions'a gitme

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

  2. Create Function'ı (İşlev oluştur) tıklayın.

  3. İşlev oluşturma sayfasında işlevinizi ayarlayın:

    1. Ortam'da Cloud Run işlevi'ni seçin.
    2. İşlev adı alanına QuickStartChatApp girin.
    3. Bölge'de bir bölge seçin.
    4. Kimlik Doğrulama bölümünde Kimlik doğrulama gerektir'i seçin.
    5. İleri'yi tıklayın.
  4. Çalışma zamanı bölümünde Java'nın en son sürümünü seçin.

  5. Kaynak kodu bölümünde Satır İçi Düzenleyici'yi seçin.

  6. Giriş noktası bölümünde varsayılan metni silip App değerini girin.

  7. src/main/java/com/example/Example.java öğesini src/main/java/AvatarApp.java olarak yeniden adlandırın.

  8. AvatarApp.java dosyasının içeriğini aşağıdaki kodla değiştirin:

    java/avatar-app/src/main/java/AvatarApp.java
    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.api.services.chat.v1.model.User;
    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 AvatarApp implements HttpFunction {
      private static final Gson gson = new Gson();
    
      // Command IDs (configure these in Google Chat API)
      private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
      private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command
    
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    
        if (event.has("appCommandMetadata")) {
          handleAppCommands(event, response);
        } else {
          handleRegularMessage(event, response);
        }
      }
    
      /**
       * Handles slash and quick commands.
       *
       * @param event    The Google Chat event.
       * @param response The HTTP response object.
       */
      private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
        int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();
    
        switch (appCommandId) {
          case ABOUT_COMMAND_ID:
            Message aboutMessage = new Message();
            aboutMessage.setText("The Avatar app replies to Google Chat messages.");
            aboutMessage.setPrivateMessageViewer(new User()
                .setName(event.getAsJsonObject("user").get("name").getAsString()));
            response.getWriter().write(gson.toJson(aboutMessage));
            return;
          case HELP_COMMAND_ID:
            Message helpMessage = new Message();
            helpMessage.setText("The Avatar app replies to Google Chat messages.");
            helpMessage.setPrivateMessageViewer(new User()
                .setName(event.getAsJsonObject("user").get("name").getAsString()));
            response.getWriter().write(gson.toJson(helpMessage));
            return;
        }
      }
    
      /**
       * Handles regular messages (not commands).
       *
       * @param event    The Google Chat event.
       * @param response The HTTP response object.
       */
      private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {
    
        if (!event.has("user")) {
          response.getWriter().write("Invalid request.");
          return;
        }
    
        JsonObject user = event.getAsJsonObject("user");
        String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
        String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
        Message message = createMessage(displayName, avatarUrl);
        response.getWriter().write(gson.toJson(message));
      }
    
      /**
       * Creates a card message with the user's avatar.
       *
       * @param displayName The user's display name.
       * @param avatarUrl   The URL of the user's avatar.
       * @return The card message object.
       */
      private Message createMessage(String displayName, String avatarUrl) {
        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)))))))));
      }
    }

  9. pom.xml dosyasının içeriğini aşağıdaki kodla değiştirin:

    java/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/maven-v4_0_0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>gcfv2</groupId>
      <artifactId>avatar-app</artifactId>
      <version>0.0.1</version>
      <name>Avatar App</name>
    
      <properties>
        <maven.compiler.release>21</maven.compiler.release>
      </properties>
    
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>functions-framework-api</artifactId>
          <version>1.1.4</version>
        </dependency>
    
        <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.12.1</version>
        </dependency>
    
        <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-chat</artifactId>
          <version>v1-rev20250116-2.0.0</version>
        </dependency>
    
      </dependencies>
    
    </project>

  10. Dağıt'ı tıklayın.

Cloud Functions ayrıntılar sayfası açılır ve işleviniz iki ilerleme göstergesiyle birlikte görünür: biri derleme, diğeri ise hizmet için. Her iki ilerleme göstergesi de kaybolup yerini onay işaretine bıraktığında işleviniz dağıtılmış ve hazır demektir.

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

Google Chat'in işlevinizi çağırmasına izin vermek için Google Chat hizmet hesabını Cloud Run Invoker rolüyle ekleyin.

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

    Cloud Run'a gitme

  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üne chat@system.gserviceaccount.com girin.

  6. Rol seçin bölümünde Cloud Run > Cloud Run Invoker'ı seçin.

  7. Kaydet'i tıklayın.

Uygulamayı Google Chat'te yayınlama

Cloud Function dağıtıldıktan sonra, bunu Google Chat uygulamasına dönüştürmek için aşağıdaki adımları uygulayın:

  1. Google Cloud Console'da Menü > Cloud Functions'ı tıklayın.

    Cloud Functions'a gitme

    Cloud Functions'ı etkinleştirdiğiniz projenin seçili olduğundan emin olun.

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

  3. Tetikleyiciler sekmesini tıklayın.

  4. HTTPS bölümünde URL'yi kopyalayın.

  5. "Google Chat API"yi arayın ve Google Chat API'yi, ardından Yönet'i tıklayın.

    Chat API'ye gitme

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

    1. Uygulama adı alanına Quickstart App yazın.
    2. Avatar URL'si bölümüne https://developers.google.com/chat/images/quickstart-app-avatar.png girin.
    3. Açıklama bölümüne Quickstart 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ç noktası URL'si'ni seçin ve Cloud Function tetikleyicisinin URL'sini kutuya yapıştırın.
    6. Authentication Audience (Kimlik Doğrulama Kitlesi) bölümünde HTTP endpoint URL'yi (HTTP uç noktası URL'si) seçin.
    7. Görünürlük bölümünde, alanınızdaki Bu Google Chat uygulamasını belirli kişilerin ve grupların kullanımına sun'u seçip e-posta adresinizi girin.
    8. Günlükler bölümünde Günlük hatalarını Logging'e seçeneğini belirleyin.
  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 yanıtında, aşağıdaki resimde gösterildiği gibi gönderenin adını ve avatar resmini gösteren bir kart mesajı yer alır:

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 gitme

  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 ardından projeyi silmek için Kapat'ı tıklayın.