HTTP Google Chat uygulaması oluşturma

Bu sayfada, HTTP Chat uygulamasının nasıl oluşturulacağı 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ıç kılavuzunda, Sohbet 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 mimaride, Chat'i aşağıdaki şemada gösterildiği gibi HTTP kullanarak Google Cloud veya şirket içi bir sunucuyla entegre edilecek şekilde yapılandırırsınız:

Önceki şemada, bir HTTP Chat uygulamasıyla etkileşimde bulunan kullanıcının aşağıdaki bilgi akışı vardır:

1. Kullanıcı, Chat'te bir Chat uygulamasına doğrudan mesaj veya Chat alanında 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 (Takvim ve E-Tablolar gibi), diğer Google hizmetleri (Haritalar, YouTube ve Vertex AI gibi) veya diğer web hizmetleri (proje yönetimi sistemi ya da destek kaydı aracı gibi) ile entegre edilebilir.
4. Web sunucusu, Chat'teki Chat uygulaması hizmetine bir HTTP yanıtı gönderir.
5. Yanıt kullanıcıya gönderilir.
6. İsteğe bağlı olarak Chat uygulaması, mesajları eşzamansız olarak yayınlamak veya başka işlemler yapmak için Chat API'yi çağırabilir.

Bu mimari, sohbet uygulamaları farklı programlama dilleri kullanılarak tasarlanabileceğinden, sisteminizde halihazırda bulunan kitaplıkları ve bileşenleri kullanma esnekliği sağlar.

Hedefler

• Ortamınızı ayarlayın.
• Cloud Functions işlevi oluşturup dağıtın.
• Uygulamayı Chat'te yayınlayın.
• Uygulamayı test edin.

Ön koşullar

• Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi. Mevcut bir projede faturalandırmanın etkin olup olmadığını kontrol etmek için Projelerinizin faturalandırma durumunu doğrulama başlıklı makaleyi inceleyin. Proje oluşturmak ve faturalandırmayı ayarlamak için Google Cloud projesi oluşturma başlıklı makaleyi inceleyin.

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 bir 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şlevi oluşturup dağıtmak üzere aşağıdaki adımları uygulayın:

Node.js

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

   Cloud Functions'a gidin

   Chat uygulamanızın projesinin seçili olduğundan emin olun.

2. İşlev Oluştur'u tıklayın.

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

   1. Ortam bölümünde Cloud Run İşlevi'ni seçin.
   2. İşlev adı alanına QuickStartChatApp yazın.
   3. Bölge'de bir bölge seçin.
   4. Kimlik doğrulama bölümünde Kimlik doğrulaması iste'yi seçin.
   5. İleri'yi tıklayın.

4. Çalışma zamanı bölümünde, Node.js'in en son sürümünü seçin.

5. Kaynak kod bölümünde Satır içi düzenleyici'yi seçin.

6. Giriş noktası alanında varsayılan metni silin ve avatarApp yazın.

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

   node/avatar-app/index.js

   GitHub'da göster
   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 gidin

   Chat uygulamanızın projesinin seçili olduğundan emin olun.

2. İşlev Oluştur'u tıklayın.

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

   1. Ortam bölümünde Cloud Run İşlevi'ni seçin.
   2. İşlev adı alanına QuickStartChatApp yazın.
   3. Bölge'de bir bölge seçin.
   4. Kimlik doğrulama bölümünde Kimlik doğrulaması iste'yi seçin.
   5. İleri'yi tıklayın.

4. Çalışma zamanı bölümünde, Python'ın en son sürümünü seçin.

5. Kaynak kod bölümünde Satır içi düzenleyici'yi seçin.

6. Giriş noktası alanında varsayılan metni silin ve avatar_app yazın.

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

   python/avatar-app/main.py

   GitHub'da göster
   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 gidin

   Chat uygulamanızın projesinin seçili olduğundan emin olun.

2. İşlev Oluştur'u tıklayın.

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

   1. Ortam bölümünde Cloud Run İşlevi'ni seçin.
   2. İşlev adı alanına QuickStartChatApp yazın.
   3. Bölge'de bir bölge seçin.
   4. Kimlik doğrulama bölümünde Kimlik doğrulaması iste'yi 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 kod bölümünde Satır içi düzenleyici'yi seçin.

6. Giriş noktası alanında varsayılan metni silin ve App yazın.

7. src/main/java/com/example/Example.java'ü src/main/java/AvatarApp.java olarak yeniden adlandırın.

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

   java/avatar-app/src/main/java/AvatarApp.java

   GitHub'da göster
   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 içeriğini aşağıdaki kodla değiştirin:

   java/avatar-app/pom.xml

   GitHub'da göster
   <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österilir: biri derleme, diğeri hizmet içindir. Her iki ilerleme göstergesi de kaybolup onay işaretiyle değiştirildiğinde işleviniz dağıtılmış ve kullanıma hazır olur.

İşlevinizi çağırması için Google Chat'e yetki verme

Google Chat'in işlevinizi çağırması için yetkilendirmek üzere Google Chat hizmet hesabını Cloud Run Çağırıcı rolüyle ekleyin.

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

   Cloud Run'a gidin

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 alanına [e-mail] girin.

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

7. Kaydet'i tıklayın.

Uygulamayı Google Chat'te yayınlama

Cloud işlevi dağıtıldıktan sonra 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 gidin

   Cloud Functions'ı etkinleştirdiğiniz projenin seçildiğinden 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 alanına https://developers.google.com/chat/images/quickstart-app-avatar.png yazın.
   3. Açıklama alanına Quickstart app yazın.
   4. İşlevsellik bölümünde 1:1 mesaj alma ve 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. Kimlik doğrulama kitlesi bölümünde HTTP uç noktası URL'si'ni seçin.
   7. Görünürlük bölümünde, alanınızda Bu Google Chat uygulamasını belirli kişilere ve gruplara sun'u seçin ve e-posta adresinizi girin.
   8. Günlükler bölümünde Günlüğe hata kaydet'i seçin.

7. Kaydet'i tıklayın.

Chat uygulaması, Chat'te mesaj almaya ve yanıt vermeye hazırdır.

Chat uygulamanızı test etme

Chat uygulamanızı test etmek için Chat uygulamasıyla bir doğrudan mesaj alanı açın ve mesaj gönderin:

1. Kendinizi güvenilir test kullanıcısı olarak 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 kullanıcı 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.

   Not: Chat uygulamanızı sonuç listesinde görmüyorsanız Google Workspace hesabınızı, Google Cloud Console'daki Chat API Yapılandırması sayfasının Görünürlük ayarlarına eklediğinizden emin olun.
5. Uygulamayla olan yeni doğrudan mesajda Hello yazın ve enter tuşuna basın.

Chat uygulamasının yanıtı, aşağıdaki resimde gösterildiği gibi gönderenin adını ve avatar resmini gösteren bir kart mesajı içerir:

Güvenilir test kullanıcıları eklemek 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ç verir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmeyebilir ancak Chat uygulamaları için hata günlüğü 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, hata ayıklama ve düzeltme hakkında yardım için Google Chat hatalarını giderme başlıklı makaleyi inceleyin.

Temizleme

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

Dikkat: Bir projenin silinmesinin sonuçları şunlardır:

• Projedeki her şey silinir. Bu eğitim için mevcut bir proje kullandıysanız projeyi sildiğinizde projede yaptığınız diğer çalışmaları da silersiniz.
• Özel proje kimlikleri kaybolur. Bu projeyi oluştururken gelecekte kullanmak istediğiniz özel bir proje kimliği oluşturmuş olabilirsiniz. Proje kimliğini kullanan URL'leri (ör. appspot.com'daki bir URL) korumak için projenin tamamını silmek yerine projedeki seçili kaynakları silin.

Birden fazla eğitim ve hızlı başlangıç kılavuzunu keşfetmeyi planlıyorsanız projeleri yeniden kullanmak, proje kotası sınırlarını aşmanızı önleyebilir.

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

   Resource Manager'a gidin

2. Proje listesinde, silmek istediğiniz projeyi seçin ve ardından Sil'i tıklayın.
3. Projeyi silmek için iletişim kutusuna proje kimliğini yazın ve ardından Kapat'ı tıklayın.

İlgili konular

• Chat uygulamanıza daha fazla özellik eklemek için aşağıdakileri inceleyin:

  • Etkileşimli kart mesajları oluşturma
  • Eğik çizgi komutlarına yanıt verme
  • İletişim kutularını açma ve yanıtlama

• Chat uygulaması mimarisi seçme

• Google Chat'ten gelen istekleri doğrulama