דף זה תורגם על ידי 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 צריכה להיות חלק מהמרחב המשותף בעצמה.

אם אפליקציית 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. כדי לאתחל פרויקט Apps Script, קראו את המדריך למתחילים של אפליקציית Chat ל-Google 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.

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

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

במסמכי העזר של 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

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

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

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