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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    כניסה לדף 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 & שירותים > פרטי כניסה.

    כניסה לדף 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 & שירותים > פרטי כניסה.

    כניסה לדף 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 & שירותים > פרטי כניסה.

    כניסה לדף Credentials

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

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

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

    כניסה לדף Credentials

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

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

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

    כניסה לדף 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 & שירותים > פרטי כניסה.

    כניסה לדף Credentials

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > ממשקי API ו- Services (שירותים) > פרטי כניסה.

    כניסה לדף Credentials

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

  3. לוחצים על הורדת 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-oauthlib

Node.js

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

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

Apps Script

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

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

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

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

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

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

ייפתח בדפדפן שבו תתבקשו להיכנס לחשבון 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