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.

Not: Google Chat'te eklentiler, kullanıcılara Google Chat uygulamaları olarak gösterilir. Chat uygulamanızı Google Chat API etkileşim etkinliklerini kullanarak da oluşturabilirsiniz. Daha fazla bilgi edinmek için Google Chat'i genişletmeye genel bakış 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. 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 sunucuyla entegre olacak şekilde yapılandırırsınız:

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 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

• 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 etkinleştirildiğini kontrol etmek için Projelerinizin faturalandırma durumunu doğrulama bölümüne bakın. Proje oluşturma ve faturalandırmayı ayarlama hakkında bilgi edinmek 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 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 gitme

   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:

   /**
    * Google Cloud Run 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
    */
   import { http } from '@google-cloud/functions-framework';
   
   http('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 }
                       }]
                   }]
               }
           }]
       }}}}});
   });
   

   1. package.json dosyasının içeriğini aşağıdaki kodla değiştirin:

   {
     "name": "avatar-app",
     "version": "1.0.0",
     "description": "Google Chat Avatar App",
     "main": "index.js",
     "type": "module",
     "scripts": {
       "start": "node index.js"
     },
     "dependencies": {
       "@google-cloud/functions-framework": "^3.0.0"
     }
   }
   

   1. Kaydet ve yeniden dağıt'ı tıklayın.

Python

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

   Cloud Run'a gitme

   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:

   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   @functions_framework.http
   def avatar_app(req: flask.Request) -> Mapping[str, Any]:
       """Google Cloud Run 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 }
                       }]
                   }]
               }
           }]
       }}}}}
   

   1. Kaydet ve yeniden dağıt'ı tıklayın.

Java

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

   Cloud Run'a gitme

   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 AvatarApp değerini girin.
   2. Varsayılan Java dosyasını src/main/java/gcfv2/AvatarApp.java olarak yeniden adlandırın.
   3. AvatarApp.java dosyasının 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;
       }
   }
   

5. pom.xml dosyasının 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>
   

   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 gitme

   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ğırmaya 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, 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.
   9. Günlükler bölümünde Günlük hatalarını Logging'e seçeneğini belirleyin.

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 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ü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.

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

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

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.

Dikkat: Bir projenin silinmesinin etkileri ş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 tüm çalışmalar da silinir.
• Ö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 proje içindeki seçili kaynakları silin.

Birden fazla eğiticiden ve hızlı başlangıç kılavuzundan yararlanmayı planlıyorsanız projeleri yeniden kullanarak proje kotası sınırlarını aşmaktan kaçınabilirsiniz.

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.