Google Chat uygulaması olarak kimlik doğrulama

Bu kılavuzda, Chat uygulaması adına Google Chat API'ye erişmek için bir hizmet hesabının nasıl oluşturulacağı ve kullanılacağı açıklanmaktadır. İlk olarak, hizmet hesabı oluşturma konusunda size yol gösterir. Ardından, Chat API ile kimlik doğrulamak ve Chat alanında mesaj yayınlamak için hizmet hesabını kullanan bir komut dosyası yazma işlemi gösterilmektedir.

Bir hizmet hesabıyla kimlik doğrulaması yapıldığında, Chat uygulamalarının bir Chat alanında veri almak veya işlem yapmak için alanda üyeliği olmalıdır. Örneğin, bir alanın üyelerini listelemek veya alanda mesaj oluşturmak için Chat uygulamasının alanın bir üyesi olması gerekir. Tek istisna, bir Chat uygulamasının uygulama kimlik doğrulamasıyla alan oluşturmasıdır. Bu durumda uygulama, alanı oluşturur ve ardından otomatik olarak üye olur.

https://www.googleapis.com/auth/chat.app.* ile başlayan adlara sahip yetkilendirme kapsamlarıyla uygulama yetkilendirmesini destekleyen Google Chat API yöntemleri, tek seferlik yönetici onayı gerektirir. https://www.googleapis.com/auth/chat.bot yetkilendirme kapsamıyla uygulama yetkilendirmesini destekleyen Google Chat API yöntemleri için ek onay gerekmez. https://www.googleapis.com/auth/chat.app.* Yetkilendirme kapsamları Geliştirici Önizlemesi'nde kullanılabilir.

Chat uygulamanızın kullanıcı verilerine erişmesi veya kullanıcı adına işlem yapması gerekiyorsa bunun yerine kullanıcı olarak kimlik doğrulama yapın. Alan yöneticisiyseniz bir Chat uygulamasının hizmet hesabını, kullanıcılarınızın verilerine erişmesi için yetkilendirmek üzere alan genelinde yetki verebilirsiniz. Bu sayede, her kullanıcının izin vermesi gerekmez. Daha fazla bilgi için Alan genelinde yetki kullanarak kimlik doğrulama ve yetkilendirme başlıklı makaleyi inceleyin.

Chat uygulamalarının ne zaman kimlik doğrulama gerektirdiği ve ne tür kimlik doğrulaması kullanılacağı hakkında daha fazla bilgi edinmek için Chat API kimlik doğrulama ve yetkilendirmeye genel bakıştaki Gerekli kimlik doğrulama türleri bölümüne bakın.

Ön koşullar

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
  • Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. HTTP hizmetini kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.
  • Chat uygulamasını bir alana ekleyin. Chat uygulamasını eklemek için Google Chat uygulamaları için etkileşimli özellikleri test etme başlıklı makaleyi inceleyin.

Python

Node.js

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 aşağıdaki adımları uygulayın:

Google Cloud konsolu

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

    Hizmet Hesaplarına gidin

  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 rol atayın. Daha ayrıntılı bilgi için Kaynaklara erişim 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önetebilecek ve bu hesapta işlem yapabilecek kullanıcıları veya grupları girin. Daha fazla bilgi için Hizmet hesabı kimliğine bürünmeyi yönetme başlıklı makaleyi inceleyin.
  7. Bitti'yi 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 rol atayın. Daha ayrıntılı bilgi için Kaynaklara erişim 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şturun

Hizmet hesabı için özel anahtar oluşturmak ve indirmek üzere aşağıdaki adımları uygulayın:

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

    Hizmet Hesaplarına gidin

  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 makinenize yeni bir dosya olarak indirilir. İndirilen JSON dosyasını çalışma dizininizde credentials.json olarak kaydedin. Bu dosya, bu anahtarın tek kopyasıdır. Anahtarınızı güvenli şekilde nasıl depolayacağınız hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetme başlıklı makaleyi inceleyin.

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

Ardından, bu hizmet hesabı için Google Workspace Marketplace uyumlu bir OAuth istemcisi oluşturun.

Yönetici onayı alma

Geliştirici önizlemesi kapsamında sunulan ve https://www.googleapis.com/auth/chat.app.* ile başlayan bir yetkilendirme kapsamını kullanmak için Chat uygulamanızın tek seferlik yönetici onayı alması gerekir.

https://www.googleapis.com/auth/chat.bot yetkilendirme kapsamını kullanmak için yönetici onayı gerekmez.

Yönetici onayı almak için Chat uygulamanızın hizmet hesabını aşağıdaki bilgilerle hazırlamanız gerekir:

  • Google Workspace Marketplace ile uyumlu bir OAuth istemcisi.
  • Google Workspace Marketplace SDK'sında uygulama yapılandırması.

Google Workspace Marketplace ile uyumlu bir OAuth istemcisi oluşturma

Google Workspace Marketplace uyumlu bir OAuth istemcisi oluşturmak için şu adımları uygulayın:

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

    Hizmet Hesaplarına gidin

  2. Chat uygulamanız için oluşturduğunuz hizmet hesabını tıklayın.

  3. Gelişmiş ayarlar'ı tıklayın.

  4. Google Workspace Marketplace uyumlu OAuth istemcisi oluştur'u tıklayın.

  5. Devam'ı tıklayın.

Google Workspace Marketplace ile uyumlu bir OAuth istemcisinin oluşturulduğunu belirten bir onay mesajı görünür.

Google Workspace Marketplace SDK'sında Chat uygulamasını yapılandırma

Google Workspace Marketplace SDK'sında Chat uygulamasını yapılandırmak için aşağıdaki adımları uygulayın:

  1. Google Cloud konsolunda, Google Workspace Marketplace SDK'sını etkinleştirin.

    Google Workspace Marketplace SDK'sını etkinleştirme

  2. Google Cloud Console'da Menü > API'ler ve Hizmetler > Etkin API'ler ve hizmetler > Google Workspace Marketplace SDK'sı > Uygulama Yapılandırması'na gidin.

    Uygulama Yapılandırması'na gidin

  3. Uygulama Yapılandırması sayfasını tamamlayın. Sohbet uygulamanızı nasıl yapılandıracağınız, hedef kitlenizin kim olduğuna ve diğer faktörlere bağlıdır. Uygulama yapılandırma sayfasını tamamlama konusunda yardım almak için Uygulamanızı Google Workspace Marketplace SDK'sında yapılandırma bölümünü inceleyin. Bu kılavuzun amaçları doğrultusunda aşağıdaki bilgileri girin:

    1. Uygulama görünürlüğü bölümünde Gizli'yi seçin.
    2. Yükleme ayarları bölümünde Bağımsız + yönetici yükleme'yi seçin.
    3. Uygulama entegrasyonları bölümünde Chat uygulaması'nı seçin.

    4. OAuth kapsamları bölümüne, Chat uygulamanızın kullandığı tüm kimlik doğrulama kapsamlarını girin.

    5. Geliştirici bilgileri bölümünde Geliştirici adınızı, Geliştirici web sitesi URL'nizi ve Geliştirici e-postanızı girin.

    6. Taslağı kaydet'i tıklayın.

Yönetici onayı alma

Hizmet hesabınız yönetici onayı alacak şekilde yapılandırıldığına göre Chat uygulamaları için yetkilendirmeyi ayarlama bölümündeki adımları uygulayarak onay verebilecek bir Google Workspace yöneticisinden hizmeti alın.

2. adım: Google istemci kitaplığını ve diğer bağımlılıkları yükleme

Google istemci kitaplığını ve proje için gereken diğer bağımlılıkları yükleyin.

Java

Maven projenize Google istemci kitaplıklarını ve diğer gerekli bağımlılıkları eklemek için projenizin dizinindeki 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

Google istemci kitaplıklarını Node.js projenize eklemek için projenizin dizine 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ı için JWT jetonu oluşturmak üzere Apps Script için OAuth2 kitaplığı kullanılır. Kitaplığı Apps Script projenize eklemek için:

  1. Sol kısımdan 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ı, ardından Ekle'yi tıklayın.

Bu örnekte, Google Chat API'yi çağırmak için Advanced Chat hizmeti kullanılmaktadır. Apps Script projeniz için hizmeti etkinleştirmek üzere:

  1. Sol kısımdan Düzenleyici'yi tıklayın.
  2. Sol tarafta, Hizmetler'in yanındaki Hizmet ekle'yi tıklayın.
  3. Google Chat API'yi seçin.
  4. 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 tüm dilleri 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 gönderir:

Java

  1. Projenizin dizininde src/main/java/com/google/chat/app/authsample/App.java dosyasını açın.

  2. App.java içindeki içeriği aşağıdaki 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 using 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 bir 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ın özel anahtar dosyasının credentials.json olarak adlandırıldığından emin olun ve dosyayı resources alt dizinine kopyalayın.

  6. Maven'i, özel anahtar dosyasını proje paketine dahil edecek şekilde yapılandırmak için projenizin dizinindeki pom.xml dosyasını düzenleyin ve <build> bölümüne aşağıdaki yapılandırmayı ekleyin:

    <build>
  <!-- ... existing configurations ... -->
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>

  7. Maven'i, bağımlılıkları proje paketine dahil edecek ve uygulamanızın ana sınıfını çalıştıracak şekilde yapılandırmak için projenizin dizinindeki 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 adlı bir dosya oluşturun.

  2. chat_app_auth.py dosyasına aşağıdaki 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.
creds = 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=creds)

# 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 bir alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin. Hizmet hesabınızın özel anahtar dosyasının adının credentials.json olduğundan emin olun.

Node.js

  1. Projenizin dizininde chat_app_auth.js adlı bir dosya oluşturun.

  2. Aşağıdaki kodu chat_app_auth.js bölümüne 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 bir alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin. Hizmet hesabınızın özel anahtar dosyasının adının credentials.json olduğundan emin olun.

Apps Komut Dosyası

  1. Apps Script düzenleyicisinde appsscript.json dosyasını düzenleyin ve hizmet hesabı OAuth jetonunu almak için harici isteklerde bulunmak üzere gereken OAuth kapsamını ekleyin:

      "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]

  2. Aşağıdaki kodu Apps Komut Dosyası projenizde 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 using 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 öğesini 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 bir 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üzenleyici'de ChatAppAuth.gs dosyasını açın ve Çalıştır'ı tıklayın.

Komut dosyanız, Chat API'ye kimliği doğrulanmış bir istek gönderir. Bu istek, Chat uygulaması olarak bir Chat alanında mesaj yayınlayarak yanıtlanır.

Örnekle ilgili sorunları giderme

Bu bölümde, bu örneği çalıştırmaya çalışırken karşılaşabileceğiniz yaygın sorunlar açıklanmaktadır.

Bu uygulamayı kullanmanıza izin verilmiyor

Komut dosyasını çalıştırırken şu hatayı 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 mesajı oluşturma izninin olmadığı anlamına gelir.

Hatayı çözmek için komut dosyasında belirtilen Chat uygulamasını Chat alanına ekleyin.

Yönetici, bu işlem için uygulamaya gerekli OAuth yetkilendirme kapsamını vermelidir

Komut dosyasını çalıştırırken şu hatayı alabilirsiniz:

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">

Bu hata mesajı, bir Google Workspace yöneticisinin Chat uygulamasına https://www.googleapis.com/auth/chat.app.* ile başlayan bir adla başlayan yetkilendirme kapsamlarını kullanması için henüz tek seferlik onay vermediği anlamına gelir.

Hatayı çözmek için:

  • Google Workspace yöneticisinden Chat uygulamanıza onay vermesini isteyin. Chat uygulaması mantığınızda bu hatayı ele alırken, Chat uygulamasının istenen işlemi gerçekleştirmek için yönetici onayına ihtiyacı olduğunu belirten bir mesaj gönderebilirsiniz. Örneğin: To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
  • Google Chat API yöntemi, yönetici onayı gerektirmeyen https://www.googleapis.com/auth/chat.bot yetkilendirme kapsamını destekliyorsa bunun yerine bu yöntemi kullanabilirsiniz. Bir yöntemin hangi yetkilendirme kapsamlarını desteklediğini kontrol etmek için Google Chat API referans dokümanlarına bakın.