Oluşturduğunuz her Google Chat uygulamasının, Chat API'nin etkinleştirildiği ve yapılandırıldığı kendi Google Cloud projesi olmalıdır.
Alanları alma ve mesajları listeleme gibi kullanıcı kimlik doğrulaması ile salt okunur API çağrıları yapmak için yalnızca API'yi etkinleştirmeniz ve bir OAuth istemcisi oluşturmanız gerekir.
API çağrıları oluşturmak, güncellemek ve silmek ya da etkileşimli bir Chat uygulaması (Chat'i genişleten bir Google Workspace eklentisi olarak oluşturulmuş) dağıtmak ve test etmek için Chat API'yi de yapılandırmanız gerekir. Chat API yapılandırma ayarlarında, Chat uygulamasıyla ilgili görünen ad, avatar, dağıtım uç noktaları ve etkileşimli özellikler gibi tüm ayrıntıları belirtirsiniz.
Ön koşullar
- Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.
- Google Cloud projesi oluşturun.
- OAuth kullanıcı rızası ekranını yapılandırın.
- Google Chat API'yi etkinleştirin.
Chat uygulamanız için görünen ad, avatar ve açıklama seçme
Chat API'yi etkinleştirdiğinizde Chat uygulamanızla ilgili olarak Chat'te kullanıcılara gösterilecek ayrıntıları (ör. görünen ad, avatar ve açıklama) yapılandırırsınız. Bu ayrıntılar yalnızca Chat'te görünür. Chat uygulamanızı Marketplace'te yayınlamak için Chat uygulamanızın Marketplace girişinde görünen ayrıntıları da belirtmeniz gerekir.
Bir Chat uygulamasını yapılandırmadan önce aşağıdaki bilgileri hazırlayın:
| Alan | Açıklama | Biçim |
|---|---|---|
| Uygulama adı | Chat uygulamasının görünen adı. | En fazla 25 alfanümerik karakter |
| Avatar URL'si | Chat uygulamanızın avatarı olarak gösterilen resim. | Kare grafik resmini (PNG veya JPEG) gösteren bir HTTPS URL'si. Önerilen boyut 256x256 piksel veya daha büyüktür. |
| Açıklama | Kullanıcılar Chat'te uygulama aradığında gösterilen, Chat uygulamasının kısa açıklaması. | En fazla 40 alfanümerik karakter |
| Uzun açıklama | İsteğe bağlıdır. Chat uygulamasının neler yapabileceğine dair bir açıklama. Kullanıcılar Chat uygulamasıyla görüşme başlattığında veya bir temsilci için oturumlar ana sayfasını açtığında gösterilir. Şu anda yalnızca Google Cloud Console kullanılarak uygulama yapılandırması güncellenirken desteklenir ve Google Workspace Eklentileri API'si aracılığıyla desteklenmez. | En fazla 250 karakter |
Chat uygulamasının adı, avatarı ve açıklaması, Chat kullanıcı arayüzünde kullanıcılara gösterilir. Chat, bazı Chat API yazma istekleri için bu bilgileri kullanarak Chat uygulamasının Chat'te gerçekleştirdiği işlemleri ilişkilendirir.
Örneğin, spaces.create() yöntemini çağırırsanız Chat, alanı oluşturan kişinin açıklamasında Chat uygulamasının adını aşağıdaki resimde gösterildiği gibi ekler:
spaces.create() yöntemi kullanıldığında Chat'in gösterdiği ilişkilendirme mesajı.
Kullanıcılar, Chat uygulamalarıyla etkileşimde bulunmak için bu bilgileri aşağıdaki şekillerde de görür veya kullanır:
- Chat uygulamasını bir alana eklemek veya uygulamaya mesaj göndermek için @bahsetme özelliğini kullanın.
- Chat uygulamasını bulup doğrudan mesaj başlatın. Uygulamalar menüsünde, doğrudan mesajlarda Chat uygulamasının adı ve avatarı gösterilir.
- Kullanıcılar, oluşturma çubuğundan Chat uygulamalarına göz atabilir ve uygulamaların adını, avatarını ve açıklamasını görebilir.
Google Cloud Console'da Chat uygulamanızı yapılandırma
Chat uygulamanızın ayrıntılarını aldıktan sonra Cloud projenizi açın ve Chat API'yi yapılandırın:
Google Cloud Console'da Chat API sayfasına gidin ve Yapılandırma sayfasını tıklayın:
Chat API Configuration (Chat API Yapılandırması) sayfasına gidin
Uygulama bilgileri bölümünde Uygulama adı, Avatar URL'si ve Açıklama alanlarını doldurun.
İsteğe bağlı: Uzun açıklama alanını doldurun.
İsteğe bağlı: İşaretleme söz dizimi menüsünden Chat uygulamanızın mesajları için varsayılan işaretleme söz dizimini (Markdown veya Chat) seçin. Metin biçimlendirme ve Chat'in API istekleri için işaretleme söz dizimini nasıl belirlediği hakkında daha fazla bilgi edinmek isterseniz Mesajları biçimlendirme başlıklı makaleyi inceleyin.
Etkileşimli özellikler bölümünde, Chat uygulamanızın kullanıcı etkileşimlerine yanıt verip vermeyeceğini yapılandırın:
Etkileşimli bir Chat uygulaması oluşturmak için Etkileşimli özellikleri etkinleştir'i açın ve aşağıdakileri tamamlayın:
- İşlevsellik bölümünde:
- İsteğe bağlı: Chat uygulamasıyla bire bir doğrudan mesajların Ana Sayfa sekmesinde bir ana sayfa kartı göstermek için Uygulama ana sayfasını destekle'yi seçin.
- Chat uygulamanızı yüklenmeye ve kullanılmaya hazır hale getirmek için Alanlara ve grup görüşmelerine katılma'yı seçin. Varsayılan olarak, kullanıcılar Chat uygulamasını yükleyebilir ve kullanıcı ile Chat uygulaması arasındaki özel bir alanda Chat uygulamasıyla mesajlaşabilir. Kullanıcılar ayrıca birden fazla kişinin bulunduğu alanlara Chat uygulamasını ekleyebilir ve bu uygulamayla etkileşim kurabilir.
Bağlantı ayarları bölümünde, Chat'ten olay nesneleri almak için kullanmak istediğiniz mimariyi seçin:
- HTTP hizmeti kullanmak için HTTP uç noktası URL'si'ni seçin ve bir URL girin.
- Google Apps Komut Dosyası projesi kullanmak için Apps Komut Dosyası'nı seçin ve proje için bir dağıtım kimliği sağlayın.
- Dialogflow temsilcisi kullanmak için Dialogflow'u, ardından Dialogflow CX veya Dialogflow ES'yi seçin ve temsilcinin kaynak adını girin.
- Pub/Sub'ı kullanmak için Cloud Pub/Sub'ı seçin ve konu adını girin.
İsteğe bağlı: Olay nesnelerini belirli uç noktalara veya işlevlere yönlendirmek için Bağlantı ayarları > Tetikleyiciler'e gidin ve aşağıdaki Chat tetikleyicileri için geri çağırma uç noktalarını veya işlevlerini sağlayın ya da güncelleyin:
- Uygulama ana sayfası (Uygulama ana sayfasını destekle etkinse): Kullanıcı, Chat uygulamasıyla bire bir doğrudan mesajda Ana Sayfa sekmesini açar.
- Alana eklendi: Kullanıcı, Chat uygulamasını bir grup görüşmesine veya alana ekler ya da bire bir mesajlar için Chat uygulamasını yükler.
- Mesaj: Kullanıcı, Chat uygulamasına mesaj gönderir. Örneğin, kullanıcı Chat uygulamasına doğrudan mesaj gönderir veya birden fazla kişinin bulunduğu bir alanda Chat uygulamasından @bahseder.
- Alandan kaldırıldı: Kullanıcı, Chat uygulamasını bir alandan kaldırır veya siler.
- Uygulama komutu: Kullanıcı, Chat uygulamasından bir hızlı komut, eğik çizgi komutu veya mesaj işlemi çağırır.
İsteğe bağlı: Oturumlar, başlangıç istemleri, komutlar (hızlı komutlar, eğik çizgi komutları ve mesaj işlemleri) veya bağlantı önizlemeleri gibi diğer etkileşimli özellikleri ekleyin.
Görünürlük bölümünde Bu Chat uygulamasını belirli kişiler ve gruplar için kullanılabilir yap'ı seçin ve Google Workspace kuruluşunuzdaki kişilerin veya Google Gruplar'ın e-posta adreslerini girin:
- Uygulamanızı kendiniz yükleyip test etmek için kendi e-posta adresinizi girin.
- Dahili bir Chat uygulamasını Marketplace'te yayınlamadan bir ekipte veya kuruluşunuzun tamamında paylaşmak için bir ya da daha fazla Google Grubu girin. Gruplarda üye sınırı yoktur. Uygulamanız
chat.app.*kapsamları istiyorsa yönetici onayı için uygulamayı yayınlamanız gerekir. - Yöneticiniz, Marketplace yüklemelerini izin verilenler listesindeki uygulamalarla kısıtlıyorsa Google Cloud Console, bu alanı geliştirme için beş ayrı kullanıcı e-posta adresiyle sınırlar. Grup görünürlüğü, yalnızca bir yönetici uygulamayı izin verilenler listesine ekledikten sonra geçerli olur.
- İşlevsellik bölümünde:
İsteğe bağlı: Google Cloud Logging'i kullanmak için Günlükler bölümünde Hataları Logging'e kaydet onay kutusunu işaretleyin. Daha fazla bilgi için Chat uygulamaları için sorgu hatası günlükleri başlıklı makaleyi inceleyin.
Kaydet'i tıklayın.
Yapılandırmayı kaydettikten sonra, Chat API'nin Görünürlük ayarında belirttiğiniz herkes Chat uygulamasını yükleyebilir, test edebilir veya kullanabilir. Chat uygulamanızı test etmeye ve hata ayıklamaya başlamak için Google Chat uygulamalarının etkileşimli özelliklerini test etme başlıklı makaleyi inceleyin.
Google Cloud CLI'yı kullanarak Chat uygulamanızı yapılandırma
Google Cloud Console'u kullanmak yerine, Google Cloud CLI (gcloud CLI) ile komut satırından bir Chat uygulamasının yapılandırmasını görüntüleyebilir ve güncelleyebilirsiniz. Örneğin, bir Chat uygulamasını komut dosyasından yapılandırabilir veya yapılandırmasını kodunuzla birlikte sakladığınız bir dosyada tutabilirsiniz.
gcloud beta workspace-add-ons chat-app-config komut grubunda aşağıdaki komutlar bulunur:
describe: Yapılandırmayı gösterir.update: Bir Chat uygulamasını ilk kez yapılandırır veya yapılandırmasını değiştirir.
Komutlar, Google Workspace Add-ons API'deki chatAppConfig kaynağını kullanır.
Başlamadan önce
- gcloud CLI'yi yükleyin. gcloud CLI'yi daha önce yüklediyseniz
gcloud components updatekomutunu çalıştırarak en son sürüme sahip olduğunuzdan emin olun. Kullanıcı hesabınızla gcloud CLI'da oturum açın. Komutlar, hizmet hesaplarını desteklemez.
gcloud auth loginChat uygulamanızın Cloud projesini gcloud CLI'nin varsayılan projesi olarak ayarlayın. Komutlar proje numarasını kabul etmediği için proje kimliğini kullanın.
gcloud config set project PROJECT_IDAlternatif olarak, her komuta
--projectişaretini ekleyin.Cloud projesinde Google Workspace eklentileri API'sini etkinleştirin:
gcloud services enable gsuiteaddons.googleapis.comCloud projesinde aşağıdaki Identity and Access Management (IAM) rollerine sahip olduğunuzdan emin olun:
- Yapılandırmayı görüntülemek ve güncellemek için Google Workspace Eklentileri Geliştiricisi (
roles/gsuiteaddons.developer) veya yalnızca görüntülemek için Google Workspace Eklentileri Okuyucusu (roles/gsuiteaddons.reader) rolüne sahip olmanız gerekir. Bu roller, Ön koşullar ve kimlik doğrulama bölümünde listelenen izinleri içerir. - Hizmet Kullanımı Tüketicisi
(
roles/serviceusage.serviceUsageConsumer). gcloud CLI, istekleri için kota projesi olarak Cloud projesini kullanır. Bu işlem içinserviceusage.services.useizni gerekir.
Sahip ve Düzenleyici rolleri bu izinlerin tümünü içerir. Google Cloud Console'daki yapılandırma sayfasına erişim sağlayan Chat uygulamaları sahibi ve Chat uygulamaları görüntüleyicisi rolleri yeterli değildir.
- Yapılandırmayı görüntülemek ve güncellemek için Google Workspace Eklentileri Geliştiricisi (
Yapılandırmayı görüntüleme
Chat uygulamanızın yapılandırmasını görüntülemek için describe komutunu çalıştırın:
gcloud beta workspace-add-ons chat-app-config describeÇıkış şuna benzer:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
Cloud projesinde henüz bir Chat uygulaması yoksa komut başarılı olur ve yapılandırmanın yalnızca name alanını yazdırır:
name: projects/123456789012/chatAppConfig
Çıkışı değiştirmek için aşağıdaki işaretlerden birini ekleyin:
--format=json: Yapılandırmayı JSON biçiminde yazdırır.--view=basic: Etkileşimli özellik ayarlarını (interactiveFeatureConfig) hariç tutar.--format="value(displayName)": Yalnızca görünen adı veya Cloud projesinde henüz bir Chat uygulaması yoksa boş bir satırı yazdırır. Yapılandırılmış bir Chat uygulamasının her zaman görünen adı vardır. Bu nedenle, bir Chat uygulamasının mevcut olup olmadığını kontrol etmek için komut dosyasında bu işareti kullanabilirsiniz.
Yapılandırmayı güncelleme
Bir Chat uygulamasını ilk kez yapılandırmak veya yapılandırmasını değiştirmek için update komutunu çalıştırın. Ayarları işaretlerle veya bir yapılandırma dosyasında belirtin. İkisini tek bir komutta birleştiremezsiniz.
Bir Cloud projesi için komutu ilk kez çalıştırdığınızda en azından bir görünen ad ve açıklama belirtmeniz gerekir. Durumu devre dışı olarak ayarlamadığınız sürece Chat uygulaması, komut tamamlanır tamamlanmaz etkinleşir. Test kullanıcısı olarak listelediğiniz kişiler, uygulamayı bulup kullanabilir.
İşaretleri kullanma
Aşağıdaki örnekte, bir HTTP uç noktasında etkinlik alan bir Chat uygulaması yapılandırılmaktadır:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledAşağıdakini değiştirin:
HTTP_ENDPOINT_URL: Chat'ten olay nesnelerini alan HTTPS URL'si.USER_EMAIL: Google Workspace kuruluşunuzda Chat uygulamasını yükleyip test edebilecek bir kişinin veya grubun e-posta adresi (ör. kendi e-posta adresiniz).
Komut, güncellenen yapılandırmayı yazdırır.
Aşağıdaki tabloda, Google Cloud Console'daki Chat API Yapılandırma sayfasında bulunan ayarların işaretleri listelenmektedir. Her bir işaretle ilgili ayrıntılar için update komut referansına bakın.
| Google Cloud Console'daki ayar | Bayraklar |
|---|---|
| Uygulama adı | --display-name |
| Avatar URL'si | --avatar-uri değerini, avatar koşullarını karşılayan bir resmin HTTPS URL'siyle değiştirin veya varsayılan avatarı kullanmak için --clear-avatar-uri değerini girin. |
| Açıklama | --description |
| Uygulama durumu | --state=active veya --state=disabled |
| İşaretleme söz dizimi | --markup-syntax=markdown veya
--markup-syntax=chat |
| Alanlara ve grup görüşmelerine katılma | --supports-multiuser-spaces veya
--no-supports-multiuser-spaces |
| Bağlantı ayarları | Aşağıdakilerden biri:
|
| Görünürlük | --add-allowlisted-testing-principals,
--remove-allowlisted-testing-principals ve
--clear-allowlisted-testing-principals |
| Hataları Logging'e kaydetme | --error-logging-enabled veya
--no-error-logging-enabled |
Komutlar, bağlantı önizlemeleri ve her tetikleyici için ayrı uç noktalarda işaret yoktur. Bunları yapılandırmak için bir yapılandırma dosyası kullanın.
Örneğin, diğer ayarlarını değiştirmeden Chat uygulamanızı devre dışı bırakmak için aşağıdaki komutu çalıştırın. Tekrar açmak için --state=active tuşuna basın.
gcloud beta workspace-add-ons chat-app-config update --state=disabledYapılandırma dosyası kullanma
Yapılandırmayı bir dosyada tutmak veya işaretleri olmayan ayarları yapılandırmak için update komutuna bir YAML veya JSON dosyası iletin. Dosya, chatAppConfig kaynağının alanlarını kullanır. Bu alanlar, describe komutunun yazdırdığı alanlarla aynıdır.
Güncellenecek ayarları içeren bir dosya oluşturun. Örneğin, aşağıdaki içeriğe sahip
chat_app_config.yamladlı bir dosya oluşturun:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILUSER_EMAILifadesini, Google Workspace kuruluşunuzda Chat uygulamasını yükleyip test edebilecek bir kişinin veya grubun e-posta adresiyle değiştirin.updatekomutunu--config-fileişaretiyle çalıştırın:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
Bir Chat uygulamasının mevcut yapılandırmasından başlamak için describe komutunun çıkışını bir dosyaya kaydedin:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlArdından dosyayı düzenleyin, değiştirmek istemediğiniz alanları silin ve dosyayı update komutuna iletin. Dosyada, komutun güncelleyemediği bir ayar varsa komut başarısız olur. Ayrıntılı bilgi için Sınırlamalar bölümüne bakın.
update komutu, dosyadaki name alanını yoksayar. gcloud CLI'da ayarladığınız Cloud projesini her zaman günceller. Bu sayede, başka bir Cloud projesinde Chat uygulamasını yapılandırmak için aynı dosyayı kullanabilirsiniz.
Komut, değişikliklerinizi nasıl uygular?
- Yalnızca belirttiğiniz ayarlar değişir. İşaretlerle birlikte kullanıldığında komut, ilettiğiniz işaretlerin ayarlarını değiştirir. Yapılandırma dosyasıyla, dosyadaki alanları değiştirir. Bu nedenle, dosyanın tüm yapılandırmayı içermesi gerekmez. Bağlantı ayarları bir istisnadır: Ayarladığınız bağlantı türü mevcut bağlantı türünün, ayarladığınız Dialogflow sürümü ise tüm Dialogflow yapılandırmasının yerini alır.
- Listeler bir bütün olarak değiştirilir. Dosya
appCommands,urlPatternsveyaallowlistedTestingPrincipalsalanını içeriyorsa dosyadaki liste mevcut listenin yerini alır. Test kullanıcılarını tek tek eklemek veya kaldırmak için--add-allowlisted-testing-principalsve--remove-allowlisted-testing-principalsişaretlerini kullanın. - Boş bir değer, ayarı temizler. Örneğin,
interactiveFeatureConfigaltındaurlPatterns: []içeren bir dosya, tüm bağlantı önizleme URL kalıplarını kaldırır. - Başarısız olan bir komut hiçbir şeyi değiştirmez. Bir değer geçerli değilse komut, hatayı yazdırır ve yapılandırmayı olduğu gibi bırakır.
- İstekler sıklık sınırlamasına tabidir. API, her Cloud projesi ve her kuruluş için dakikada gönderilebilecek okuma ve güncelleme isteklerinin sayısını sınırlar. Her
updatekomutu bir güncelleme isteği gönderir. İşaretlerle test kullanıcısı ekler veya kaldırırsanız komut bir okuma isteği de gönderir. Birden fazla ayarı değiştirmek için her ayar için ayrı bir komut çalıştırmak yerine bunları tek bir komut veya tek bir dosya halinde iletin.
Sınırlamalar
- Komutlar yalnızca Google Workspace eklentisi olarak geliştirilen Chat Uygulamalarını destekler.
- Komutlar, hizmet hesaplarını veya hizmet hesabı kimliğine bürünmeyi desteklemez. gcloud CLI'da bir kullanıcı hesabıyla oturum açmanız gerekir.
- Bir Cloud projesinde bir Chat uygulaması yapılandırması vardır ve komutlar bunu silemez. Kullanıcıların Chat uygulamasını kullanmasını engellemek için uygulamanın durumunu devre dışı olarak ayarlayın veya Cloud projesini silin.
- Güncelleme, canlı Chat uygulaması için geçerlidir. Komutların taslak veya deneme modu yoktur.
- Bir Chat uygulaması Google Workspace Marketplace'te yayınlanırken veya incelenirken komutlar uygulamanın görünen adını, avatarını, açıklamasını, komutlarını ya da bağlantı önizleme URL kalıplarını değiştiremez.
- Komutlar,
chatAppConfigkaynağındaki ayarları destekler. Kaynağın içermediği bir ayarı yapılandırmak için Google Cloud Console'u kullanın.
Sorun giderme
Bir komut başarısız olursa hata mesajındaki metni aşağıdaki tabloda bulun. Mesaj INVALID_ARGUMENT gibi bir durumla başlıyorsa Google Workspace Eklentileri API'si isteği reddetmiştir ve durumdan sonraki metinde sorun açıklanır.
| Hata mesajı şunları içeriyor: | Neden | Çözüm |
|---|---|---|
Invalid choice: 'chat-app-config' veya Invalid choice: 'workspace-add-ons' |
Komut beta içermiyor veya gcloud CLI sürümünüz komutları içermiyor. |
Komuta gcloud beta workspace-add-ons chat-app-config ile başlayın. Hata devam ederse gcloud CLI'yı en yeni sürüme güncelleyin. |
PROJECT ID |
Proje, bir proje numarasına ayarlanmıştır. | Proje kimliğini projeye ayarlayın. |
Failed to parse value(s) in protobuf |
Yapılandırma dosyası, gcloud CLI'nin tanımadığı bir alan içeriyor. Hata mesajında alanın adı belirtilir. | Alan adını describe komutunun çıkışıyla karşılaştırın. Alan yeniyse gcloud CLI'yı en yeni sürüme güncelleyin. |
does not have permission to access projects instance |
API, isteği reddetti. Bu mesajdan sonraki metinde neden belirtilir. Örneğin:
|
Başlamadan önce bölümündeki şartları kontrol edin. |
INVALID_ARGUMENT |
Bir değer geçerli değil. Örneğin, görünen ad 3 ila 25 karakter, açıklama ise 1 ila 40 karakter uzunluğunda olmalıdır. Mesajda not found or deleted ifadesi varsa proje kimliği doğru değildir. |
Hata mesajında açıklanan değeri düzeltin ve komutu tekrar çalıştırın. |
FAILED_PRECONDITION |
Chat uygulaması isteğe izin vermiyor. Örneğin, Google Workspace eklentisi olarak oluşturulmamışsa veya Google Workspace Marketplace'te yayınlanmışsa ayar değiştirilemez. | Hata mesajındaki talimatları uygulayın. Google Workspace eklentisi olmayan bir Chat uygulamasını yapılandırmak için Google Cloud Console'u kullanın veya uygulamayı dönüştürün. |
RESOURCE_EXHAUSTED veya 429 |
API, kısa bir süre içinde Cloud projesi veya kuruluşunuz için çok fazla istek aldı. | Bir dakika bekleyip komutu tekrar çalıştırın. |
Google Workspace Add-ons API'yi kullanarak Chat uygulamanızı yapılandırma
Chat uygulamanızı Google Cloud Console'da manuel olarak yapılandırmak yerine, Google Workspace add-ons API'ndaki chatAppConfig kaynağını kullanarak Google Workspace eklentisi olarak oluşturulmuş bir Chat uygulamasının yapılandırmasını programatik olarak okuyabilir ve güncelleyebilirsiniz.
chatAppConfig, her Cloud projesinde her zaman bulunan tekil bir kaynaktır. Bir yapılandırmayı ilk kez kaydetmeden önce kaynakta boş bir yapılandırma bulunur (ilk kaydetme işleminden önce kaynağı okursanız GetChatAppConfig da bunu döndürür). Kaynak zaten mevcut olduğundan ayrı olarak oluşturmanız gerekmez. Hem ilk yapılandırmayı kaydetmek hem de mevcut bir yapılandırmayı güncellemek için UpdateChatAppConfig kullanın.
Ön koşullar ve kimlik doğrulama
GetChatAppConfig veya UpdateChatAppConfig yöntemini çağırmadan önce aşağıdaki ön koşulları tamamlayın:
- Cloud projenizde Google Workspace Add-ons API'yi (
gsuiteaddons.googleapis.com) etkinleştirin. İsterseniz Google Cloud Console'da Chat uygulaması yapılandırmasını görüntülemek veya güncellemek ya da Chat API'yi çağırmak için Google Chat API'yi (chat.googleapis.com) etkinleştirebilirsiniz. https://www.googleapis.com/auth/cloud-platformkapsamını içeren bir OAuth 2.0 kimlik bilgisiyle gerçek kullanıcı olarak kimlik doğrulaması yapın. Hizmet hesabı kimlik doğrulaması,chatAppConfigyöntemleri için desteklenmez.- Kimliği doğrulanmış kullanıcının hedef Cloud projesinde gerekli Identity and Access Management (IAM) izinlerine sahip olduğundan emin olun:
gsuiteaddons.chatAppConfigs.getvechat.bots.get, yapılandırmayı (GetChatAppConfig) okuyabilir.- Yapılandırmayı (
UpdateChatAppConfig) güncellemek içingsuiteaddons.chatAppConfigs.update,chat.bots.updatevechat.bots.get.
- İstemci kitaplığı kullanıyorsanız diliniz için Google Workspace Eklentileri API istemci kitaplığının en yeni sürümünü yükleyin. İstemci kitaplıklarının listesi için Google Workspace Eklentileri API referansına bakın.
Chat uygulaması yapılandırmasını güncelleme
Bir Chat uygulamasını ilk kez yapılandırmak veya mevcut bir yapılandırmayı güncellemek için Cloud projenizin tekil chatAppConfig kaynağına bir PATCH isteği (UpdateChatAppConfig) gönderin:
- Boş bir
chatAppConfigiçeren bir Cloud projesinde ilk kaydetme işlemi içindisplayName(3 ila 25 karakter) vedescription(1 ila 40 karakter) gereklidir. İlk kaydetme işlemindeinteractiveFeatureConfigparametresini atlarsanız Chat uygulaması etkileşimli olmayan bir uygulama olarak yapılandırılır. - Sonraki güncellemelerde, güncellenecek virgülle ayrılmış alanları belirtmek için isteğe bağlı
updateMasksorgu parametresini kullanın (veya sağlanan tüm alanları güncellemek içinupdateMaskparametresini atlayın). Yinelenen bir alan (appCommands,urlPatternsveyaallowlistedTestingPrincipals) güncellendiğinde listenin tamamı değiştirilir.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
İstek URL'si, üstbilgisi ve gövdesinde aşağıdakileri değiştirin:
PROJECT_NUMBER: Chat uygulamanızı barındıran Cloud projesinin sayısal proje numarası.ACCESS_TOKEN:https://www.googleapis.com/auth/cloud-platformkapsamıyla yetkilendirilmiş bir kullanıcı OAuth 2.0 erişim jetonu.USER_EMAIL: Chat uygulamasını test etmek için izin verilenler listesine eklenecek, Google Workspace kuruluşunuzdan bir e-posta adresi veya Google Grubu (ör. kendi e-posta adresiniz).- İstek gövdesindeki örnek yapılandırma alanlarını (ör.
displayName,description,avatarUriveinteractiveFeatureConfig; uç nokta yapılandırmanız, komutlarınız, bağlantı önizleme URL kalıplarınız ve test sorumlularınız dahil) Chat uygulamanızın değerleriyle değiştirin. Desteklenen tüm alanlar ve uç nokta seçenekleri hakkında ayrıntılı bilgi içinprojects.chatAppConfigREST referansı veprojects.chatAppConfig.patchsayfalarını inceleyin.
Chat uygulaması yapılandırmasını alma
Bir Cloud projesinin mevcut Chat uygulaması yapılandırmasını okumak için GetChatAppConfig yöntemini çağırın.
İsteğe bağlı view sorgu parametresini (ChatAppConfigView) iletebilirsiniz:
BASIC(varsayılan):interactiveFeatureConfigolmadan temel meta verileri döndürür.FULL:interactiveFeatureConfigdahil olmak üzere tüm yapılandırma alanlarını döndürür.
Cloud projesi için Chat uygulaması yapılandırması henüz kaydedilmediyse yöntem boş bir ChatAppConfig nesnesi döndürür.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
Kullanım sınırları
chatAppConfig yöntemlerinin proje başına kotaları vardır. Bir kotayı aşarsanız istek, 429: Too many requests HTTP durum koduyla başarısız olur. Kota sınırları için Google Workspace Add-ons API kullanım sınırları başlıklı makaleyi inceleyin.
Hataları giderme
Bir chatAppConfig isteği başarısız olursa hata yanıtındaki HTTP durum kodunu ve message alanını kontrol edin. Aşağıdaki tabloda yaygın hatalar, nedenleri ve nasıl çözülecekleri listelenmiştir.
| HTTP durum kodu | Genel nedenler | Çözünürlük |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
Geçersiz alan için message alanını kontrol edin ve isteği düzeltin. Desteklenen alanlar ve değerler için projects.chatAppConfig referansına bakın. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
Kaynak adındaki Cloud projesi mevcut değil veya kimliği doğrulanmış kullanıcı bu projeye erişemiyor. | Kaynak adında projects/PROJECT_NUMBER/chatAppConfig biçiminde doğru proje numarasının kullanıldığından ve kullanıcının Cloud projesine erişimi olduğundan emin olun. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
Proje başına kota aşıldı. | Bekleyin ve isteği daha sonra tekrar deneyin. Sınırlar için Kullanım sınırları başlıklı makaleyi inceleyin. |
Mevcut Google Workspace eklentileriyle ilgili dikkat edilmesi gereken noktalar
Chat uygulamaları, diğer Google Workspace uygulamalarını genişleten Google Workspace eklentilerine kıyasla farklı bir yapılandırma gerektirir. Eklentiniz diğer Google Workspace uygulamalarını genişletiyorsa Chat uygulamasını yapılandırmak için aşağıdaki şartları göz önünde bulundurun:
- Hem bireysel kullanıcılar hem de Google Workspace yöneticileri, eklentinizi Marketplace'ten yükleyebilmelidir. Bu yükleme ayarlarını Marketplace SDK'sında yapılandırırsınız.
- Chat uygulamaları, manifest'in
addons.commonnesnesinde diğer Google Workspace uygulamaları için yapılandırdığınız adı ve logoyu kullanmaz. - Google Workspace Marketplace'te yayınlanan eklentiler için Google Chat API yapılandırma ayarlarında yapılan değişikliklerin taslağını kaydedemezsiniz. Chat API yapılandırma ayarlarını güncelleyip kaydettikten sonra güncellenen Chat uygulaması, mevcut tüm kullanıcılar tarafından hemen kullanılabilir. Pazar Yeri girişinizi güncellemek için herhangi bir değişiklik göndermeden önce taslak oluşturabilirsiniz.
- Eklentinizi Apps Komut Dosyası'nı kullanarak oluşturduysanız:
- Eklenti yapılandırmanızın geri kalanı için kullandığınız Apps Komut Dosyası dağıtım kimliğini kullanmanız gerekir.
- Chat'te test dağıtımlarını yüklemek için Apps Komut Dosyası düzenleyicisini kullanamazsınız. Bunun yerine, uygulamaları doğrudan Chat kullanıcı arayüzünden yüklemeniz gerekir.
- Eklentinizi bir HTTP hizmeti kullanarak oluşturduysanız Google Workspace Add-ons API'yi kullanarak oluşturduğunuz
projects.deploymentsmanifest dosyasında Chat uygulaması yapılandırma ayrıntılarını atlayın. Google Workspace Marketplace SDK'sında belirttiğiniz HTTP dağıtımları yalnızca diğer Google Workspace uygulamaları için kullanılır. Bunun yerine, Chat uygulamanızı Google Cloud Console'da, gcloud CLI ile veya Google Workspace Eklentileri API'sindekichatAppConfigkaynağını kullanarak yapılandırın.
Diğer kullanıcılara Chat API'yi yapılandırma izni verme
Chat uygulamaları Sahibi veya Chat uygulamaları Görüntüleyicisi Google Cloud Identity Access Management (IAM) rolünü vererek belirli kullanıcıların Chat uygulaması yapılandırma sayfasına erişmesine izin verebilirsiniz. Bu rollere sahip kullanıcılar, API'ler ve Hizmetler kontrol panelini kullanarak Chat uygulamaları yapılandırma sayfasına gidemez ancak Chat uygulamasının ana makine Cloud projesi için Google Cloud konsoluna giderek yapılandırma sayfasına şu şekilde erişebilir:
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
PROJECT_ID, Chat uygulamasını barındıran Google Cloud projesinin proje kimliğidir.
İlgili konular
- Chat uygulaması mimarisi seçme
- Kullanıcı etkileşimlerini alma ve yanıtlama
- Google Chat uygulamaları için etkileşimli özellikleri test etme
Eklenti olmayan Chat uygulamaları: Google Chat API'yi yapılandırma
Google Workspace eklentisi olmayan bir Chat uygulaması kullanıyorsanız yapılandırmanızda, etkinliğe özel tetikleyiciler yerine tüm etkileşim etkinlikleri için tek bir uç nokta kullanılır:
Google Cloud Console'da Chat API Yapılandırma sayfasına gidin:
Etkileşimli özellikler bölümünde Etkileşimli özellikleri etkinleştir'i açın.
Bu Chat uygulamasını Google Workspace eklentisi olarak oluştur seçeneğinin işaretini kaldırın. Onaylamanızı isteyen bir iletişim kutusu açılır. İletişim kutusunda Devre dışı bırak'ı tıklayın.
İşlevsellik bölümünde, gerektiği şekilde Uygulama ana sayfasını destekle veya Alanlara ve grup görüşmelerine katıl'ı seçin.
Bağlantı ayarları bölümünde Chat uygulamanız için tek bir uç nokta (HTTP uç nokta URL'si, Apps Komut Dosyası dağıtım kimliği, Cloud Pub/Sub konu adı veya Dialogflow) belirtin.
İsteğe bağlı olarak Komutlar, Başlangıç istemleri, Bağlantı önizlemeleri, Görünürlük ve Günlükler'i yapılandırın, ardından Kaydet'i tıklayın.
Eklenti olmayan bir Chat uygulamasını Google Chat'i genişleten bir Google Workspace eklentisine yükseltmek için Google Chat uygulamasını Google Workspace eklentisine dönüştürme başlıklı makaleyi inceleyin.