Google Chat uygulaması olarak kimlik doğrulama

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:

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

  • Node.js
  • npm paket yönetimi aracı
  • Başlatılmış bir Node.js projesi. Yeni bir projeyi başlatmak için yeni bir klasör oluşturup bu klasöre geçiş yapın ve ardından komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:

    npm init
    

Apps Komut Dosyası

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

  1. Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

    Hizmet Hesapları'na git

  2. Hizmet hesabı oluştur'u tıklayın.
  3. Hizmet hesabı ayrıntılarını girip Oluştur ve devam et'i tıklayın.
  4. İ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.
  5. Devam'ı tıklayın.
  6. İ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.
  7. Done'ı (Bitti) tıklayın. Hizmet hesabının e-posta adresini not edin.

gcloud CLI

  1. Hizmet hesabını oluşturun:
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name="SERVICE_ACCOUNT_NAME"
  2. İ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:

  1. Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

    Hizmet Hesapları'na git

  2. Hizmet hesabınızı seçin.
  3. Anahtarlar > Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
  4. 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.

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

  1. Solda, Düzenleyici'yi tıklayın.
  2. Solda, Kitaplıklar'ın yanındaki Kitaplık ekle'yi tıklayın .
  3. Komut dosyası kimliğini (1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF) girin.
  4. 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:

  1. Solda, Düzenleyici'yi tıklayın.
  2. Solda, Hizmetler'in yanındaki Hizmet ekle'yi tıklayın.
  3. Google Chat API'yi seçin.
  4. Version (Sürüm) bölümünde v1'i seçin.
  5. 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

  1. Projenizin dizininde src/main/java/com/google/chat/app/authsample/App.java dosyasını açın.
  2. 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();
        }
    }
    
  3. Kodda, SPACE_NAME değerini Chat API'deki spaces.list yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.

  4. Projenizin dizininde resources adlı yeni bir alt dizin oluşturun.

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

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

  1. Çalışma dizininizde chat_app_auth.py adında bir dosya oluşturun.
  2. 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)
    
  3. Kodda, SPACE_NAME değerini Chat API'deki spaces.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ın credentials.json olarak adlandırıldığından emin olun.

Node.js

  1. Projenizin dizininde chat_app_auth.js adında bir dosya oluşturun.
  2. 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);
    
  3. Kodda, SPACE_NAME değerini Chat API'deki spaces.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ın credentials.json olarak adlandırıldığından emin olun.

Apps Komut Dosyası

  1. 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"
      ]
    
  2. 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());
    }
    
  3. Kodda, CREDENTIALS değerini credentials.json dosyasının içeriğiyle değiştirin.

  4. Kodda, SPACE_NAME değerini Chat API'deki spaces.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.

Chat API referans belgelerini inceleyerek Chat API'nin başka neler yapabileceğini öğrenin.