אימות והרשאה כמשתמש ב-Google Chat

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

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

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

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

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

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

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

לכל האפליקציות שמשתמשות ב-OAuth 2.0 נדרשת הגדרה של מסך הסכמה, אבל צריך לרשום רק את היקפי ההרשאות לאפליקציות שבהן משתמשים אנשים מחוץ לארגון שלכם ב-Google Workspace.

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > OAuth Screen (מסך הסכמה ל-OAuth).

    מעבר למסך ההסכמה של OAuth

  2. בוחרים את סוג המשתמש באפליקציה ולוחצים על יצירה.

  3. ממלאים את טופס ההרשמה לאפליקציה ולוחצים על שמירה והמשך.

  4. לוחצים על הוספה או הסרה של היקפים. מוסיפים ומאמתים את היקפי ההרשאות הנדרשים לאפליקציה, לוחצים על Update ואז על Save and Continue (שמירה והמשך).

  5. בודקים את הסיכום של רישום האפליקציה. לוחצים על Edit כדי לערוך שינויים, או על Back to Dashboard.

שלב 2: יצירת פרטי כניסה של מזהה לקוח ב-OAuth במסוף Google Cloud

כדי לבצע אימות כמשתמש קצה ולגשת לנתוני המשתמשים באפליקציה שלך, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה לקוח משמש לזיהוי של אפליקציה יחידה לשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות – כמו Android, iOS ו-Web – צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.

יצירת פרטי כניסה של מזהה לקוח ב-OAuth

כדי לקבל הוראות ספציפיות ליצירת מזהה לקוח OAuth, צריך לבחור את סוג האפליקציה:

אפליקציית אינטרנט

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > אפליקציית אינטרנט.
  4. בשדה שם, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. מוסיפים מזהי URI מורשים שקשורים לאפליקציה:
    • אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות JavaScript מורשים, לוחצים על הוספת URI. לאחר מכן מזינים URI שישמש לבקשות דפדפן. מזהה את הדומיינים שמהם האפליקציה שלך יכולה לשלוח בקשות API לשרת OAuth 2.0.
    • אפליקציות בצד השרת (Java, Python ועוד) – בקטע URI Authorized redirect URIs לוחצים על הוספת URI. לאחר מכן צריך להזין URI של נקודת קצה (endpoint) שאליו שרת OAuth 2.0 יכול לשלוח תגובות.
  6. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.

    יש לשים לב ל-Client-ID. סודות לקוח לא משמשים לאפליקציות אינטרנט.

  7. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.

Android

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > Android.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'שם החבילה', מזינים את שם החבילה מהקובץ AndroidManifest.xml.
  6. בשדה 'טביעת אצבע לאישור SHA-1', מזינים את טביעת האצבע לאישור SHA-1.
  7. לוחצים על יצירה. מופיע המסך שנוצר על ידי לקוח OAuth, ומוצג בו מזהה הלקוח החדש שלכם.
  8. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע 'מזהי לקוחות ב-OAuth 2.0'.

iOS

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > iOS.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'מזהה החבילה', מזינים את מזהה החבילה כפי שמופיע בקובץ Info.plist של האפליקציה.
  6. אופציונלי: אם האפליקציה שלכם מופיעה ב-Apple App Store, מזינים את המזהה שלה ב-App Store.
  7. אופציונלי: בשדה 'מזהה צוות' מזינים את המחרוזת הייחודית בת 10 תווים, שנוצרה על ידי Apple ומוקצית לצוות שלכם.
  8. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  9. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע 'מזהי לקוחות ב-OAuth 2.0'.

אפליקציית Chrome

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > אפליקציית Chrome.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'מזהה אפליקציה', מזינים את מחרוזת המזהה הייחודית של האפליקציה, שמורכבת מ-32 תווים. ערך המזהה הזה מופיע בכתובת ה-URL של האפליקציה בחנות האינטרנט של Chrome ובמרכז השליטה למפתחים של חנות האינטרנט של Chrome.
  6. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  7. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע 'מזהי לקוחות ב-OAuth 2.0'.

אפליקציה לשולחן העבודה

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > אפליקציה למחשב.
  4. בשדה שם, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  6. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.

טלוויזיות והתקני קלט עם הגבלות

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > טלוויזיות והתקני קלט מוגבלים.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  6. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע 'מזהי לקוחות ב-OAuth 2.0'.

Universal Windows Platform (UWP)‎

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. לוחצים על סוג האפליקציה > Universal Windows Platform (UWP).
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'מזהה חנות', מזינים את ערך מזהה Microsoft Store הייחודי של האפליקציה, באורך 12 תווים. המזהה הזה נמצא בכתובת ה-URL של האפליקציה ב-Microsoft Store ובמרכז השותפים.
  6. לוחצים על יצירה. מוצג המסך 'לקוח OAuth שנוצר', ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  7. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע 'מזהי לקוחות ב-OAuth 2.0'.

יש להוריד את קובץ ה-JSON של סוד הלקוח

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. בקטע מזהי לקוחות ב-OAuth 2.0, לוחצים על מזהה הלקוח שיצרתם.

  3. לוחצים על Download JSON.

  4. שומרים את הקובץ בשם client_secrets.json.

שלב 3: מתקינים את ספריית הלקוח של 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.oauth-client</groupId>
    <artifactId>google-oauth-client-jetty</artifactId>
    <version>1.34.1</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-httplib2 google-auth-oauthlib oauth2client

Node.js

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

npm install "@googleapis/chat" open server-destroy

Apps Script

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

  1. מימין, לוחצים על עורך .
  2. מימין, ליד Services, לוחצים על Add a service (הוספת שירות) .
  3. בוחרים באפשרות Google Chat API.
  4. ב-Version, בוחרים באפשרות v1.
  5. לוחצים על הוספה.

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

שלב 4: כותבים סקריפט שקורא ל-Chat API

קריאה ל-API עם הרשאה של OAuth היא תהליך שיש בו כמה שלבים. באפליקציות לאינטרנט או למחשב, התהליך הוא בדרך כלל כך:

  1. האפליקציה מפנה את המשתמשים לדף הרשאה שבו מבקשים גישה לנתוני המשתמש שצוינו בהיקפי ההרשאות. האפליקציה מזהה את עצמה באמצעות פרטי הכניסה של Client-ID.
  2. המשתמש בודק את ההרשאות שהאפליקציה מבקשת ומאשר אותה.
  3. שרת האימות של Google מפנה את הדפדפן לנקודת הקצה מסוג HTTP של האפליקציה, עם קוד הרשאה.
  4. האפליקציה שולחת בקשה נוספת לשרת ההרשאות של Google כדי להחליף את קוד ההרשאה באסימון הגישה.
  5. האפליקציה משתמשת באסימון הגישה כדי לקרוא ל-API בשם המשתמש.

למידע נוסף על תהליך ההרשאה של OAuth, ראו שימוש ב-OAuth 2.0 לגישה ל-Google APIs מדריך.

דוגמאות הקוד הבאות ב-Java, ב-Python וב-Node.js משתמשות בספריית לקוח כדי להפעיל את תהליך ההרשאה של OAuth. הוא פותח שרת HTTP מקומי כדי לקבל את קוד ההרשאה בחזרה משרת ההרשאות, ואז הוא מחליף אותו באסימון גישה. בדוגמת הקוד של Apps Script, תהליך ההרשאה הזה מנוהל על ידי Apps Script.

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

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.auth.oauth2.Credential;
import com.google.api.client.extensions.java6.auth.oauth2.AuthorizationCodeInstalledApp;
import com.google.api.client.extensions.jetty.auth.oauth2.LocalServerReceiver;
import com.google.api.client.googleapis.auth.oauth2.GoogleAuthorizationCodeFlow;
import com.google.api.client.googleapis.auth.oauth2.GoogleClientSecrets;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.client.util.store.FileDataStoreFactory;
import com.google.api.services.chat.v1.HangoutsChat;
import com.google.api.services.chat.v1.model.Space;

import java.io.InputStreamReader;
import java.util.Collection;
import java.util.Collections;

/**
 * Authenticates with Chat API via user credentials, then creates a Chat space.
 */
public class App {
    // Application OAuth credentials.
    private static final String KEYS_RESOURCE_URI = "/client_secrets.json";

    // Define your app's authorization scopes.
    private static final Collection<String> SCOPES =
        Collections.singleton("https://www.googleapis.com/auth/chat.spaces.create");

    // Directory to store user credentials.
    private static final java.io.File DATA_STORE_DIR =
        new java.io.File(System.getProperty("user.home"), ".store/auth-sample-app");

    // Global instance of the JSON factory.
    private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();

    // Global instance of the HTTP transport.
    private static HttpTransport httpTransport;

    // Global instance of the DataStoreFactory. The best practice is to make it a single
    // globally shared instance across your application.
    private static FileDataStoreFactory dataStoreFactory;

    public static void main( String[] args ) {
        try {
            // Run app.
            httpTransport = GoogleNetHttpTransport.newTrustedTransport();
            dataStoreFactory = new FileDataStoreFactory(DATA_STORE_DIR);
            Credential userCredential = authorize();
            Space response = App.createChatSpace(userCredential);
            // Print details about the created space.
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * Authorizes the installed application to access user's protected data.
     */
    private static Credential authorize() throws Exception {
        // Load client secrets.
        GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY,
            new InputStreamReader(App.class.getResourceAsStream("/client_secrets.json")));
        // Set up authorization code flow.
        GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder(
            httpTransport, JSON_FACTORY, clientSecrets, SCOPES)
            .setDataStoreFactory(dataStoreFactory)
            .build();
        // Authorize.
        return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");
    }

    /**
     * Creates a Chat space.
     */
    private static Space createChatSpace(Credential userCredential) throws Exception {
        // Build the Chat API client and authenticate with the user account.
        HangoutsChat chatService = new HangoutsChat.Builder(
            httpTransport, JSON_FACTORY, userCredential)
            .setApplicationName("auth-sample-app")
            .build();

        // Create a Chat space.
        Space space = new Space()
            // To create a named space, set spaceType to SPACE.
            .setSpaceType("SPACE")
            // The user-visible name of the space.
            .setDisplayName("API-made");
        return chatService.spaces().create(space).execute();
    }
}

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

  4. מעתיקים את הקובץ client_secrets.json לספריית המשנה resources.

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

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

  6. כדי להגדיר את 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_space_create_named.py באותה ספרייה שבה נמצא client_secrets.json:

    from __future__ import print_function

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.create"]

def main():
  '''
  Authenticates with Chat API via user credentials,
  then creates a Chat space.
  '''

  flow = InstalledAppFlow.from_client_secrets_file(
                    'client_secrets.json', SCOPES)
  creds = flow.run_local_server()

  # Build a service endpoint for Chat API.
  service = build('chat', 'v1', credentials=creds)

  # Use the service endpoint to call Chat API.
  result = service.spaces().create(

    # Details about the space to create.
    body = {

      # To create a named space, set spaceType to SPACE.
      'spaceType': 'SPACE',

      # The user-visible name of the space.
      'displayName': 'API-made'

    }

  ).execute()

  # Prints details about the created space.
  print(result)

if __name__ == '__main__':
  main()

Node.js

  1. שומרים את הקוד הבא בקובץ בשם chat_space_create_named.js באותה ספרייה שבה נמצאים הפרויקט Node.js ו-client_secrets.json:

    const fs = require('fs');
const path = require('path');
const http = require('http');
const url = require('url');
const destroyer = require('server-destroy');

const chat = require('@googleapis/chat');

// Application OAuth credentials.
const keys = require('./client_secrets.json').installed;

// Define your app's authorization scopes.
// When modifying these scopes, delete the file token.json, if it exists.
const scopes = ["https://www.googleapis.com/auth/chat.spaces.create"];

// Create a new OAuth2 client with the configured keys.
const oauth2Client = new chat.auth.OAuth2(
  keys.client_id,
  keys.client_secret,
  'http://localhost:3000'
);

/**
 * Opens an HTTP server to accept the OAuth callback.
 * In this simple example, the only request to our webserver is to /?code=<code>.
 */
async function authenticate(scopes) {
  const opn = (await import('open')).default;

  return new Promise((resolve, reject) => {
    // Generate the URL for authorization.
    const authorizeUrl = oauth2Client.generateAuthUrl({
      access_type: 'offline',
      scope: scopes.join(' '),
    });
    // Start the HTTP server to listen for the callback.
    const server = http
      .createServer(async (req, res) => {
        try {
          const qs = new url.URL(req.url, 'http://localhost:3000').searchParams;
          res.end('Authentication successful! Please return to the console.');
          server.destroy();
          const { tokens } = await oauth2Client.getToken(qs.get('code'));
          oauth2Client.credentials = tokens;
          resolve(oauth2Client);
        } catch (e) {
          reject(e);
        }
      })
      .listen(3000, () => {
        // Open the browser to the authorize URL to start the workflow.
        opn(authorizeUrl, { wait: false }).then(cp => cp.unref());
      });
    destroyer(server);
  });
}

/**
 * Authenticates with Chat API via user credentials, then creates a Chat space.
 */
async function createSpace() {
  // Create the Chat API client and authenticate with the authorized user.
  const chatClient = await chat.chat({
    version: 'v1',
    auth: oauth2Client
  });

  // Call the Chat API to create a space.
  const result = await chatClient.spaces.create({

    // Details about the space to create.
    requestBody: {

      // To create a named space, set spaceType to SPACE.
      'spaceType': 'SPACE',

      // The user-visible name of the space.
      'displayName': 'API-made'

    }

  });
  return result;
}

// Authenticate the user, execute the function,
// then print details about the created space.
authenticate(scopes)
  .then(createSpace)
  .then(console.log);

Apps Script

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

      "oauthScopes": [
    "https://www.googleapis.com/auth/chat.spaces.create"
  ]

  2. שומרים את הקוד הבא בקובץ בשם ChatSpaceCreateNamed.gs בפרויקט Apps Script:

    /**
 * Authenticates with Chat API via user credentials, then creates a
 * Chat space.
 */
function createSpace() {
  try {
    // Details about the space to create.
    // To create a named space, set spaceType to SPACE.
    // The user-visible name of the space is displayName.
    const space = {'displayName': 'API-made', 'spaceType': 'SPACE'};

    // Call Chat API with user credentials to create the space.
    const result = Chat.Spaces.create(space);

    // Log details about the created space.
    console.log(result);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to create space with error %s', err.message);
  }
}

שלב 5: מריצים את הסקריפט לדוגמה

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

Java

mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar

Python

python3 chat_space_create_named.py

Node.js

node chat_space_create_named.js

Apps Script

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

ייפתח דפדפן ותתבקש להיכנס לחשבון Google:

נכנסים לחשבון כדי לתת הרשאה לאפליקציית Chat.

איור 2. מסך ההסכמה ל-OAuth שבו בוחרים את החשבון לאימות האפליקציה.

אחרי שתיכנסו, יופיע מסך ההסכמה ל-OAuth ותתבקשו לתת הרשאה לאפליקציה.

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

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

כשמריצים את chat_space_create_named.py, עשויה להופיע הודעת השגיאה הבאה:

Expected a JSON object with a single property for a "web" or "installed" application

המשמעות של הודעת השגיאה הזו היא שהקובץ client_secrets.json שהורדתם ממסוף Google Cloud לא מתחיל במאפיין "web" או "installed". אחרי האימות באמצעות הקובץ שהורדתם, אם בקוד שלכם לא נשמר אסימון הגישה בקובץ חדש כמו token.json, אסימון הגישה נכתב ב-client_secrets.json, מה שעלול לגרום לשגיאה הזו במהלך ניסיונות אימות נוספים.

כדי לפתור את השגיאה, צריך להוריד שוב את הקובץ הסודי של הלקוח ממסוף Google Cloud ולשמור את הקובץ החדש במקום הקובץ הנוכחי.

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

  • במסמכי העזרה של Chat API תוכלו לקרוא מה עוד אפשר לעשות ב-Chat API.