המדריך למתחילים של Node.js

מדריכים למתחילים מסבירים איך להגדיר ולהפעיל אפליקציה שמתקשרת Google Workspace API.

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

ליצור אפליקציית שורת הפקודה של Node.js ששולחת בקשות API של Google Chat.

מטרות

  • מגדירים את הסביבה.
  • מתקינים את ספריית הלקוח.
  • הגדרת הדוגמה.
  • מריצים את הדוגמה.

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

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

הגדרת הסביבה

כדי להשלים את המדריך למתחילים הזה, עליכם להגדיר את הסביבה.

הפעלת ה-API

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

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

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

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

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

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

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

אישור פרטי כניסה לאפליקציה בשולחן העבודה

כדי לאמת משתמשי קצה ולגשת לנתוני המשתמשים באפליקציה: ליצור מזהה לקוח אחד או יותר של OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה יחידה לשרתי OAuth של Google. אם האפליקציה שלכם פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.
  1. במסוף Google Cloud, נכנסים לתפריט > APIs & שירותים > פרטי כניסה.

    כניסה לדף Credentials

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

איך מגדירים את אפליקציית Google Chat

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

  1. נכנסים לדף Configuration במסוף Google Cloud:

    לדף ההגדרה של Chat API

  2. בקטע Application info (פרטי האפליקציה), מזינים את הפרטים הבאים:

    1. בשדה שם האפליקציה, מזינים Chat API quickstart app.
    2. בשדה כתובת URL של הדמות, מזינים https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. בשדה תיאור, מזינים Quickstart for calling the Chat API.

  3. בקטע תכונות אינטראקטיביות לוחצים על הפעלת תכונות אינטראקטיביות למצב מושבת כדי להשבית תכונות אינטראקטיביות אפליקציית Chat.

  4. לוחצים על שמירה.

התקנת ספריית הלקוח

  • מתקינים את הספריות באמצעות npm:

    npm install @google-apps/chat @google-cloud/local-auth@2.1.0 --save

הגדרת הדוגמה

  1. בספריית העבודה, יוצרים קובץ בשם index.js.

  2. בקובץ, מדביקים את הקוד הבא:

    chat/quickstart/index.js
    const fs = require('fs').promises;
const path = require('path');
const process = require('process');
const {authenticate} = require('@google-cloud/local-auth');
const {ChatServiceClient} = require('@google-apps/chat');
const {auth} = require('google-auth-library');

// If modifying these scopes, delete token.json.
const SCOPES = ['https://www.googleapis.com/auth/chat.spaces.readonly'];

// The file token.json stores the user's access and refresh tokens, and is
// created automatically when the authorization flow completes for the first
// time.
const TOKEN_PATH = path.join(process.cwd(), 'token.json');
const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');

/**
 * Reads previously authorized credentials from the save file.
 *
 * @return {Promise<OAuth2Client|null>}
 */
async function loadSavedCredentialsIfExist() {
  try {
    const content = await fs.readFile(TOKEN_PATH);
    const credentials = JSON.parse(content);
    return auth.fromJSON(credentials);
  } catch (err) {
    console.log(err);
    return null;
  }
}

/**
 * Serializes credentials to a file compatible with GoogleAuth.fromJSON.
 *
 * @param {OAuth2Client} client
 * @return {Promise<void>}
 */
async function saveCredentials(client) {
  const content = await fs.readFile(CREDENTIALS_PATH);
  const keys = JSON.parse(content);
  const key = keys.installed || keys.web;
  const payload = JSON.stringify({
    type: 'authorized_user',
    client_id: key.client_id,
    client_secret: key.client_secret,
    refresh_token: client.credentials.refresh_token,
  });
  await fs.writeFile(TOKEN_PATH, payload);
}

/**
 * Load or request or authorization to call APIs.
 *
 * @return {Promise<OAuth2Client>}
 */
async function authorize() {
  let client = await loadSavedCredentialsIfExist();
  if (client) {
    return client;
  }
  client = await authenticate({
    scopes: SCOPES,
    keyfilePath: CREDENTIALS_PATH,
  });
  if (client.credentials) {
    await saveCredentials(client);
  }
  return client;
}

/**
 * Lists spaces with user credential.
 * @param {OAuth2Client} authClient An authorized OAuth2 client.
 */
async function listSpaces(authClient) {
  // Create a client
  const chatClient = new ChatServiceClient({
    authClient: authClient,
    scopes: SCOPES,
  });

  // Initialize request argument(s)
  const request = {
    // Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
    filter: 'space_type = "SPACE"'
  };

  // Make the request
  const pageResult = chatClient.listSpacesAsync(request);

  // Handle the response. Iterating over pageResult will yield results and
  // resolve additional pages automatically.
  for await (const response of pageResult) {
    console.log(response);
  }
}

authorize().then(listSpaces).catch(console.error);

הרצת הדוגמה

  1. בספריית העבודה, מריצים את הדוגמה:

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

    אפליקציית Nodejs מריצה את Google Chat API וקוראת לו.

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

השלבים הבאים