Google Chat API'yi yapılandırma

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

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:

Google Chat uygulaması, kullanıcı için bir alan oluşturur.
Şekil 1. Bir kullanıcı adına alan oluşturmak için 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:

  1. 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

  2. Uygulama bilgileri bölümünde Uygulama adı, Avatar URL'si ve Açıklama alanlarını doldurun.

  3. İsteğe bağlı: Uzun açıklama alanını doldurun.

  4. İ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.

  5. 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:

    1. İş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.
    2. 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.
    3. İ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.
    4. İ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.

    5. 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.
  6. İ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.

  7. 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

  1. gcloud CLI'yi yükleyin. gcloud CLI'yi daha önce yüklediyseniz gcloud components update komutunu çalıştırarak en son sürüme sahip olduğunuzdan emin olun.
  2. Kullanıcı hesabınızla gcloud CLI'da oturum açın. Komutlar, hizmet hesaplarını desteklemez.

    gcloud auth login
  3. Chat 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_ID

    Alternatif olarak, her komuta --project işaretini ekleyin.

  4. Cloud projesinde Google Workspace eklentileri API'sini etkinleştirin:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Cloud 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çin serviceusage.services.use izni 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ü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-enabled

Aş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:
  • HTTP uç nokta URL'si: --http-endpoint-url
  • Apps Komut Dosyası: --apps-script-deployment-id
  • Cloud Pub/Sub: Aynı Cloud projesinde bir konuyla --pubsub-topic, projects/PROJECT_ID/topics/TOPIC_ID biçiminde
  • Dialogflow: --dialogflow-edition=es veya --dialogflow-edition=cx (--dialogflow-agent, temsilcinin veya ortamın kaynak adına ayarlanmış şekilde, örneğin projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID)
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=disabled

Yapı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.

  1. Güncellenecek ayarları içeren bir dosya oluşturun. Örneğin, aşağıdaki içeriğe sahip chat_app_config.yaml adlı 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_EMAIL
    

    USER_EMAIL ifadesini, Google Workspace kuruluşunuzda Chat uygulamasını yükleyip test edebilecek bir kişinin veya grubun e-posta adresiyle değiştirin.

  2. update komutunu --config-file iş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.yaml

Ardı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, urlPatterns veya allowlistedTestingPrincipals alanı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-principals ve --remove-allowlisted-testing-principals işaretlerini kullanın.
  • Boş bir değer, ayarı temizler. Örneğin, interactiveFeatureConfig altında urlPatterns: [] 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 update komutu 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, chatAppConfig kaynağı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:
  • Hesabınız gerekli IAM rollerine sahip değil. Metinde Caller does not have required permission to use project ifadesi varsa Hizmet Kullanımı Tüketicisi rolü eksiktir.
  • Google Workspace Eklentileri API'si Cloud projesinde etkinleştirilmemiş.
  • Bir hizmet hesabıyla oturum açtınız.
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:

  1. 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.
  2. https://www.googleapis.com/auth/cloud-platform kapsamını içeren bir OAuth 2.0 kimlik bilgisiyle gerçek kullanıcı olarak kimlik doğrulaması yapın. Hizmet hesabı kimlik doğrulaması, chatAppConfig yöntemleri için desteklenmez.
  3. 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.get ve chat.bots.get, yapılandırmayı (GetChatAppConfig) okuyabilir.
    • Yapılandırmayı (UpdateChatAppConfig) güncellemek için gsuiteaddons.chatAppConfigs.update, chat.bots.update ve chat.bots.get.
  4. İ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 chatAppConfig içeren bir Cloud projesinde ilk kaydetme işlemi için displayName (3 ila 25 karakter) ve description (1 ila 40 karakter) gereklidir. İlk kaydetme işleminde interactiveFeatureConfig parametresini 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ı updateMask sorgu parametresini kullanın (veya sağlanan tüm alanları güncellemek için updateMask parametresini atlayın). Yinelenen bir alan (appCommands, urlPatterns veya allowlistedTestingPrincipals) 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-platform kapsamı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, avatarUri ve interactiveFeatureConfig; 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çin projects.chatAppConfig REST referansı ve projects.chatAppConfig.patch sayfaları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): interactiveFeatureConfig olmadan temel meta verileri döndürür.
  • FULL: interactiveFeatureConfig dahil 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)
  • updateMask, mevcut olmayan veya güncellenemeyen bir alan içeriyor.
  • Bir alan değeri eksik veya geçersiz. Örneğin, interactiveFeatureConfig, connectionConfig içermez.
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)
  • Chat uygulaması, Google Workspace eklentisi olarak oluşturulmamıştır.
  • Chat uygulaması Google Workspace Marketplace'te yayınlandığı için alan değiştirilemiyor.
  • Yeni değer, mevcut Chat uygulaması yapılandırmasıyla uyumlu değil.
  • Chat uygulamasını Google Workspace eklentisine dönüştürün veya Google Cloud Console'da yapılandırın.
  • Yayınlanan girişi güncellemek için message alanındaki talimatları uygulayın.
  • Çakışan ayar için message alanını kontrol edin ve her iki ayarı da aynı istekte güncelleyin veya önce mevcut ayarı değiştirin.
403: Forbidden (PERMISSION_DENIED)
  • Kimliği doğrulanmış kullanıcı, Cloud projesinde gerekli IAM izinlerine sahip değil.
  • İstek, kullanıcı hesabı yerine hizmet hesabıyla kimlik doğrulaması yapar.
  • Kullanıcıya Ön koşullar ve kimlik doğrulama bölümünde listelenen izinleri verin.
  • https://www.googleapis.com/auth/cloud-platform kapsamıyla gerçek bir kullanıcı olarak kimlik doğrulaması yapın.
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.common nesnesinde 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:
  • Eklentinizi bir HTTP hizmeti kullanarak oluşturduysanız Google Workspace Add-ons API'yi kullanarak oluşturduğunuz projects.deployments manifest 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'sindeki chatAppConfig kaynağı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.

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:

  1. Google Cloud Console'da Chat API Yapılandırma sayfasına gidin:

    Chat API Yapılandırması sayfasına gidin

  2. Etkileşimli özellikler bölümünde Etkileşimli özellikleri etkinleştir'i açın.

  3. 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.

  4. İşlevsellik bölümünde, gerektiği şekilde Uygulama ana sayfasını destekle veya Alanlara ve grup görüşmelerine katıl'ı seçin.

  5. 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.

  6. İ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.