מדריך למתחילים בנושא JavaScript

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

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

יצירת אפליקציית אינטרנט של JavaScript ששולחת בקשות ל-Directory API.

מטרות

  • מגדירים את הסביבה.
  • הגדרת הדוגמה.
  • מריצים את הדוגמה.

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

הגדרת הסביבה

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

הפעלת ה-API

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

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

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

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

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

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

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

אישור פרטי כניסה לאפליקציית אינטרנט

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

    כניסה לדף Credentials

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

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

יצירה של מפתח API

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

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה >. API key.
  3. מפתח ה-API החדש מוצג.
    • לוחצים על 'העתקה' . כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. מפתח ה-API יכול להיות גם נמצא ב'מפתחות API'. בפרטי הכניסה של הפרויקט.
    • לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש. של מפתח ה-API. מידע נוסף זמין במאמר החלת הגבלות על מפתחות API.

הגדרת הדוגמה

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

  2. בקובץ index.html, מדביקים את הקוד לדוגמה הבא:

    adminSDK/directory/index.html
    <!DOCTYPE html>
<html>
  <head>
    <title>Directory API Quickstart</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <p>Directory API Quickstart</p>

    <!--Add buttons to initiate auth sequence and sign out-->
    <button id="authorize_button" onclick="handleAuthClick()">Authorize</button>
    <button id="signout_button" onclick="handleSignoutClick()">Sign Out</button>

    <pre id="content" style="white-space: pre-wrap;"></pre>

    <script type="text/javascript">
      /* exported gapiLoaded */
      /* exported gisLoaded */
      /* exported handleAuthClick */
      /* exported handleSignoutClick */

      // TODO(developer): Set to client ID and API key from the Developer Console
      const CLIENT_ID = '<YOUR_CLIENT_ID>';
      const API_KEY = '<YOUR_API_KEY>';

      // Discovery doc URL for APIs used by the quickstart
      const DISCOVERY_DOC = 'https://www.googleapis.com/discovery/v1/apis/admin/directory_v1/rest';

      // Authorization scopes required by the API; multiple scopes can be
      // included, separated by spaces.
      const SCOPES = 'https://www.googleapis.com/auth/admin.directory.user.readonly';

      let tokenClient;
      let gapiInited = false;
      let gisInited = false;

      document.getElementById('authorize_button').style.visibility = 'hidden';
      document.getElementById('signout_button').style.visibility = 'hidden';

      /**
       * Callback after api.js is loaded.
       */
      function gapiLoaded() {
        gapi.load('client', initializeGapiClient);
      }

      /**
       * Callback after the API client is loaded. Loads the
       * discovery doc to initialize the API.
       */
      async function initializeGapiClient() {
        await gapi.client.init({
          apiKey: API_KEY,
          discoveryDocs: [DISCOVERY_DOC],
        });
        gapiInited = true;
        maybeEnableButtons();
      }

      /**
       * Callback after Google Identity Services are loaded.
       */
      function gisLoaded() {
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: CLIENT_ID,
          scope: SCOPES,
          callback: '', // defined later
        });
        gisInited = true;
        maybeEnableButtons();
      }

      /**
       * Enables user interaction after all libraries are loaded.
       */
      function maybeEnableButtons() {
        if (gapiInited && gisInited) {
          document.getElementById('authorize_button').style.visibility = 'visible';
        }
      }

      /**
       *  Sign in the user upon button click.
       */
      function handleAuthClick() {
        tokenClient.callback = async (resp) => {
          if (resp.error !== undefined) {
            throw (resp);
          }
          document.getElementById('signout_button').style.visibility = 'visible';
          document.getElementById('authorize_button').innerText = 'Refresh';
          await listUsers();
        };

        if (gapi.client.getToken() === null) {
          // Prompt the user to select a Google Account and ask for consent to share their data
          // when establishing a new session.
          tokenClient.requestAccessToken({prompt: 'consent'});
        } else {
          // Skip display of account chooser and consent dialog for an existing session.
          tokenClient.requestAccessToken({prompt: ''});
        }
      }

      /**
       *  Sign out the user upon button click.
       */
      function handleSignoutClick() {
        const token = gapi.client.getToken();
        if (token !== null) {
          google.accounts.oauth2.revoke(token.access_token);
          gapi.client.setToken('');
          document.getElementById('content').innerText = '';
          document.getElementById('authorize_button').innerText = 'Authorize';
          document.getElementById('signout_button').style.visibility = 'hidden';
        }
      }

      /**
       * Print the first 10 users in the domain.
       */
      async function listUsers() {
        let response;
        try {
          const request = {
            'customer': 'my_customer',
            'maxResults': 10,
            'orderBy': 'email',
          };
          response = await gapi.client.directory.users.list(request);
        } catch (err) {
          document.getElementById('content').innerText = err.message;
          return;
        }

        const users = response.result.users;
        if (!users || users.length == 0) {
          document.getElementById('content').innerText = 'No users found.';
          return;
        }
        // Flatten to string to display
        const output = users.reduce(
            (str, user) => `${str}${user.primaryEmail} (${user.name.fullName})\n`,
            'Users:\n');
        document.getElementById('content').innerText = output;
      }

    </script>
    <script async defer src="https://apis.google.com/js/api.js" onload="gapiLoaded()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
  </body>
</html>

    מחליפים את מה שכתוב בשדות הבאים:

הרצת הדוגמה

  1. בספריית העבודה, מתקינים את חבילת ה-http-server:

    npm install http-server

  2. בספריית העבודה, מפעילים שרת אינטרנט:

    npx http-server -p 8000
  1. בדפדפן, עוברים אל http://localhost:8000.
  2. תוצג בקשה לאישור גישה:
    1. אם עדיין לא נכנסתם לחשבון Google, נכנסים אליו כשמוצגת בקשה לעשות זאת. אם המיקום נכנסת לכמה חשבונות. צריך לבחור חשבון אחד שישמש להרשאה.
    2. לוחצים על אישור.

אפליקציית ה-JavaScript מפעילה את Directory API וקוראת לו.

השלבים הבאים