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

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

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

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

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

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

אימות ואישור באמצעות הענקת גישה ברמת הדומיין

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

אימות ואישור באמצעות הרשאות אדמין

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

חשוב לזכור: כשאפליקציית 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

שלב 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. לוחצים על Create Credentials > OAuth client ID.
  3. לוחצים על Application type (סוג אפליקציה) > Web application.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. מוסיפים מזהי URI מורשים שקשורים לאפליקציה:
    • אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות JavaScript מורשים, לוחצים על הוספת URI. לאחר מכן, מזינים URI שישמש לבקשות דפדפן. הנתון הזה מזהה את הדומיינים שמהם האפליקציה יכולה לשלוח בקשות API לשרת OAuth 2.0.
    • אפליקציות בצד השרת (Java, Python ועוד) – בקטע מזהי URI מורשים להפניה אוטומטית, לוחצים על הוספת URI. לאחר מכן, מזינים URI של נקודת קצה שאליה שרת OAuth 2.0 יכול לשלוח תשובות.
  6. לוחצים על יצירה. יופיע המסך שנוצר על ידי לקוח OAuth ומוצג בו מזהה הלקוח החדש וסוד הלקוח שלכם.

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

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

Android

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

    כניסה לדף Credentials

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

טלוויזיות ומכשירים מוגבלים לקליטת נתונים

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

    כניסה לדף Credentials

  2. לוחצים על Create Credentials > OAuth client ID.
  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.
  3. לוחצים על Application type (סוג אפליקציה) > 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

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

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

Apps Script

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

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

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

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

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

  1. האפליקציה מפנה את המשתמשים לדף הרשאה שבו מבקשים גישה לנתוני המשתמש שצוינו בהיקפי ההרשאות. האפליקציה מזדהה באמצעות פרטי הכניסה של מזהה הלקוח.
  2. המשתמש בודק את ההרשאות שהאפליקציה מבקשת, ומאשר את הבקשה.
  3. שרת האימות של Google מפנה את הדפדפן לנקודת הקצה (endpoint) של ה-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.