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

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

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

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

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

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

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

במאמר סוגי האימות הנדרש בסקירה הכללית על אימות והרשאות ב-Chat API מוסבר מתי צריך לבצע אימות באפליקציות ל-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

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

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

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

כדי ליצור חשבון שירות:

מסוף Google Cloud

  1. במסוף Google Cloud, נכנסים לתפריט > IAM & Admin > Service Accounts.

    כניסה לדף Service Accounts

  2. לוחצים על יצירת חשבון שירות.
  3. ממלאים את הפרטים של חשבון השירות ולוחצים על Create and continue (יצירה והמשך).
  4. אופציונלי: כדי להעניק גישה למשאבים של הפרויקט ב-Google Cloud, צריך להקצות תפקידים לחשבון השירות. לפרטים נוספים אפשר לעיין במאמר הענקה, שינוי וביטול של גישה למשאבים.
  5. לוחצים על המשך.
  6. אופציונלי: יש להזין משתמשים או קבוצות שיוכלו לנהל ולבצע פעולות באמצעות חשבון השירות הזה. פרטים נוספים זמינים במאמר ניהול התחזות לחשבון שירות.
  7. לוחצים על סיום. רושמים לעצמכם את כתובת האימייל של חשבון השירות.

CLI של gcloud

  1. יוצרים את חשבון השירות:
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name="SERVICE_ACCOUNT_NAME"
  2. אופציונלי: כדי להעניק גישה למשאבים של הפרויקט ב-Google Cloud, צריך להקצות תפקידים לחשבון השירות. לפרטים נוספים אפשר לעיין במאמר הענקה, שינוי וביטול של גישה למשאבים.

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > IAM & Admin > Service Accounts.

    כניסה לדף Service Accounts

  2. בוחרים את חשבון השירות.
  3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
  4. בוחרים באפשרות JSON ולוחצים על יצירה.

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

  5. לוחצים על Close.

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

שלב 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:

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

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

  1. בצד ימין, לוחצים על עורך .
  2. מימין, ליד שירותים, לוחצים על הוספת שירות .
  3. בוחרים באפשרות Google Chat API.
  4. בקטע Version, בוחרים באפשרות v1.
  5. לוחצים על הוספה.

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

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

הקוד הבא מבצע אימות ב-Chat API באמצעות חשבון שירות, ואז שולח הודעה במרחב המשותף ב-Chat:

Java

  1. בספריית הפרויקט, פותחים את הקובץ src/main/java/com/google/chat/app/authsample/App.java.
  2. מחליפים את התוכן שבקובץ 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();
        }
    }
    
  3. מחליפים את SPACE_NAME בשם של המרחב המשותף בקוד. אפשר לקבל אותו מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף.

  4. יוצרים ספריית משנה חדשה בשם resources בספריית הפרויקט.

  5. מוודאים ששם המפתח הפרטי של חשבון השירות הוא credentials.json, ומעתיקים אותו לספריית המשנה resources.

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

    <build>
      <!-- ... existing configurations ... -->
      <resources>
        <resource>
          <directory>resources</directory>
        </resource>
      </resources>
    </build>
    
  7. כדי להגדיר את 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

  1. בספריית העבודה, יוצרים קובץ בשם chat_app_auth.py.
  2. יש לכלול את הקוד הבא ב-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)
    
  3. מחליפים את SPACE_NAME בשם של המרחב המשותף בקוד. אפשר לקבל אותו מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף. מוודאים ששם המפתח הפרטי של חשבון השירות שלכם הוא credentials.json.

Node.js

  1. בספריית הפרויקט, יוצרים קובץ בשם chat_app_auth.js.
  2. יש לכלול את הקוד הבא ב-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);
    
  3. מחליפים את SPACE_NAME בשם של המרחב המשותף בקוד. אפשר לקבל אותו מה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף. מוודאים ששם המפתח הפרטי של חשבון השירות שלכם הוא credentials.json.

Apps Script

  1. בעורך Apps Script, עורכים את הקובץ appsscript.json ומוסיפים את היקף ה-OAuth שדרוש כדי לבצע בקשות חיצוניות כדי לקבל את אסימון ה-OAuth של חשבון השירות:

      "oauthScopes": [
        "https://www.googleapis.com/auth/script.external_request"
      ]
    
  2. שומרים את הקוד הבא בקובץ בשם 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());
    }
    
  3. בקוד, מחליפים את CREDENTIALS בתוכן הקובץ credentials.json.

  4. מחליפים את 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. ה-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.