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

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

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

יוצרים אפליקציית אינטרנט ב-JavaScript ששולחת בקשות ל-Google Drive Activity API.

מטרות

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

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

  • חשבון Google.

הגדרת הסביבה

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

הפעלת ה-API

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

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

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

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

  2. בקטע User type בוחרים באפשרות Internal ולוחצים על Create.
  3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.
  4. בשלב הזה, אפשר לדלג על הוספת היקפי הרשאה וללחוץ על Save and Continue (שמירה והמשך). בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך לשנות את סוג המשתמש ל-חיצוני, ואז להוסיף את היקפי ההרשאה הנדרשים לאפליקציה.

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

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

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

    כניסה לדף Credentials

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

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

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

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

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

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

    כניסה לדף Credentials

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

הגדרת הדוגמה

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

    drive/activity-v2/index.html
    <!DOCTYPE html>
    <html>
      <head>
        <title>Drive Activity API Quickstart</title>
        <meta charset="utf-8" />
      </head>
      <body>
        <p>Drive Activity 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/driveactivity/v2/rest';
    
          // Authorization scopes required by the API; multiple scopes can be
          // included, separated by spaces.
          const SCOPES = 'https://www.googleapis.com/auth/drive.activity.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 listActivities();
            };
    
            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 recent activity.
           */
          async function listActivities() {
            let response;
            try {
              response = await gapi.client.driveactivity.activity.query({
                'pageSize': 10,
              });
            } catch (err) {
              document.getElementById('content').innerText = err.message;
              return;
            }
    
            const activities = response.result.activities;
            if (!activities || activities.length == 0) {
              document.getElementById('content').innerText = 'No activities found.';
              return;
            }
            // Flatten to string to display
            const output = activities.reduce(
                (str, activity) => {
                  const time = getTimeInfo(activity);
                  const action = getActionInfo(activity['primaryActionDetail']);
                  const actors = activity.actors.map(getActorInfo);
                  const targets = activity.targets.map(getTargetInfo);
                  return `${str}${time}: ${truncated(actors)}, ${action}, ${truncated(targets)}\n`;
                },
                'Activities:\n');
            document.getElementById('content').innerText = output;
          }
    
          // Utility methods for formatting activity records
    
          /**
           * Returns a string representation of the first N elements in a list.
           * @param {string[]} array - Values to join
           * @param {number} limit - # of elements to show
           * @return {string} formatted string
           */
          function truncated(array, limit = 2) {
            const contents = array.slice(0, limit).join(', ');
            const more = array.length > limit ? ', ...' : '';
            return `[${contents}${more}]`;
          }
    
          /**
           * Returns the first found property name in an object.
           * @param {object} object - Object to search
           * @return {string} key name or 'unknown'
           */
          function getOneOf(object) {
            const props = Object.getOwnPropertyNames(object);
            if (props.length === 0) {
              return 'unknown';
            }
            return props[0];
          }
    
          /**
           * Returns a time associated with an activity.
           * @param {object} activity - Activity record
           * @return {string} Formatted timestamp
           */
          function getTimeInfo(activity) {
            if ('timestamp' in activity) {
              return activity.timestamp;
            }
            if ('timeRange' in activity) {
              return activity.timeRange.endTime;
            }
            return 'unknown';
          }
    
          /**
           * Returns the type of action.
           * @param {object} actionDetail
           * @return {string} Action type as string
           */
          function getActionInfo(actionDetail) {
            return getOneOf(actionDetail);
          }
    
          /**
           * Returns user information, or the type of user if not a known user.
           * @param {object} user - User record
           * @return {string} user type as string
           */
          function getUserInfo(user) {
            if ('knownUser' in user) {
              const knownUser = user['knownUser'];
              const isMe = knownUser['isCurrentUser'] || false;
              return isMe ? 'people/me' : knownUser['personName'];
            }
            return getOneOf(user);
          }
    
          /**
           * Returns actor information, or the type of actor if not a user.
           * @param {object} actor - Actor record
           * @return {string} actor type as string
           */
          function getActorInfo(actor) {
            if ('user' in actor) {
              return getUserInfo(actor['user']);
            }
            return getOneOf(actor);
          }
    
          /**
           * Returns the type of a target and an associated title.
           * @param {object} target - Activity target record
           * @return {string} target type as string
           */
          function getTargetInfo(target) {
            if ('driveItem' in target) {
              const title = target.driveItem.title || 'unknown';
              return `driveItem:"${title}"`;
            }
            if ('drive' in target) {
              const title = target.drive.title || 'unknown';
              return `drive:"${title}"`;
            }
            if ('fileComment' in target) {
              const parent = target.fileComment.parent || {};
              const title = parent.title || 'unknown';
              return `fileComment:"${title}"`;
            }
            return `${getOneOf(target)}:unknown`;
          }
        </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 פועלת ומפעילה את Google Drive Activity API.

השלבים הבאים