Chat uygulamasını diğer hizmetlere ve araçlara bağlama

Bu sayfada, Google Chat uygulamasını Google Chat dışındaki bir hizmete veya araca bağlama açıklanmaktadır. Chat uygulamaları tek başlarına güçlü olsa da genellikle diğer sistemlerle birlikte çalışır ve hesapları bağlamak, veri erişimini yetkilendirmek, ek verileri görüntülemek veya kullanıcı tercihlerini yapılandırmak için yardımcı uygulamalar gerektirir.

Kullanıcıların kimliğini üçüncü taraf hizmeti veya OAuth akışıyla doğrulamak için sohbet uygulamanız aşağıdaki adımları uygular:

1. Yetkilendirme veya yapılandırma gerektiğinde algılama
2. Kullanıcıdan hizmete giriş yapmasını veya hizmeti yapılandırmasını isteyen temel bir yetkilendirme kartı döndürün.
3. Kullanıcı yetkilendirme işlemini tamamladıktan sonra Google Chat'in orijinal etkileşimi otomatik olarak yeniden denemesi için tamamlama URI'sine yönlendirin.

Ön koşullar

Yetkilendirme gerektiğini algılama

Kullanıcılar, Chat uygulamanızla etkileşimde bulunurken çeşitli nedenlerle korunan bir kaynağa erişmek için yetkilendirilmemiş olabilir. Örneğin:

• Üçüncü taraf hizmetine bağlanmak için henüz erişim jetonu oluşturulmamıştır veya erişim jetonunun süresi dolmuştur.
• Erişim jetonu, istenen kaynağı kapsamıyor.
• Erişim jetonu, isteğin gerekli kapsamlarını içermiyor.

Kullanıcıların hizmetinize erişim yetkisi verip oturum açabilmesi için Chat uygulamanız bu durumları algılamalıdır.

Apps Komut Dosyası'nda geliştirme yapıyorsanız Google Apps Komut Dosyası için OAuth2 kitaplığını (veya OAuth1 sürümünü) kullanabilirsiniz. Bu kitaplıkta hasAccess işlevi, kullanıcının bir hizmete erişimi yetkilendirip yetkilendirmediğini kontrol eder. Alternatif olarak, UrlFetchApp.fetch isteklerini kullanırken döndürülen HttpResponse nesnesindeki yanıt kodunu ve içeriği incelemek için muteHttpExceptions parametresini true olarak ayarlayabilirsiniz.

Kullanıcılara temel yetkilendirme kartı gösterme

Chat uygulamanız yetkilendirme veya yapılandırma gerektiğini algıladığında, kullanıcıya özel bir temel yetkilendirme kartı göstermek için AuthorizationError yanıtını döndürün.

Aşağıdaki resimde, Google'ın temel yetkilendirme kartı örneği gösterilmektedir:

Kullanıcılara temel yetkilendirme kartı göstermek için bir AuthorizationError nesnesi döndürün:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Aşağıdakini değiştirin:

• AUTHORIZATION_URL: Kimlik doğrulama, yetkilendirme veya yapılandırma işlemlerini gerçekleştiren web uygulamasının HTTPS URL'si.
• RESOURCE_DISPLAY_NAME: Korunan kaynak veya hizmetin görünen adı. Bu ad, yetkilendirme isteminde kullanıcıya gösterilir. Örneğin, RESOURCE_DISPLAY_NAME cihazınız Example Account ise istemde, uygulamanın Example Account cihazınıza erişmek için onay alması gerektiği belirtilir.

Yapılandırma isteğini tamamlayın

Kullanıcı, Chat'te yetkilendirme sürecini tamamlayabilir ve Chat, manuel yenileme yapmadan orijinal etkileşimi otomatik olarak yeniden deneyebilir. Chat, tetikleyici Mesaj, Alana eklendi veya Uygulama komutu ise otomatik yeniden denemeyi destekler.

Bu tetikleyiciler için sohbet uygulamanız, event payload'da (etkinlik yükü) bir tamamlama yönlendirme URI'si (configCompleteRedirectUri / completeRedirectUri) alır:

• Mesaj: chat.messagePayload.configCompleteRedirectUri
• Alana eklendi: chat.addedToSpacePayload.configCompleteRedirectUri
• Uygulama komutu: chat.appCommandPayload.configCompleteRedirectUri

Bu yönlendirme URI'sini <var>AUTHORIZATION_URL</var> içinde kodlamanız ve yetkilendirme akışı tamamlandıktan sonra kullanıcının tarayıcısını bu URI'ye yönlendirmeniz gerekir. Bu URL'ye yönlendirme, Google Chat'e yetkilendirme veya yapılandırma isteğinin yerine getirildiğini bildirir.

Kullanıcı, orijinal etkinlik yükünde sağlanan tamamlama yönlendirme URI'sine başarıyla yönlendirildiğinde Google Chat aşağıdaki adımları uygular:

1. Başlatan kullanıcıya gösterilen özel yetkilendirme istemini siler.
2. Orijinal iletiyi herkese açık hale getirerek alandaki diğer üyelerin görmesini sağlar.
3. Orijinal etkinlik nesnesini Chat uygulamanıza ikinci kez gönderir.

Tamamlama yönlendirme URI'sine yönlendirme yapmazsanız kullanıcı yetkilendirme akışını tamamlayabilir ancak Google Chat önceki yürütmeyi otomatik olarak yeniden denemez ve kullanıcının Chat uygulamanızı manuel olarak tekrar çağırması gerekir.

Tamamlama yönlendirme URI'sini ziyaret etmek yalnızca tek bir kullanıcı etkileşimini etkiler. Bir kullanıcı, bir sohbet uygulamasına birden fazla kez mesaj gönderip birden fazla istem aldıysa yalnızca bir istem için kimlik doğrulama ve yapılandırma işlemini tamamlamak, yalnızca söz konusu etkileşimi yeniden dener.

Chat kullanıcısını Chat dışında kimlik doğrulama

Chat'in dışındaki bir URL'ye (ör. OAuth web geri araması) bağlantı oluştururken genellikle harici web oturumunu Chat'teki kullanıcı kimliğiyle ilişkilendirmeniz gerekir. Hedef web uygulamasını Google ile oturum açma özelliğiyle korumanızı öneririz.

Kullanıcı kimliğini almak için oturum açma sırasında verilen kimlik jetonunu kullanın. sub talebi, kullanıcının benzersiz Google kimliğini içerir ve Google Chat'teki kullanıcı kaynağı adıyla (chat.user.name) ilişkilendirilebilir.

sub talebini bir Google Chat users/{user} kaynak adıyla ilişkilendirmek için sub talebi değerinin önüne users/ ekleyin. Örneğin, sub talep değeri 123, Chat uygulamanıza gönderilen etkinlik nesnelerinde users/123 ile eşleşir.

Kod örnekleri

Aşağıdaki kod örnekleri, bir Chat uygulamasının temel yetkilendirme kartı kullanarak nasıl çevrimdışı OAuth2 kimlik bilgileri isteyebileceğini, bunları bir veritabanında nasıl saklayabileceğini, tamamlanma URI'sine nasıl yönlendirebileceğini ve kullanıcı kimlik doğrulamasıyla nasıl API çağrıları yapabileceğini gösterir:

İlgili konular

• Kullanıcı etkileşimlerini alma ve yanıtlama
• Google Chat uygulamaları ve Google Chat API isteklerinin kimliğini doğrulama ve yetkilendirme
• Google Workspace eklentinizi üçüncü taraf hizmetine bağlama

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}