Bu kılavuzda, Chat uygulaması adına Google Chat API'ye erişmek için hizmet hesabının nasıl oluşturulacağı ve kullanılacağı açıklanmaktadır. Öncelikle, hizmet hesabı oluşturma konusunda size yol gösterilir. Ardından, Chat API ile kimlik doğrulamak için hizmet hesabını kullanan bir komut dosyasının nasıl yazılacağını ve Chat alanında nasıl mesaj yayınlanacağını gösterir.
Chat uygulamaları, Google Chat API'yi eşzamansız olarak çağırırken kimlik doğrulaması yapmak için hizmet hesaplarını kullanabilir. Böylece:
- Google Chat'e
spaces.messages.create
ile mesaj göndererek:- Uzun süre çalışan bir arka plan işi bittiğinde kullanıcılara bildirim gönderilir.
- Kullanıcılara bir sunucunun çevrimdışı olduğunu bildirir.
- Bir müşteri destek görevlisinden, yeni açılan bir müşteri destek kaydıyla ilgilenmesini isteyin.
- Daha önce
spaces.messages.update
ile gönderilmiş iletileri şu şekilde güncelleyin:- Devam eden işlemin durumunu değiştirin.
- Bir görevin atandığı kişiyi veya son tarihi güncelleyin.
- Bir alandaki kullanıcıları
spaces.members.list
ile listeleyerek:- Bir alanda kimlerin olduğunu görün.
- Alan üyeliğinin bir ekipteki herkesi kapsadığını doğrulayın.
Kimlik doğrulaması bir hizmet hesabıyla yapıldığında, Chat uygulamaları hakkında veri almak veya Chat alanında işlem gerçekleştirmek için Chat uygulamalarının alana üye olması gerekir. Örneğin, bir alanın üyelerini listelemek veya alanda mesaj oluşturmak için Chat uygulamasının ilgili alanın üyesi olması gerekir.
Chat uygulamanızın kullanıcı verilerine erişmesi veya kullanıcı adına işlem yapması gerekiyorsa kullanıcı olarak kimlik doğrulaması yapın.
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şlevlerde alan genelinde yetki kullanabilirsiniz.
Chat uygulamalarının ne zaman kimlik doğrulama gerektirdiği ve ne tür kimlik doğrulamanın kullanılacağı hakkında daha fazla bilgi edinmek için Chat API kimlik doğrulama ve yetkilendirmeye genel bakış sayfasındaki Gerekli kimlik doğrulama türleri bölümünü inceleyin.
Ön koşullar
Bu kılavuzdaki örneği çalıştırmak için aşağıdaki önkoşullara ihtiyacınız vardır:
- Google Chat 'e erişimi olan bir Google Workspace hesabı.
- Chat API'nin etkin olduğu bir Google Cloud projesi. Proje oluşturmak ve bir API'yi etkinleştirmek için Proje oluşturma ve API'yi etkinleştirme bölümüne bakın.
- Chat alanında üyeliği olan yayınlanmış bir Chat uygulaması:
- Chat uygulaması oluşturmak ve yayınlamak için Cloud Functions ile Google Chat uygulaması oluşturma başlıklı makaleyi inceleyin.
- Chat alanına Chat uygulaması eklemek için Google Chat'te alanlara veya görüşmelere uygulama ekleme başlıklı makaleyi inceleyin.
Ayrıca, dile özgü aşağıdaki ön koşullara da ihtiyacınız vardır:
Java
- JDK 1.7 veya üzeri
- Maven paket yönetimi aracı
Başlatılmış bir Maven projesi. Yeni bir projeyi başlatmak için komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:
mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
Python
- Python 3.6 veya sonraki sürümler
- pip paket yönetimi aracı
Node.js
Apps Komut Dosyası
- Google Cloud projenize bağlı bir Apps Komut Dosyası projesi. Bir Apps Komut Dosyası projesini başlatmak için Google Apps Komut Dosyası Chat uygulaması hızlı başlangıç kılavuzu sayfasına göz atın.
1. Adım: Google Cloud Console'da bir hizmet hesabı oluşturun
Chat uygulamanızın Google API'lerine erişmek için kullanabileceği bir hizmet hesabı oluşturun.
Hizmet hesabı oluşturma
Hizmet hesabı oluşturmak için şu adımları uygulayın:
Google Cloud Console
- Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.
- Hizmet hesabı oluştur'u tıklayın.
- Hizmet hesabı ayrıntılarını girip Oluştur ve devam et'i tıklayın.
- İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla bilgi için Kaynaklara erişim izni verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.
- Devam'ı tıklayın.
- İsteğe bağlı: Bu hizmet hesabını yönetebilen ve işlem gerçekleştirebilecek kullanıcıları veya grupları girin. Daha fazla bilgi için Hizmet hesabı kimliğine bürünmeyi yönetme başlıklı makaleye bakın.
- Done'ı (Bitti) tıklayın. Hizmet hesabının e-posta adresini not edin.
gcloud CLI
- Hizmet hesabını oluşturun:
gcloud iam service-accounts create
SERVICE_ACCOUNT_NAME
\ --display-name="SERVICE_ACCOUNT_NAME
" - İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla bilgi için Kaynaklara erişim izni verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.
Hizmet hesabı, hizmet hesabı sayfasında görünür. Ardından hizmet hesabı için özel anahtar oluşturun.
Özel anahtar oluşturma
Hizmet hesabı için özel anahtar oluşturmak ve indirmek üzere şu adımları uygulayın:
- Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.
- Hizmet hesabınızı seçin.
- Anahtarlar > Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
- JSON'u seçip Oluştur'u tıklayın.
Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve yeni bir dosya olarak makinenize indirilir. İndirilen JSON dosyasını çalışma dizininize
credentials.json
olarak kaydedin. Dosya, bu anahtarın tek kopyasıdır. Anahtarınızı güvenli bir şekilde nasıl saklayacağınız hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetme konusuna bakın. - Close'u (Kapat) tıklayın.
Hizmet hesapları hakkında daha fazla bilgi için Google Cloud IAM belgelerindeki hizmet hesapları bölümüne bakın.
2. Adım: Google istemci kitaplığını ve diğer bağımlılıkları yükleyin
Proje için gereken Google istemci kitaplığını ve diğer bağımlılıkları yükleyin.
Java
Maven projenize Google istemci kitaplıklarını ve gerekli diğer bağımlılıkları eklemek için projenizin dizininde pom.xml
dosyasını düzenleyin ve aşağıdaki bağımlılıkları ekleyin:
<dependencies>
<!-- ... existing dependencies ... -->
<dependency>
<groupId>com.google.apis</groupId>
<artifactId>google-api-services-chat</artifactId>
<version>v1-rev20230905-2.0.0</version>
</dependency>
<dependency>
<groupId>com.google.auth</groupId>
<artifactId>google-auth-library-oauth2-http</artifactId>
<version>1.19.0</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>
</dependencies>
Python
Python için Google istemci kitaplıklarını henüz yüklemediyseniz komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:
pip3 install --upgrade google-api-python-client google-auth
Node.js
Node.js projenize Google istemci kitaplıklarını eklemek için projenizin dizinine geçin ve komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:
npm install "@googleapis/chat"
Apps Komut Dosyası
Bu örnekte, hizmet hesabı kimlik doğrulamasına yönelik bir JWT jetonu oluşturmak amacıyla Apps Komut Dosyası kitaplığı için OAuth2 kullanılmaktadır. Kitaplığı Apps Komut Dosyası projenize eklemek için:
- Solda, Düzenleyici'yi tıklayın.
- Solda, Kitaplıklar'ın yanındaki Kitaplık ekle'yi tıklayın .
- Komut dosyası kimliğini (
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
) girin. - Ara'yı ve ardından Ekle'yi tıklayın.
Bu örnekte, Google Chat API'yi çağırmak için Advanced Chat hizmeti kullanılmaktadır. Apps Komut Dosyası projeniz için hizmeti etkinleştirmek üzere:
- Solda, Düzenleyici'yi tıklayın.
- Solda, Hizmetler'in yanındaki Hizmet ekle'yi tıklayın.
- Google Chat API'yi seçin.
- Version (Sürüm) bölümünde v1'i seçin.
- Ekle'yi tıklayın.
İstemci kitaplıklarımız tarafından desteklenen herhangi bir dili kullanabilirsiniz.
3. adım: Chat API ile kimlik doğrulamak için hizmet hesabını kullanan bir komut dosyası yazın
Aşağıdaki kod, bir hizmet hesabı kullanarak Chat API ile kimlik doğrulaması yapar ve ardından bir Chat alanına mesaj yayınlar:
Java
- Projenizin dizininde
src/main/java/com/google/chat/app/authsample/App.java
dosyasını açın. App.java
içeriğini şu kodla değiştirin:package com.google.chat.app.authsample; import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport; import com.google.api.client.http.HttpRequestInitializer; import com.google.api.client.json.gson.GsonFactory; import com.google.api.services.chat.v1.HangoutsChat; import com.google.api.services.chat.v1.model.Message; import com.google.auth.http.HttpCredentialsAdapter; import com.google.auth.oauth2.GoogleCredentials; /** * Authenticates with Chat API via service account credentials, * then creates a Chat message. */ public class App { // Specify required scopes. private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot"; // Specify service account details. private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json"; public static void main( String[] args ) { try { // Run app. Message response = App.createChatMessage(); // Print details about the created message. System.out.println(response); } catch (Exception e) { e.printStackTrace(); } } private static Message createChatMessage() throws Exception { // Build the Chat API client and authenticate with the service account. GoogleCredentials credentials = GoogleCredentials.fromStream( App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI)) .createScoped(CHAT_SCOPE); HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials); HangoutsChat chatService = new HangoutsChat.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), requestInitializer) .setApplicationName("auth-sample-app") .build(); // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. String spaceName = "spaces/SPACE_NAME"; // Create a Chat message. Message message = new Message().setText("Hello, world!"); return chatService.spaces().messages().create(spaceName, message).execute(); } }
Kodda,
SPACE_NAME
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.Projenizin dizininde
resources
adlı yeni bir alt dizin oluşturun.Hizmet hesabınız için özel anahtar dosyasının
credentials.json
adında olduğundan emin olun ve dosyayıresources
alt dizinine kopyalayın.Maven'ı özel anahtar dosyasını proje paketine ekleyecek şekilde yapılandırmak için projenizin dizininde
pom.xml
dosyasını düzenleyin ve aşağıdaki yapılandırmayı<build>
bölümüne ekleyin:<build> <!-- ... existing configurations ... --> <resources> <resource> <directory>resources</directory> </resource> </resources> </build>
Maven'i proje paketine bağımlılıkları dahil edecek ve uygulamanızın ana sınıfını yürütecek şekilde yapılandırmak için projenizin dizininde
pom.xml
dosyasını düzenleyin ve<plugins>
bölümüne aşağıdaki yapılandırmayı ekleyin:<plugins> <!-- ... existing configurations ... --> <plugin> <artifactId>maven-assembly-plugin</artifactId> <configuration> <archive> <manifest> <mainClass>com.google.chat.app.authsample.App</mainClass> </manifest> </archive> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> </configuration> </plugin> </plugins>
Python
- Çalışma dizininizde
chat_app_auth.py
adında bir dosya oluşturun. chat_app_auth.py
içine şu kodu ekleyin:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE_NAME with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE_NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result)
Kodda,
SPACE_NAME
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin. Hizmet hesabınız için gizli anahtar dosyasınıncredentials.json
olarak adlandırıldığından emin olun.
Node.js
- Projenizin dizininde
chat_app_auth.js
adında bir dosya oluşturun. chat_app_auth.js
içine şu kodu ekleyin:const chat = require('@googleapis/chat'); async function createMessage() { const auth = new chat.auth.GoogleAuth({ // Specify service account details. keyFilename: 'credentials.json', // Specify required scopes. scopes: ['https://www.googleapis.com/auth/chat.bot'] }); const authClient = await auth.getClient(); // Create the Chat API client and authenticate with the service account. const chatClient = await chat.chat({ version: 'v1', auth: authClient }); // Create a Chat message. const result = await chatClient.spaces.messages.create({ // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. parent: 'spaces/SPACE_NAME', // The message to create. requestBody: { 'text': 'Hello, world!' } }); return result; } // Execute function then print details about the created message. createMessage().then(console.log);
Kodda,
SPACE_NAME
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin. Hizmet hesabınız için gizli anahtar dosyasınıncredentials.json
olarak adlandırıldığından emin olun.
Apps Komut Dosyası
Apps Komut Dosyası düzenleyicisinde
appsscript.json
dosyasını düzenleyin ve hizmet hesabı OAuth jetonunu almak amacıyla harici isteklerde bulunmak için gereken OAuth kapsamını ekleyin:"oauthScopes": [ "https://www.googleapis.com/auth/script.external_request" ]
Aşağıdaki kodu, Apps Komut Dosyası projenizdeki
ChatAppAuth.gs
adlı bir dosyaya kaydedin:// Specify the contents of the file credentials.json. const CREDENTIALS = CREDENTIALS; const SCOPE = 'https://www.googleapis.com/auth/chat.bot'; // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. const PARENT = 'spaces/SPACE_NAME' /** * Authenticates with Chat API via app credentials, then posts a message. */ function createMessageWithAppCredentials() { try { const service = getService_(); if (!service.hasAccess()) { console.error(service.getLastError()); return; } // Specify the message to create. const message = {'text': 'Hello world!'}; // Call Chat API with a service account to create a message. const result = Chat.Spaces.Messages.create( message, PARENT, {}, // Authenticate with the service account token. {'Authorization': 'Bearer ' + service.getAccessToken()}); // Log details about the created message. console.log(result); } catch (err) { // TODO (developer) - Handle exception. console.log('Failed to create message with error %s', err.message); } } /** * Configures the OAuth library to authenticate with the service account. */ function getService_() { return OAuth2.createService(CREDENTIALS.client_email) .setTokenUrl('https://oauth2.googleapis.com/token') .setPrivateKey(CREDENTIALS.private_key) .setIssuer(CREDENTIALS.client_email) .setSubject(CREDENTIALS.client_email) .setScope(SCOPE) .setPropertyStore(PropertiesService.getScriptProperties()); }
Kodda,
CREDENTIALS
değerinicredentials.json
dosyasının içeriğiyle değiştirin.Kodda,
SPACE_NAME
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.
4. Adım: Örneğin tamamını çalıştırın
Çalışma dizininizde örneği derleyip çalıştırın:
Java
mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar
Python
python3 chat_app_auth.py
Node.js
node chat_app_auth.js
Apps Komut Dosyası
Apps Komut Dosyası Düzenleyicisi'nde ChatAppAuth.gs
dosyasını açın
ve Çalıştır'ı tıklayın.
Komut dosyanız, Chat API'ye kimliği doğrulanmış istek gönderir. API, Chat alanında Chat uygulaması olarak mesaj yayınlayarak yanıt verir.
Örnekteki sorunları giderin
Bu bölümde, bu örneği çalıştırmaya çalışırken karşılaşabileceğiniz yaygın sorunlar açıklanmaktadır.
Bu uygulamayı kullanma izniniz yok
Komut dosyasını çalıştırırken şöyle bir hata alabilirsiniz:
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">
Bu hata mesajı, Chat uygulamasının belirtilen Chat alanında Chat mesajları oluşturma izni olmadığı anlamına gelir.
Hatayı çözmek için komut dosyasında belirtilen Chat uygulamasını Chat alanına ekleyin.
İlgili konular
Chat API referans belgelerini inceleyerek Chat API'nin başka neler yapabileceğini öğrenin.