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

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

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

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

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

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

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

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

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

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

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

חשבון Google Workspace עם גישה ל-Google Chat .
פרויקט ב-Google Cloud עם Chat API מופעל. במאמר יצירת פרויקט והפעלת ה-API מוסבר איך יוצרים פרויקט ומפעילים API.
אפליקציית Chat שפורסמה עם מינוי למרחב משותף ב-Chat:
- במאמר איך יוצרים אפליקציות ל-Google Chat בעזרת Cloud Functions מוסבר איך יוצרים ומפרסמים אפליקציית Chat.
- במאמר הוספת אפליקציות למרחבים משותפים או לשיחות ב-Google Chat מוסבר איך מוסיפים אפליקציית Chat למרחב משותף ב-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. תוכלו להיעזר במדריך למתחילים של אפליקציית Google Apps Script Chat כדי לאתחל פרויקט ב-Apps Script.

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

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

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

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

מסוף Google Cloud

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

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

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

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

Java

כדי להוסיף לפרויקט Maven את ספריות הלקוח של Google ויחסי תלות נדרשים אחרים, עורכים את הקובץ 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.
לוחצים על חיפוש ואז על הוספה.

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

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

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

שלב 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 בשם של מרחב משותף, שאפשר לקבל מ-method 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 בשם של מרחב משותף, שאפשר לקבל מ-method 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 בשם של מרחב משותף, שאפשר לקבל מ-method 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 בשם של מרחב משותף, שאפשר לקבל מ-method 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 שמצוינת בסקריפט.

מידע נוסף על מה עוד אפשר לעשות ב-Chat API מופיע במאמרי העזרה של 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

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

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

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