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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

    כניסה לדף Credentials

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

    יש לציין את מזהה הלקוח. סודות לקוח לא משמשים לאפליקציות אינטרנט.

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

Android

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

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח 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. לוחצים על יצירת פרטי כניסה > מזהה לקוח 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. לוחצים על יצירת פרטי כניסה > מזהה לקוח 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. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על סוג האפליקציה > אפליקציה למחשב.
  4. בשדה שם, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  6. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.

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

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

    כניסה לדף Credentials

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

Universal Windows Platform (UWP)‎

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

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח 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. לוחצים על הורדת JSON.

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

שלב 3: מתקינים את ספריית הלקוח של 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.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-oauthlib

Node.js

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

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

Apps Script

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

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

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

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

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

  1. האפליקציה מפנה את המשתמשים לדף הרשאות שבו היא מבקשת גישה לנתוני המשתמשת שצוינו בהיקפי ההרשאות. האפליקציה מזדהה באמצעות פרטי הכניסה של מזהה הלקוח.
  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 google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# 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.