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. Google Chat'te eklentiler kullanıcılara Google Chat uygulamaları olarak görünür. Daha fazla bilgi edinmek için Google Chat'i genişletme başlıklı makaleyi inceleyin.

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

HTTP mimarisinde, Chat'i aşağıdaki şemada gösterildiği gibi HTTP kullanarak Google Cloud veya şirket içi bir sunucuyla entegre olacak ş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 iletilir.
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.
• Chat uygulaması için bir Google Workspace eklentisi yapılandırı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.

  Google Workspace Add-ons API'yi de etkinleştirmeniz gerekir ancak Chat uygulaması dağıtımlarını oluşturmak ve yönetmek için bu API'yi kullanamazsınız. Ayrıntılar için Sınırlılıklar ve bilinen sorunlar bölümüne bakın.

  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. Create Function'ı (İşlev Oluştur) 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 AddOnChatApp 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ındaki varsayılan metni silin ve avatarApp yazın.

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

   /**
    * Google Cloud Function that responds to messages sent from a
    * Google Chat space.
    *
    * @param {Object} req Request sent from Google Chat space
    * @param {Object} res Response to send back
    */
   exports.avatarApp = function avatarApp(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 as a variable.
       const chatMessage = req.body.chat.messagePayload.message;
   
       // Replies with the sender's avatar in a card.
       const displayName = chatMessage.sender.displayName;
       const avatarUrl = chatMessage.sender.avatarUrl;
       res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
           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. Create Function'ı (İşlev Oluştur) 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 AddOnChatApp 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:

   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   @functions_framework.http
   def avatar_app(req: flask.Request) -> Mapping[str, Any]:
       """Google Cloud Function that handles requests from Google Chat
   
       Args:
           flask.Request: the request
   
       Returns:
           Mapping[str, Any]: the response
       """
       if req.method == "GET":
           return "Hello! This function must be called from Google Chat."
   
       request_json = req.get_json(silent=True)
   
       # Stores the Google Chat event as a variable.
       chat_message = request_json["chat"]["messagePayload"]["message"]
   
       # Replies with the sender's avatar in a card.
       display_name = chat_message["sender"]["displayName"]
       avatar_url = chat_message["sender"]["avatarUrl"]
       return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
           "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. Create Function'ı (İşlev Oluştur) 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 AddOnChatApp 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ındaki varsayılan metni silin ve AvatarApp yazın.

7. Varsayılan Java dosyasını src/main/java/AvatarApp.java olarak yeniden adlandırın.

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

   import java.util.List;
   
   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;
   
   public class AvatarApp implements HttpFunction {
       private static final Gson gson = new Gson();
   
       @Override
       public void service(HttpRequest request, HttpResponse response) throws Exception {
           JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
           if (request.getMethod().equals("GET") || !body.has("chat")) {
               response.getWriter().write("Hello! This function is meant to be used " +
                   "in a Google Chat Space..");
               return;
           }
   
           // Stores the Google Chat event as a variable.
           JsonObject chatMessage = body.getAsJsonObject("chat")
               .getAsJsonObject("messagePayload").getAsJsonObject("message");
   
           // Replies with the sender's avatar in a card.
           String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString();
           String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString();
           Message message = createMessage(displayName, avatarUrl);
   
           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));
       }
   
       Message createMessage(String displayName, String avatarUrl) {
           GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
           cardHeader.setTitle(String.format("Hello %s!", displayName));
   
           GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
           textParagraph.setText("Your avatar picture: ");
   
           GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
           avatarWidget.setTextParagraph(textParagraph);
   
           GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
           image.setImageUrl(avatarUrl);
   
           GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
           avatarImageWidget.setImage(image);
   
           GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
           section.setWidgets(List.of(avatarWidget, avatarImageWidget));
   
           GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
           card.setName("Avatar Card");
           card.setHeader(cardHeader);
           card.setSections(List.of(section));
   
           CardWithId cardWithId = new CardWithId();
           cardWithId.setCardId("avatarCard");
           cardWithId.setCard(card);
   
           Message message = new Message();
           message.setText("Here's your avatar");
           message.setCardsV2(List.of(cardWithId));
   
           return message;
       }
   }
   

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

   <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.0.4</version>
           </dependency>
   
           <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
           <dependency>
               <groupId>com.google.code.gson</groupId>
               <artifactId>gson</artifactId>
               <version>2.9.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-rev20230115-2.0.0</version>
           </dependency>
       </dependencies>
   
       <!-- Required for Java functions in the inline editor -->
       <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>
   

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 Workspace eklentisinin işlevinizi çağırması için yetkilendirmek üzere Google Workspace eklenti 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 yöneticiler bölümünde, projenizle ilişkili Google Workspace eklenti hizmet hesabının e-posta adresini 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.

Eklentiyi yapılandırma

Cloud Functions 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 Menü > Cloud Functions'ı tıklayın.

   Cloud Functions'a gidin

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

2. İşlev listesinde AddOnChatApp'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 Add-on Chat 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 Add-on Chat 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 eklediğinizde 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 mesaja Hello yazın ve enter tuşuna basın.

Chat uygulamasının mesaj bölümünde, gönderenin adını ve avatar resmini gösteren bir kart bulunur. Aşağıdaki resimde bu kart gösterilmektedir:

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 projeyi silmenin 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. İletişim kutusuna proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.