Cloud Functions ile 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, Chat uygulamasının bir 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 Chat'i, aşağıdaki şemada gösterildiği gibi HTTP kullanarak Google Cloud veya şirket içi bir sunucu ile entegre olacak şekilde yapılandırırsınız:

Yukarıdaki şemada, HTTP Chat uygulamasıyla etkileşimde bulunan bir kullanıcı aşağıdaki bilgi akışına sahiptir:

1. Kullanıcı, Chat'te bir Chat uygulamasına doğrudan mesaj yoluyla veya bir Chat alanında mesaj gönderir.
2. Chat uygulaması mantığını içeren bulut veya şirket içi sistem olan bir web sunucusuna HTTP isteği gönderilir.
3. Chat uygulama 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 veya bilet işlemleri aracı) 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ı eşzamansız olarak mesaj yayınlamak veya diğer işlemleri gerçekleştirmek için Chat API'yi çağırabilir.

Chat uygulamaları farklı programlama dilleri kullanılarak tasarlanabildiği için bu mimari, sisteminizde zaten bulunan mevcut 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

• Bir Google Workspace kuruluşunda, kimliği doğrulanmamış Google Cloud Functions işlevi çağrılarına izin veren ve Google Chat'e erişimi olan bir Google Workspace hesabı.

• Bir Google Cloud projesi.
• Cloud projeniz için faturalandırmayı etkinleştirdiğinizden emin olun. Projelerinizin faturalandırma durumunu nasıl doğrulayacağınızı öğrenin.

Ortamı ayarlama

Google API'lerini kullanmadan önce bunları bir Google Cloud projesinde etkinleştirmeniz gerekir. Tek bir Google Cloud projesinde bir veya daha fazla API etkinleştirebilirsiniz.

• Google Cloud konsolunda 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 birlikte yanıt verir.

Chat uygulamanızda işlev oluşturmak ve dağıtmak için aşağıdaki adımları tamamlayın:

Node.js

1. Google Cloud konsolunda 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'da 2. nesil'i seçin.
   2. İşlev adı alanına QuickStartChatApp girin.
   3. Bölge'de bir bölge seçin.
   4. Kimlik Doğrulaması bölümünde, Kimliği doğrulanmayan çağrılara izin ver'i seçin.
   5. İleri'yi tıklayın.

4. Çalışma zamanı bölümünde Node.js 20'yi seçin.

5. Source code'da (Kaynak kodu) Satır içi Düzenleyici'yi seçin.

6. Giriş noktası bölümünde varsayılan metni silin ve helloChat değerini girin.

7. index.js alanının içeriğini şu kodla değiştirin:

   Node/avatar-app/index.js

   GitHub'da göster

   /**
    * Google Cloud Function that responds to messages sent from a
    * Google Chat room.
    *
    * @param {Object} req Request sent from Google Chat room
    * @param {Object} res Response to send back
    */
   exports.helloChat = function helloChat(req, res) {
     if (req.method === 'GET' || !req.body.message) {
       res.send('Hello! This function is meant to be used in a Google Chat ' +
         'Room.');
     }
   
     const sender = req.body.message.sender.displayName;
     const image = req.body.message.sender.avatarUrl;
   
     const data = createMessage(sender, image);
   
     res.send(data);
   };
   
   /**
    * Creates a card with two widgets.
    * @param {string} displayName the sender's display name
    * @param {string} imageUrl the URL for the sender's avatar
    * @return {Object} a card with the user's avatar.
    */
   function createMessage(displayName, imageUrl) {
     const cardHeader = {
       title: `Hello ${displayName}!`,
     };
   
     const avatarWidget = {
       textParagraph: {text: 'Your avatar picture: '},
     };
   
     const avatarImageWidget = {
       image: {imageUrl},
     };
   
     const avatarSection = {
       widgets: [
         avatarWidget,
         avatarImageWidget,
       ],
     };
   
     return {
       text: 'Here\'s your avatar',
       cardsV2: [{
         cardId: 'avatarCard',
         card: {
           name: 'Avatar Card',
           header: cardHeader,
           sections: [avatarSection],
         }
       }],
     };
   }

8. Deploy'u (Dağıt) tıklayın.

Python

1. Google Cloud konsolunda 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. İşlev adı alanına QuickStartChatApp girin.
   2. Tetikleyici türü'nde HTTP'yi seçin.
   3. Kimlik Doğrulaması bölümünde, Kimliği doğrulanmayan çağrılara izin ver'i seçin.
   4. Kaydet'i tıklayın.
   5. İleri'yi tıklayın.

4. Çalışma zamanı bölümünde Python 3.10'u seçin.

5. Source code'da (Kaynak kodu) Satır içi Düzenleyici'yi seçin.

6. Giriş noktası bölümünde varsayılan metni silin ve hello_chat değerini girin.

7. main.py alanının içeriğini şu kodla değiştirin:

   python/avatar-app/main.py

   GitHub'da göster

   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   
   # Google Cloud Function that responds to messages sent in
   # Google Chat.
   #
   # @param {Object} req Request sent from Google Chat.
   # @param {Object} res Response to send back.
   @functions_framework.http
   def hello_chat(req: flask.Request) -> Mapping[str, Any]:
     if req.method == "GET":
       return "Hello! This function must be called from Google Chat."
   
     request_json = req.get_json(silent=True)
   
     display_name = request_json["message"]["sender"]["displayName"]
     avatar = request_json["message"]["sender"]["avatarUrl"]
   
     response = create_message(name=display_name, image_url=avatar)
   
     return response
   
   
   # Creates a card with two widgets.
   # @param {string} name the sender's display name.
   # @param {string} image_url the URL for the sender's avatar.
   # @return {Object} a card with the user's avatar.
   def create_message(name: str, image_url: str) -> Mapping[str, Any]:
     avatar_image_widget = {"image": {"imageUrl": image_url}}
     avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
     avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}
   
     header = {"title": f"Hello {name}!"}
   
     cards = {
         "text": "Here's your avatar",
         "cardsV2": [
             {
                 "cardId": "avatarCard",
                 "card": {
                     "name": "Avatar Card",
                     "header": header,
                     "sections": [avatar_section],
                 },
             }
         ]
     }
   
     return cards

8. Deploy'u (Dağıt) tıklayın.

Java

1. Google Cloud konsolunda 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. İşlev adı alanına QuickStartChatApp girin.
   2. Tetikleyici türü'nde HTTP'yi seçin.
   3. Kimlik Doğrulaması bölümünde, Kimliği doğrulanmayan çağrılara izin ver'i seçin.
   4. Kaydet'i tıklayın.
   5. İleri'yi tıklayın.

4. Çalışma zamanı bölümünde Java 11'i seçin.

5. Source code'da (Kaynak kodu) Satır içi Düzenleyici'yi seçin.

6. Giriş noktası bölümünde varsayılan metni silin ve HelloChat değerini girin.

7. src/main/java/com/example/Example.java alanının adını src/main/java/HelloChat.java olarak değiştirin.

8. HelloChat.java alanının içeriğini şu kodla değiştirin:

   java/avatar-app/src/main/java/HelloChat.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.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 HelloChat 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("message")) {
         response.getWriter().write("Hello! This function must be called from Google Chat.");
         return;
       }
   
       JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
       String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
       String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
       Message message = createMessage(displayName, avatarUrl);
   
       response.getWriter().write(gson.toJson(message));
     }
   
     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("previewLink");
       cardWithId.setCard(card);
   
       Message message = new Message();
       message.setText("Here's your avatar");
       message.setCardsV2(List.of(cardWithId));
   
       return message;
     }
   }

9. pom.xml alanının içeriğini şu 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/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>cloudfunctions</groupId>
     <artifactId>http-function</artifactId>
     <version>1.0-SNAPSHOT</version>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <dependency>
         <groupId>com.google.cloud.functions</groupId>
         <artifactId>functions-framework-api</artifactId>
         <version>1.0.1</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 11 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. Deploy'u (Dağıt) tıklayın.

Cloud Functions ayrıntılar sayfası açılır ve işleviniz, biri derleme, diğeri hizmet için olmak üzere iki ilerleme göstergesiyle birlikte görünür. Her iki ilerleme göstergesi de kaybolup onay işaretiyle değiştirildiğinde işleviniz dağıtılmış ve hazır hale gelir.

Uygulamayı Google Chat'te yayınlama

Cloud Functions işlevi dağıtıldıktan sonra, Cloud Functions işlevini Google Chat uygulamasına dönüştürmek için şu adımları uygulayın:

1. Google Cloud konsolunda 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'nin altındaki URL'yi kopyalayın.

5. "Google Chat API" araması yapıp Google Chat API'yi, ardından Yönet'i tıklayın.

   Chat API'ye git

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'sine https://developers.google.com/chat/images/quickstart-app-avatar.png girin.
   3. Açıklama alanına Quickstart app girin.
   4. İşlevler bölümünde Bire bir mesaj al ve Alanlara ve grup görüşmelerine katıl'ı seçin.
   5. Bağlantı ayarları bölümünde Uygulama URL'si'ni seçin ve Cloud Functions işlevi tetikleyicisinin URL'sini kutuya yapıştırın.
   6. Görünürlük bölümünde, Bu Google Chat uygulamasını alanınızdaki belirli kişiler ve gruplar tarafından kullanılabilir yap'ı seçip e-posta adresinizi girin.
   7. Günlükler bölümünde Hataları Logging'e kaydet'i seçin.

7. Kaydet'i tıklayın.

Chat uygulaması, Chat'te mesaj almaya ve mesajları yanıtlamaya 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 bir 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 kişi ekle alanına Chat uygulamanızın adını yazın.

4. Sonuçlardan Chat uygulamanızı seçin. Bir doğrudan mesaj açılır.

   Not: Sonuçlar listesinde Chat uygulamanızı görmüyorsanız Google Workspace hesabınızı Google Cloud Console'da, 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ıp 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 sorun oluştu." veya "İsteğiniz işleme alınamıyor" mesajı gösterilir. 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ük kaydı etkinken hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri mevcuttur. Hataları görüntüleme, hata 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ğiticide kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız Cloud projesini silmenizi öneririz.

Dikkat: Projeyi silmenin etkileri aşağıdaki gibidir:

• Projedeki her şey silinir. Bu eğitim için mevcut bir projeyi kullandıysanız bu projeyi sildiğinizde projede yaptığınız diğer tüm çalışmaları da silmiş olursunuz.
• Özel proje kimlikleri kaybolur. Bu projeyi oluşturduğunuzda, ileride 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 projenin içindeki seçili kaynakları silin.

Birden fazla eğiticiyi ve hızlı başlangıç kılavuzunu incelemeyi planlıyorsanız projeleri yeniden kullanmak, proje kota sınırlarını aşmanızı önlemeye yardımcı olabilir.

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

   Resource Manager'a git

2. Proje listesinden silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
3. İletişim kutusuna proje kimliğini yazın, ardından projeyi silmek için 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ını yanıtlama
  • İletişim kutularını açma ve yanıtlama

• Chat uygulaması mimarisi seçme