Chat uygulamaları ve Google Chat API isteklerinin kimliğini doğrulama ve yetkilendirme

Kimlik doğrulama ve yetkilendirme, sırasıyla kimliği ve kaynaklara erişimi doğrulamak için kullanılan mekanizmalardır. Bu dokümanda, Chat uygulamaları ve Chat API istekleri için kimlik doğrulama ve yetkilendirmenin işleyiş şekli açıklanmaktadır.

Sürece genel bakış

Aşağıdaki şemada, Google Chat için üst düzey kimlik doğrulama ve yetkilendirme adımları gösterilmektedir:

Google Chat kimlik doğrulama ve yetkilendirme için üst düzey adımlar
Şekil 1. Google Chat'te kimlik doğrulama ve yetkilendirme için üst düzey adımlar.

  1. Bir Google Cloud projesi yapılandırın, Chat API'yi etkinleştirin ve Chat uygulamanızı yapılandırın: Geliştirme sırasında bir Google Cloud projesi oluşturursunuz. Google Cloud projesinde Chat API'yi etkinleştirir, Chat uygulamanızı yapılandırır ve kimlik doğrulamasını ayarlarsınız. Daha fazla bilgi için Google Workspace'te uygulama geliştirme ve Chat uygulaması oluşturma bölümlerine göz atın.

  2. Chat API'yi çağırma: Uygulamanız Chat API'yi çağırdığında Chat API'ye kimlik doğrulama bilgileri gönderir. Uygulamanız bir hizmet hesabıyla kimlik doğrulaması yaparsa kimlik bilgileri, uygulama kodunuzun bir parçası olarak gönderilir. Uygulamanız, henüz verilmemiş bir kullanıcı kimlik doğrulaması kullanılarak Chat API'nin çağrılmasını gerektiriyorsa kullanıcıdan oturum açmasını ister.

  3. Kaynak isteme: Uygulamanız, kimlik doğrulamayı ayarlarken belirttiğiniz kapsamlar ile erişim ister.

  4. İzin isteme: Uygulamanız, kullanıcı olarak kimlik doğrulaması yapıyorsa Google bir OAuth izin ekranı görüntüler. Böylece kullanıcı, uygulamanıza istenen verilere erişim izni verip vermemeye karar verebilir. Hizmet hesabıyla kimlik doğrulamak için kullanıcı izni gerekmez.

  5. Kaynaklar için onaylanan istek gönderme: Kullanıcı, yetkilendirme kapsamlarına izin verirse uygulamanız kimlik bilgilerini ve kullanıcı tarafından onaylanan kapsamları bir talep altında birleştirir. İstek, erişim jetonunu almak için Google yetkilendirme sunucusuna gönderilir.

  6. Google bir erişim jetonu döndürür: Erişim jetonu, verilen kapsamların bir listesini içerir. Döndürülen kapsam listesi istenen kapsamlardan daha kısıtlayıcıysa uygulamanız jeton tarafından sınırlandırılan tüm özellikleri kapatır.

  7. İstenen kaynaklara erişim: Uygulamanız, Chat API'yi çağırmak ve Chat API kaynaklarına erişmek için Google'ın erişim jetonunu kullanır.

  8. Yenileme jetonu alma (isteğe bağlı): Uygulamanızın Google Chat API'ye tek bir erişim jetonunun kullanım ömründen sonra erişmesi gerekiyorsa yenileme jetonu alabilir. Daha fazla bilgi için Google API'lerine erişmek için OAuth 2.0'ı kullanma bölümüne bakın.

  9. Daha fazla kaynak isteme: Uygulamanız daha fazla erişime ihtiyaç duyuyorsa kullanıcıdan yeni kapsamlar vermesini ister. Bu da erişim jetonu almak için yeni bir istek gönderilmesine neden olur (3-6. adımlar).

Chat uygulamaları kimlik doğrulama gerektirdiğinde

Chat uygulamaları, kullanıcı etkileşimine yanıt olarak veya eşzamansız olarak mesaj gönderebilir. Ayrıca kullanıcı adına, Chat alanı oluşturma veya Chat alanındaki kişilerin listesini alma gibi görevleri de tamamlayabilirler.

Chat uygulaması, yanıtı işlerken Chat API'yi veya başka bir Google API'sini çağırmadığı sürece Chat uygulamalarının kullanıcı etkileşimlerine yanıt vermek için kimlik doğrulaması yapması gerekmez.

Chat uygulamaları, eşzamansız mesajlar göndermek veya kullanıcı adına görev gerçekleştirmek için Chat API'ye RESTful istekler gönderir. Bu işlem için kimlik doğrulama ve yetkilendirme gerekir.

Kullanıcı etkileşimlerine verilen yanıtlar için kimlik doğrulama gerekmez

Google Chat uygulamalarının etkileşim etkinliklerini almak ve eşzamanlı olarak yanıt vermek için kullanıcı veya Chat uygulaması olarak kimlik doğrulaması yapmaları gerekmez.

Google Chat uygulamaları, kullanıcılar bir Chat uygulamasıyla etkileşimde bulunduğunda veya çağırdığında, aşağıdakiler de dahil olmak üzere etkileşim etkinlikleri alır:

  • Kullanıcı, Chat uygulamasına mesaj gönderir.
  • Kullanıcı bir Chat uygulamasından @bahseder.
  • Bir kullanıcı, Chat uygulamasının eğik çizgi komutlarından birini çağırır.

Aşağıdaki şemada, bir Chat kullanıcısı ile Chat uygulaması arasındaki istek-yanıt sırası gösterilmektedir:

Chat uygulaması etkileşim etkinlikleri için yetkilendirme gerekmez
Şekil 2.Chat uygulaması etkileşim etkinlikleri kimlik doğrulama gerektirmez.

  1. Kullanıcı, Google Chat'teki Chat uygulamasına bir mesaj gönderir.
  2. Google Chat, mesajı uygulamaya yönlendirir.
  3. Uygulama, mesajı alır, işler ve Google Chat'e bir yanıt döndürür.
  4. Google Chat, yanıtı kullanıcı için veya bir alanda oluşturur.

Bu adım sırası, her Chat uygulaması etkileşim etkinliği için tekrarlanır.

Eşzamansız mesajlar için kimlik doğrulama gerekir

Eşzamansız mesajlar, bir Chat uygulaması Chat API'ye istekte bulunduğunda oluşur. Bu da kimlik doğrulama ve yetkilendirme gerektirir.

Chat uygulamaları, Chat API'yi çağırarak Google Chat'te mesaj yayınlayabilir veya kullanıcının adına görevleri tamamlayıp verilere erişebilir. Örneğin, bir sunucu kesintisi tespit edildikten sonra Chat uygulaması, Chat API'yi şu amaçlarla çağırabilir:

  • Kesintiyi araştırmak ve düzeltmek için özel bir Chat alanı oluşturun.
  • Chat alanına kullanıcı ekleyin.
  • Kesintiyle ilgili ayrıntılı bilgi vermek için Chat alanında bir mesaj yayınlayın.

Aşağıdaki şemada, bir Chat uygulaması ile Chat alanı arasında eşzamansız bir mesaj dizisi gösterilmektedir:

Eşzamansız mesajlar için kimlik doğrulama gerekir
Şekil 3. Eşzamansız mesajlar için kimlik doğrulama gerekir.

  1. Bir Chat uygulaması, spaces.messages.create yöntemini kullanarak Chat API'yi çağırarak bir mesaj oluşturur ve HTTP isteğine kullanıcı kimlik bilgilerini ekler.
  2. Google Chat, Chat uygulamasının kimliğini hizmet hesabı veya kullanıcı kimlik bilgileriyle doğrular.
  3. Google Chat, uygulamanın mesajını belirli bir Chat alanına oluşturur.

Chat API kapsamları

OAuth izin ekranını yapılandırıp kapsamları seçerek kullanıcılara ve uygulama inceleme uzmanlarına gösterilecek bilgileri tanımlayın ve uygulamanızı daha sonra yayınlayabilmek için kaydedin.

Uygulamanıza verilen erişim düzeyini tanımlamak için yetkilendirme kapsamlarını tanımlamanız ve bildirmeniz gerekir. Yetkilendirme kapsamı, Google Workspace uygulamasının adını, eriştiği verilerin türünü ve erişim düzeyini içeren bir OAuth 2.0 URI dizesidir.

Hassas olmayan kapsamlar

Kapsam kodu Açıklama
https://www.googleapis.com/auth/chat.bot

chat.bot kapsamı yalnızca hizmet hesaplarını destekler. Bu kapsamı kullanarak kullanıcı kimlik bilgileriyle veya alan genelinde yetki ile kimlik doğrulayamazsınız.

Chat uygulamalarının sohbetleri görüntülemesine ve mesaj göndermesine izin verir. Chat uygulamalarında kullanılabilen tüm özelliklere erişim sağlar.

Hassas kapsamlar

Kapsam kodu Açıklama
https://www.googleapis.com/auth/chat.spaces Chat'te görüşmeler ve alanlar oluşturup meta verileri (geçmiş ayarları dahil ) görüntüleyin veya güncelleyin.
https://www.googleapis.com/auth/chat.spaces.create Chat'te yeni görüşmeler oluşturabilirsiniz.
https://www.googleapis.com/auth/chat.spaces.readonly Chat'te sohbetleri ve alanları görüntüleyin.
https://www.googleapis.com/auth/chat.memberships Chat'teki görüşmelerde üyeleri görüntüleme, ekleme ve kaldırma.
https://www.googleapis.com/auth/chat.memberships.app Kendisini Google Chat'teki görüşmelere ekleme ve görüşmelerden kaldırma.
https://www.googleapis.com/auth/chat.memberships.readonly Chat görüşmelerindeki üyeleri görüntüleme.
https://www.googleapis.com/auth/chat.messages.create Chat'te mesaj oluşturup gönderin.
https://www.googleapis.com/auth/chat.messages.reactions Chat'te mesajlara tepki ekleyin, verilen tepkileri görüntüleyin ve silin.
https://www.googleapis.com/auth/chat.messages.reactions.create Chat'te mesajlara tepki ekleyin.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Chat'te bir mesaja verilen tepkileri görüntüleyin.
https://www.googleapis.com/auth/chat.users.readstate Chat görüşmelerinin son okunma zamanını görüntüleme ve değiştirme.
https://www.googleapis.com/auth/chat.users.readstate.readonly Chat görüşmelerinin son okunma zamanını görüntüleme.

Kısıtlanmış kapsamlar

Kapsam kodu Açıklama
https://www.googleapis.com/auth/chat.delete Chat'te görüşmeleri ve alanları silebilir, ilişkili dosyalara erişimi kaldırabilirsiniz.
https://www.googleapis.com/auth/chat.import Alanları, mesajları ve üyelikleri Chat'e aktarın. Daha fazla bilgi için Chat uygulamalarını veri içe aktarması için yetkilendirme başlıklı makaleyi inceleyin.
https://www.googleapis.com/auth/chat.messages Mesajları görüntüleyin, oluşturun, gönderin, güncelleyin ve silin. Ayrıca mesajlara tepki ekleyin, verilen tepkileri görüntüleyin ve silin.
https://www.googleapis.com/auth/chat.messages.readonly Chat'te mesajları ve tepkileri görüntüleyin.

Yukarıdaki tablolarda yer alan kapsamlar, aşağıdaki tanımlara göre hassasiyetlerini gösterir:

Uygulamanızın başka herhangi bir Google API'sine erişmesi gerekiyorsa bu kapsamları da ekleyebilirsiniz. Google API kapsamları hakkında daha fazla bilgi için Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümüne bakın.

Google Workspace API'lerinin kapsamları hakkında daha fazla bilgi edinmek için OAuth izin ekranını yapılandırma ve kapsamları seçme başlıklı makaleyi inceleyin.

Gerekli kimlik doğrulama türleri

Chat uygulamalarının Chat API ile kimlik doğrulaması ve yetkilendirme yapmak için kullanabileceği iki yöntem vardır: kullanıcı kimlik bilgileri veya hizmet hesapları.

Chat uygulaması, kullanıcı kimlik bilgisi yetkilendirmesi sayesinde kullanıcı verilerine erişip kullanıcı adına işlemleri tamamlayabilir. OAuth kapsamları, yetkilendirilmiş verileri ve işlemleri belirtir. Ancak, bu Chat uygulamaları herkese açık olarak yayınlanamaz. Daha fazla bilgi edinmek için Google Chat uygulamaları yayınlama başlıklı makaleyi inceleyin.

Uygulama yetkilendirmesi sayesinde, Chat uygulamaları hizmet hesabı kimlik bilgilerini kullanarak API'ye uygulama olarak erişir. Uygulama yetkilendirmesi her zaman chat.bot yetkilendirme kapsamını kullanır.

Alan yöneticisiyseniz bir uygulamanın hizmet hesabına, her kullanıcının izin vermesini gerektirmeden kullanıcılarınızın verilerine erişme yetkisi vermek için alan genelinde yetki verebilirsiniz. Alan genelinde yetkiyi yapılandırdıktan sonra, bir kullanıcı hesabının kimliğine bürünmek için hizmet hesabınızı kullanarak API çağrıları yapabilirsiniz. Kimlik doğrulama için bir hizmet hesabı kullanılsa da alan genelinde yetki, kullanıcının kimliğine büründüğü için kullanıcı kimlik doğrulaması olarak kabul edilir. Kullanıcı kimlik doğrulaması gerektiren tüm işlevler alan genelinde yetki kullanabilir.

Belirli bir API isteği için hangi kimlik bilgisi türünün kullanılacağına karar verirken bazı API yöntemlerinin yalnızca belirli bir kimlik bilgisi türünü desteklediğini unutmayın. Bir API yöntemi her iki kimlik bilgisini de destekliyorsa çağrıda kullanılan kimlik bilgilerinin türü, döndürülen sonucu etkiler:

  • Uygulama yetkilendirmesi sayesinde, yöntemler yalnızca uygulamanın erişebildiği kaynakları döndürür.
  • Kullanıcı yetkilendirmesi sayesinde yöntemler yalnızca kullanıcının Chat kullanıcı arayüzünde erişebildiği kaynakları döndürür.

Örneğin, uygulama yetkilendirmesi ile ListSpaces yöntemi çağrıldığında, uygulamanın üyesi olduğu alanların listesi döndürülür. Kullanıcı yetkilendirmesiyle ListSpaces çağrıldığında, kullanıcının üyesi olduğu alanların listesi döndürülür. Pratikte, uygulamanız Chat API'yi çağırırken istediğiniz işleve bağlı olarak her iki yetkilendirme türünü de kullanabilir.

Eşzamansız Chat API çağrıları için

Aşağıdaki tabloda Chat API yöntemleri ve desteklenen yetkilendirme kapsamları listelenmiştir:

Yöntem Kullanıcı kimlik doğrulaması destekleniyor Uygulama kimlik doğrulaması desteklenir Desteklenen yetkilendirme kapsamları
Alanlar  
Alan oluşturma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Alan oluşturma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces.create
  • chat.spaces
Alan alın Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces.readonly
  • chat.spaces
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Alanları listeleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces.readonly
  • chat.spaces
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Alan güncelleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces
  • chat.import
Alan silme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.delete
  • chat.import
Alanın içe aktarma işlemini tamamlama Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.import
Doğrudan mesajları bulma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.spaces.readonly
  • chat.spaces
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Üyeler  
Üye oluşturma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Üye olun Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.memberships.readonly
  • chat.memberships
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Liste üyeleri Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Üye silme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Mesajlar  
Mesaj oluşturma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.create
  • chat.messages
  • chat.import
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Mesaj alma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.readonly
  • chat.messages
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
İletileri listeleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Mesajları güncelleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages
  • chat.import
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Mesajı silme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages
  • chat.import
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Tepkiler  
Tepki oluşturma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Tepkileri listeleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Tepkiyi silme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Medya ve ekler  
Medyayı dosya eki olarak yükleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.create
  • chat.messages
  • chat.import
Medyayı indir Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.messages.readonly
  • chat.messages
Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Mesaj eki alma Uygulama kimlik doğrulaması etkinken:
  • chat.bot
Kullanıcı okuma durumları
Bir kullanıcının alanı okuma durumunu alma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.users.readstate
  • chat.users.readstate.readonly
Bir kullanıcının alan okuma durumunu güncelleme Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.users.readstate
Bir kullanıcının ileti dizisi okunma durumunu alma Kullanıcı kimlik doğrulaması kullanıldığında:
  • chat.users.readstate
  • chat.users.readstate.readonly

Chat uygulaması etkileşim etkinlikleri için

Aşağıdaki tabloda, kullanıcıların Chat uygulamalarıyla yaygın olarak kullandığı yöntemler ve kimlik doğrulamanın gerekli olup olmadığı veya desteklenip desteklenmediği listelenmiştir:

Senaryo Kimlik doğrulama gerekmez Kullanıcı kimlik doğrulaması destekleniyor Uygulama kimlik doğrulaması desteklenir
Şu kişiden gelen iletileri al:
Chat uygulaması etkileşim etkinlikleri
Apps Komut Dosyası geri çağırmaları
Google Cloud Pub/Sub
Mesajları yanıtlama:
Bir Chat uygulaması etkileşim etkinliği kullanılarak eşzamanlı olarak
Eşzamanlı bir şekilde, bir Apps Komut Dosyası geri çağırma döndürülen değeri kullanarak
Yeni ileti gönderme:
Gelen webhook'larla