Bu sayfa, Cloud Translation API ile çevrilmiştir.

Google Chat uygulamanızla etkileşimleri alma ve yanıtlama

Bu sayfada, Google Chat uygulamanızın Google Chat uygulaması etkileşim etkinlikleri olarak da bilinen kullanıcı etkileşimlerini nasıl alıp yanıt verebileceği açıklanmaktadır.

Google Chat uygulaması etkileşim etkinliği, kullanıcının bir Chat uygulamasını çağırmak veya uygulamayla etkileşime girmek için gerçekleştirdiği herhangi bir işlemi (ör. bir Chat uygulamasından @bahsetmek veya uygulamayı bir alana eklemek) temsil eder. Kullanıcılar bir Chat uygulamasıyla etkileşimde bulunduğunda Google Chat, Chat uygulamasına bir etkileşim etkinliği gönderir. Chat uygulaması, etkileşimi işlemek ve bir yanıt oluşturmak için etkinliği kullanabilir.

Örneğin, Chat uygulamaları aşağıdakilerden herhangi birini yapmak için etkileşim etkinliklerini kullanır:

Etkileşim etkinliği örneği	Chat uygulamasından tipik yanıt
Kullanıcı bir Chat uygulamasından @bahsederek veya eğik çizgi komutu kullanarak uygulamayı çağırır.	Chat uygulaması, mesaj oluşturmak için mesajda belirtilenleri işler. Örneğin, bir Chat uygulaması, `/about` komutuna, Chat uygulamasının yapabileceği görevleri açıklayan bir mesajla yanıt verir.
Kullanıcı bir alana Chat uygulaması ekler.	Chat uygulaması, uygulamanın ne yaptığını ve alandaki kullanıcıların uygulamayla nasıl etkileşim kurabileceğini açıklayan bir ilk katılım mesajı gönderir.
Kullanıcı, alandan Chat uygulamasını kaldırır.	Chat uygulaması, alan için yapılandırılmış tüm gelen bildirimleri kaldırır (ör. webhook'u silme) ve dahili depolama alanını temizler.
Kullanıcı, Chat uygulaması tarafından gönderilen bir karttaki veya iletişim kutusundaki bir düğmeyi tıklar.	Chat uygulaması, kullanıcının gönderdiği tüm verileri işleyip depolar veya başka bir kart ya da iletişim kutusu döndürür.

Google Chat, her kullanıcı etkileşimi türü için farklı türde bir etkileşim etkinliği gönderir. Örneğin, Google Chat, kullanıcının bir mesajda Chat uygulamasını çağırdığı her etkileşim için MESSAGE etkinlik türünü kullanır. Ayrıntılı bilgi için Google Chat uygulaması etkileşim etkinliklerinin türleri başlıklı makaleyi inceleyin.

Bu sayfada, aşağıdakilerin nasıl yapılacağı açıklanmaktadır:

Chat uygulamanızı etkinlikleri alacak şekilde yapılandırın.
Etkileşim etkinliğini altyapınızda işleyin.
Uygunsa etkileşim etkinliklerine yanıt verin.

Chat uygulamasıyla etkileşim etkinliklerini alma

Bu bölümde, Chat uygulamanız için etkileşim etkinliklerini nasıl alacağınız ve işleyebileceğiniz açıklanmaktadır.

Chat uygulamanızı etkileşim etkinliklerini alacak şekilde yapılandırma

Bazı Chat uygulamaları etkileşimli değildir. Örneğin, gelen webhook'lar yalnızca giden mesajlar gönderebilir ve kullanıcılara yanıt veremez. Etkileşimli bir Chat uygulaması oluşturuyorsanız Chat uygulamanızın etkileşim etkinliklerini almasına, işlemesine ve yanıt vermesine olanak tanıyan bir uç nokta seçmeniz gerekir. Chat uygulamanızı tasarlama hakkında daha fazla bilgi edinmek için Chat uygulamaları uygulama mimarileri başlıklı makaleyi inceleyin.

Etkileşimli bir Chat uygulaması oluşturduysanız Google Chat'in etkileşim etkinlikleri gönderebilmesi için Google Chat API'yi yapılandırmanız gerekir:

Google Cloud konsolunda Google Chat API sayfasını açın:
Google Chat API sayfasına gidin
Yapılandırma sekmesini tıklayın.
Etkileşimli özellikler bölümünde, Etkileşimli özellikleri etkinleştir düğmesini tıklayarak açık konuma getirin.
İşlevsellik bölümünde, aşağıdaki onay kutularının birini veya ikisini birden seçin:
1. Bire bir mesajlar alma: Kullanıcıların doğrudan mesaj (DM) alanlarında Chat uygulamanızla etkileşim kurmasına olanak tanır. Bir kullanıcı DM alanında her mesaj gönderdiğinde Chat uygulamanız etkileşim etkinliklerini alır.
2. Alanlara ve grup görüşmelerine katılma: Kullanıcıların birden fazla kişinin bulunduğu alanlara Chat uygulamanızı eklemesine ve kaldırmasına olanak tanır. Chat uygulamanız, alana eklendiğinde veya alandan kaldırıldığında ve kullanıcılar alanda eğik çizgiden @bahsedildiğinde ya da eğik çizgi komutu kullandığında etkileşim etkinliklerini alır.
Bağlantı ayarları bölümünde, Google Chat'in Chat uygulaması etkileşim etkinliklerini nereye göndereceğini belirleyin.
İsteğe bağlı: Eğik çizgi komutları bölümünde, bir veya daha fazla eğik çizgi komutu ekleyip yapılandırın. Daha fazla bilgi için Eğik çizgi komutu ayarlama bölümüne bakın.
İsteğe bağlı: Bağlantı önizlemeleri bölümünde Chat uygulamanızın önizlediği bir veya daha fazla URL kalıbı ekleyin ve yapılandırın. Daha fazla bilgi için Önizleme bağlantıları bölümünü inceleyin.
Kaydet'i tıklayın.

Chat uygulamanız artık Google Chat'ten etkileşim etkinliklerini alacak şekilde yapılandırılmıştır.

Google Chat'ten gelen isteklerin kimliğini doğrulama

HTTP uç noktalarında oluşturulan uygulamalar için bu bölümde, uç noktanıza gelen isteklerin Google Chat'ten geldiğini nasıl doğrulayacağınız açıklanmaktadır.

Google, etkileşim etkinliklerini Chat uygulamanızın uç noktasına dağıtmak için hizmetinize istek gönderir. Google Chat, isteğin Google'dan geldiğini doğrulamak için uç noktanıza gönderilen her HTTPS isteğinin Authorization başlığına bir hamiline ait jeton ekler. Örneğin:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

Yukarıdaki örnekte bulunan AbCdEf123456 dizesi, hamiline ait yetkilendirme jetonudur. Bu, Google tarafından üretilen bir kriptografik jetondur. Açık kaynaklı bir Google API istemci kitaplığı kullanarak hamiline ait jetonunuzu doğrulayabilirsiniz:

Java: https://github.com/google/google-api-java-client
Python: https://github.com/google/google-api-python-client
.NET: https://github.com/google/google-api-dotnet-client

Google Chat isteklerinde gönderilen hamiline ait jetonları veren chat@system.gserviceaccount.com, audience alanı ise Chat uygulamanızı oluşturmak için kullandığınız Google Cloud projesinin numarası olarak ayarlanır. Örneğin, Chat uygulamanızın Cloud proje numarası 1234567890 ise hamiline ait jetondaki audience alanı 1234567890 olur.

Jeton Chat uygulaması için doğrulanmazsa hizmetiniz 401 (Unauthorized) HTTPS yanıt koduyla isteğe yanıt vermelidir.

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Hizmetinize yapılan HTTP çağrısı yeniden denemelerini yönetme

Hizmetinize yönelik bir HTTPS isteği başarısız olursa (zaman aşımı, geçici ağ hatası veya 2xx olmayan HTTPS durum kodu gibi) Google Chat birkaç dakika içinde yayınlamayı birkaç kez yeniden deneyebilir (ancak bu garanti edilmez). Sonuç olarak, Chat uygulaması belirli durumlarda aynı mesajı birkaç kez alabilir. İstek başarıyla tamamlanır ancak geçersiz bir mesaj yükü döndürürse Google Chat isteği yeniden denemez.

Etkileşim etkinliklerini işleme veya yanıtlama

Bu bölümde, Google Chat uygulamalarının etkileşim etkinliklerini nasıl işleyip yanıt verebileceği açıklanmaktadır.

Chat uygulamanız Google Chat'ten bir etkileşim etkinliği aldıktan sonra, uygulamanız farklı şekillerde yanıt verebilir. Etkileşimli Chat uygulamaları çoğu durumda kullanıcıya bir mesajla yanıt verir. Google Chat uygulaması ayrıca bir veri kaynağından bazı bilgileri arayabilir, etkileşim etkinliği bilgilerini kaydedebilir veya başka herhangi bir şeyi yapabilir. Bu işleme davranışı temelde Google Chat uygulamasını tanımlar.

Her etkileşim etkinliği için Chat uygulamaları bir istek gövdesi alır. Bu, etkinliği temsil eden JSON yüküdür. Yanıtı işlemek için bu bilgileri kullanabilirsiniz. Etkinlik yükü örnekleri için Chat uygulaması etkileşim etkinliklerinin türleri bölümüne bakın.

Aşağıdaki şemada, Google Chat uygulamasının farklı etkileşim etkinliklerini genellikle nasıl işlediği veya yanıtladığı gösterilmektedir:

Google Chat uygulamalarının etkileşim etkinliklerini işleme biçiminin mimarisi.

Gerçek zamanlı olarak yanıt verin

Etkileşim etkinlikleri, Chat uygulamalarının gerçek zamanlı veya eşzamanlı olarak yanıt vermesine olanak tanır. Eşzamanlı yanıtlar için kimlik doğrulama gerekmez.

Etkileşim etkinliklerine eşzamanlı yanıtlar oluşturmak için aşağıdaki kılavuzlara bakın:

Eşzamanlı yanıt vermek için Chat uygulamasının 30 saniye içinde yanıt vermesi ve yanıtın, etkileşimin gerçekleştiği alanda yayınlanması gerekir. Aksi takdirde Chat uygulaması eşzamansız olarak yanıt verebilir.

Eşzamansız olarak yanıt ver

Chat uygulamalarının bazen bir etkileşim etkinliğine 30 saniye sonra yanıt vermesi veya etkileşim etkinliğinin oluşturulduğu alanın dışında görev gerçekleştirmesi gerekir. Örneğin, bir Chat uygulamasının uzun süreli bir görevi tamamladıktan sonra kullanıcıya yanıt vermesi gerekebilir. Bu durumda Chat uygulamaları, Google Chat API'yi çağırarak eşzamansız olarak yanıt verebilir.

Chat API'yi kullanarak mesaj oluşturmak için Mesaj oluşturma başlıklı makaleyi inceleyin. Diğer Chat API yöntemlerinin kullanımıyla ilgili kılavuzlar için Chat API'ye genel bakış sayfasını inceleyin.