דף זה תורגם על ידי Cloud Translation API.

אימות כאפליקציית Google Chat

במדריך הזה מוסבר איך להגדיר חשבון שירות ולהשתמש בו כדי לגשת אל Google Chat API בשם אפליקציית Chat. קודם כל, מוסבר בו איך ליצור חשבון שירות. לאחר מכן הוא ידגים איך לכתוב סקריפט שמשתמש בחשבון השירות כדי לבצע אימות עם Chat להשתמש ב-API ולפרסם הודעה במרחב ב-Chat.

אפליקציות צ'אט יכולות להשתמש בחשבונות שירות כדי לבצע אימות במהלך התקשרות אסינכרונית ו-Google Chat API, כדי שהוא יוכל:

שליחת הודעות ל-Google Chat באמצעות spaces.messages.create to:
- שליחת הודעה למשתמשים כשמשימה ממושכת ברקע מסתיימת.
- שליחת התראה למשתמשים על כך שהשרת התנתק
- מבקשים מנציג תמיכת לקוחות לטפל בפניית לקוח שנפתחה לאחרונה.
עדכון הודעות שנשלחו בעבר באמצעות spaces.messages.update to:
- שינוי הסטטוס של 'פעולה מתמשכת'.
- לעדכן את מקבל ההקצאה או את תאריך היעד של המשימה.
הצגת רשימה של המשתמשים במרחבים משותפים עם spaces.members.list עד:
- איך רואים מי במרחבים משותפים.
- מוודאים שהמרחב המשותף כולל את כל חברי הצוות.

כשהאימות בוצע באמצעות חשבון שירות, כדי לקבל נתונים על פעולות או לבצע אותן במרחבים משותפים ב-Chat, צריכה להיות לכם גישה לתכונה 'אפליקציות צ'אט'. לדוגמה, כדי ברשימת המשתתפים במרחב המשותף, או כדי ליצור הודעה במרחב משותף, אפליקציית Chat צריכה שהוא יהיה חבר במרחב המשותף.

אם אפליקציית Chat צריכה לגשת לנתוני משתמשים או לבצע פעולות במקום זאת, בצע אימות כמשתמש.

מנהלי דומיין יכולים להעניק האצלת סמכויות ברמת הדומיין כדי להעניק הרשאה לחשבון שירות של אפליקציה לגשת אל המשתמשים שלך נתונים ללא דרישה מכל משתמש להביע הסכמה. אחרי שמגדירים הענקת גישה ברמת הדומיין, אפשר ביצוע קריאות ל-API באמצעות חשבון השירות כדי להתחזות לחשבון משתמש. למרות שחשבון שירות משמש הענקת גישה ברמת הדומיין התחזות למשתמש, ולכן נחשב לאימות משתמש. כל פונקציונליות שמחייבת משתמש תוכלו להשתמש בהענקת גישה ברמת הדומיין.

למידע נוסף על מקרים שבהם אפליקציות ל-Chat מחייבות אימות באיזה סוג של אימות להשתמש, סוגי האימות הנדרש בסקירה הכללית על אימות והרשאה של Chat API.

דרישות מוקדמות

כדי להריץ את הדוגמה במדריך הזה, צריך לעמוד בדרישות המוקדמות הבאות:

א' Google Workspace חשבון עם גישה אל Google Chat .
פרויקט ב-Google Cloud עם Chat API מופעל. כדי ליצור פרויקט ולהפעיל API, יוצרים פרויקט ומפעילים את ה-API.
אפליקציית Chat שפורסמה עם מינוי למרחב משותף ב-Chat:
- כדי ליצור ולפרסם אפליקציית Chat: איך מפתחים אפליקציות של Google Chat באמצעות Cloud Functions
- כדי להוסיף אפליקציית Chat למרחב משותף ב-Chat: איך מוסיפים אפליקציות למרחבים משותפים או לשיחות ב-Google Chat

בנוסף, צריך לעמוד בדרישות המוקדמות הבאות שספציפיות לשפה:

Java

JDK 1.7 ומעלה
ה-Maven כלי לניהול חבילות

פרויקט Maven מאותחל. כדי לאתחל פרויקט חדש, צריך להריץ את הפקודה הפקודה הבאה בממשק שורת הפקודה:

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 ומעלה
תמונה של PIP כלי לניהול חבילות

Node.js

Node.js
ה-npm כלי לניהול חבילות
פרויקט Node.js מאותחל. כדי לאתחל פרויקט חדש, צריך ליצור לעבור לתיקייה חדשה ואז להריץ את הפקודה הבאה בממשק שורת הפקודה:
```
npm init
```

Apps Script

פרויקט Apps Script שמחובר לפרויקט שלכם ב-Google Cloud. שפת תרגום לאתחל פרויקט Apps Script, המדריך למתחילים של אפליקציית Google Apps Script Chat.

שלב 1: יצירת חשבון שירות במסוף Google Cloud

איך יוצרים חשבון שירות שאפליקציית Chat תוכל להשתמש בו? גישה לממשקי ה-API של Google.

יצירה של חשבון שירות

כדי ליצור חשבון שירות, צריך לבצע את השלבים הבאים:

מסוף Google Cloud

במסוף Google Cloud, נכנסים לתפריט > IAM & אדמין > חשבונות שירות.
לדף Service accounts
לוחצים על Create service account.
ממלאים את פרטי חשבון השירות ולוחצים על Create and continue.
הערה: כברירת מחדל, Google יוצרת מזהה ייחודי של חשבון שירות. אם רוצים משנים את המזהה, משנים את המזהה בשדה 'מזהה חשבון שירות'.
אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים של הפרויקט ב-Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
לוחצים על המשך.
אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל ולבצע פעולות באמצעות חשבון השירות הזה. פרטים נוספים זמינים במאמר ניהול התחזות לחשבון שירות.
לוחצים על סיום. רושמים בצד את כתובת האימייל של חשבון השירות.

CLI של gcloud

יוצרים את חשבון השירות:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים של הפרויקט ב-Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.

חשבון השירות מופיע בדף של חשבון השירות. בשלב הבא, יוצרים חשבון של חשבון השירות.

יצירת מפתח פרטי

כדי ליצור ולהוריד מפתח פרטי לחשבון השירות, פועלים לפי השלבים הבאים:

במסוף Google Cloud, נכנסים לתפריט > IAM & אדמין > חשבונות שירות.
לדף Service accounts
בוחרים את חשבון השירות.
לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
בוחרים באפשרות JSON ולאחר מכן לוחצים על יצירה.
המערכת יוצרת את זוג המפתחות הציבורי/הפרטי החדש ומורידה אותו אל כקובץ חדש. שומרים את קובץ ה-JSON שהורדתם בתור credentials.json בחשבון ספריית העבודה. הקובץ הזה הוא העותק היחיד של המפתח הזה. מידע על אופן האחסון את המפתח שלכם באופן מאובטח, תוכלו לראות ניהול מפתחות של חשבונות שירות.
לוחצים על סגירה.

מידע נוסף על חשבונות שירות זמין במאמר חשבונות שירות במאמרי העזרה של Google Cloud IAM.

שלב 2: מתקינים את ספריית הלקוח של Google ויחסי תלות אחרים

התקנת ספריית הלקוח של Google ויחסי תלות אחרים הנדרשים לפרויקט.

Java

כדי להוסיף את ספריות הלקוח של Google ויחסי תלות נדרשים אחרים בפרויקט Maven, עורכים את הקובץ pom.xml בספריית הפרויקט ומוסיפים את הקוד של יחסי התלות הבאים:

<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

אם עדיין לא התקנתם את ספריות הלקוח של Google ל-Python, עליכם להריץ את הפקודה את הפקודה הבאה בממשק שורת הפקודה:

pip3 install --upgrade google-api-python-client google-auth

Node.js

כדי להוסיף את ספריות הלקוח של Google לפרויקט Node.js, עוברים אל של הפרויקט ומריצים את הפקודה הבאה בממשק שורת הפקודה:

npm install "@googleapis/chat"

Apps Script

הדוגמה הזו משתמשת ב OAuth2 לספריית Apps Script כדי ליצור אסימון JWT לאימות של חשבון שירות. כדי להוסיף את הספרייה לפרויקט Apps Script שלכם:

בצד ימין, לוחצים על עריכה .
בצד ימין, לצד ספריות, לוחצים על הוספת ספרייה. .
מזינים את מזהה הסקריפט 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
לוחצים על חיפוש ואז על הוספה.

הדוגמה הזו משתמשת ב שירות Chat מתקדם כדי לקרוא ל-Google Chat API. כדי להפעיל את השירות עבור פרויקט Apps Script:

בצד ימין, לוחצים על עריכה .
בצד ימין, לצד שירותים, לוחצים על הוספת שירות. .
בוחרים באפשרות Google Chat API.
ב-Version, בוחרים באפשרות v1.
לוחצים על הוספה.

אפשר להשתמש בכל שפה שנתמכת על ידי ספריות לקוח.

שלב 3: כותבים סקריפט שמשתמש בחשבון השירות כדי לבצע אימות עם Chat API

הקוד הבא מבצע אימות באמצעות להשתמש ב-Chat API באמצעות חשבון שירות, ולאחר מכן מפרסם הודעה במרחב ב-Chat:

Java

בספריית הפרויקט, פותחים את הקובץ src/main/java/com/google/chat/app/authsample/App.java

מחליפים את התוכן שב-App.java בקוד הבא:

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();
    }
}

בקוד, מחליפים את SPACE_NAME ברווח את השם הזה, שאפשר לקבל דרך spaces.list ב-Chat API או מכתובת ה-URL של מרחב משותף.
יוצרים ספריית משנה חדשה בשם resources בספריית הפרויקט.
מוודאים שלקובץ המפתח הפרטי של חשבון השירות יש שם credentials.json ומעתיקים אותו לספריית המשנה resources.
כדי להגדיר את Maven כך שיכלול את קובץ המפתח הפרטי בחבילת הפרויקט: יש לערוך את הקובץ pom.xml בספריית הפרויקט ולהוסיף את הפרטים הבאים את התצורה בקטע <build>:
```
<build>
  
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>
```

להגדיר את Maven כך שיכלול את יחסי התלות בחבילת הפרויקט, כדי להריץ את המחלקה הראשית של האפליקציה, צריך לערוך את הקובץ pom.xml דרך של הפרויקט ולהוסיף את ההגדרות הבאות הקטע <plugins>:

<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

בספריית העבודה, יוצרים קובץ בשם chat_app_auth.py.

צריך לכלול את הקוד הבא ב-chat_app_auth.py:

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)

בקוד, מחליפים את SPACE_NAME ברווח את השם הזה, שאפשר לקבל דרך spaces.list ב-Chat API או מכתובת ה-URL של מרחב משותף. צריך לוודא שהאלמנטים מפתח פרטי לחשבון השירות שלך הוא credentials.json.

Node.js

בספריית הפרויקט, יוצרים קובץ בשם chat_app_auth.js.

צריך לכלול את הקוד הבא ב-chat_app_auth.js:

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);

בקוד, מחליפים את SPACE_NAME ברווח את השם הזה, שאפשר לקבל דרך spaces.list ב-Chat API או מכתובת ה-URL של מרחב משותף. צריך לוודא שהאלמנטים מפתח פרטי לחשבון השירות שלך הוא credentials.json.

Apps Script

בעורך Apps Script, עורכים את הקובץ appsscript.json ולהוסיף את היקף ה-OAuth שנדרש כדי לשלוח בקשות חיצוניות כדי לקבל אסימון OAuth של חשבון שירות:
```
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
```

שמירת הקוד הבא בקובץ בשם ChatAppAuth.gs ב- לפרויקט שלך ב-Apps Script:

// 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());
}

בקוד, מחליפים את CREDENTIALS עם של הקובץ credentials.json.
בקוד, מחליפים את SPACE_NAME ברווח את השם הזה, שאפשר לקבל דרך spaces.list ב-Chat API או מכתובת ה-URL של מרחב משותף.

שלב 4: מריצים את הדוגמה המלאה

בספריית העבודה, יוצרים ומריצים את הדוגמה:

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 Script

פותחים את הקובץ ChatAppAuth.gs ב-Apps Script Editor ואז לוחצים על Run.

הסקריפט שלכם שולח בקשה מאומתת Chat API, שמגיב באמצעות פרסום הודעה במרחב ב-Chat בתור אפליקציית Chat.

פתרון בעיות בדוגמה

בקטע הזה מתוארות בעיות נפוצות שבהן אתם עשויים להיתקל במהלך הניסיון כדי להריץ את הדוגמה הזו.

אין לך הרשאה להשתמש באפליקציה הזו

במהלך הרצת הסקריפט, ייתכן שתתקבל הודעת השגיאה הבאה:

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

הודעת השגיאה הזו לא מופיעה הרשאה ליצור הודעות צ'אט בקבוצה שצוינה מרחב ב-Chat.

כדי לפתור את השגיאה, מוסיפים את אפליקציית Chat למרחב המשותף ב-Chat. שצוינו בסקריפט.

מה עוד אפשר לעשות ב-Chat API? מאמרי עזרה

אימות כאפליקציית Google Chat

דרישות מוקדמות

Java

Python

Node.js

Apps Script

שלב 1: יצירת חשבון שירות במסוף Google Cloud

יצירה של חשבון שירות

מסוף Google Cloud

CLI של gcloud

יצירת מפתח פרטי

שלב 2: מתקינים את ספריית הלקוח של Google ויחסי תלות אחרים

Java

Python

Node.js

Apps Script

שלב 3: כותבים סקריפט שמשתמש בחשבון השירות כדי לבצע אימות עם Chat API

Java

Python

Node.js

Apps Script

שלב 4: מריצים את הדוגמה המלאה

Java

Python

Node.js

Apps Script

פתרון בעיות בדוגמה

אין לך הרשאה להשתמש באפליקציה הזו

נושאים קשורים