מדריך למתחילים ב-JavaScript

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

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

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

מטרות

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

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

• ‫Node.js ו-npm מותקנים.
• פרויקט ב-Google Cloud.

• חשבון Google.

הגדרת הסביבה

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

מפעילים את ה-API

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

• במסוף Google Cloud, מפעילים את Google Drive Activity API.

  להפעלת ה-API

מגדירים את מסך ההסכמה של OAuth

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

1. במסוף Google Cloud, עוברים אל תפריט > Google Auth platform > Branding.

   מעבר לדף Branding

2. אם כבר הגדרתם את Google Auth platform, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים Branding,‏ Audience וData Access. אם מופיעה ההודעה Google Auth platform not configured yet, לוחצים על Get Started:
1. בקטע App Information בשדה App name, מזינים שם לאפליקציה.
2. בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
3. לוחצים על Next.
4. בקטע Audience, לוחצים על Internal.
5. לוחצים על Next.
6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
7. לוחצים על Next.
8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, מסמנים את התיבה I agree to the Google API Services: User Data Policy.
9. לוחצים על Continue.
10. לוחצים על Create.
3. כרגע אתם יכולים לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון שלכם ב-Google Workspace, תצטרכו לשנות את סוג המשתמש ל-External. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

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

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

1. במסוף Google Cloud, עוברים אל תפריט > Google Auth platform > Clients.

   כניסה לדף Clients

2. לוחצים על Create Client.
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 2.0.

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

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

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

1. במסוף Google Cloud, לוחצים על סמל התפריט > APIs & Services > Credentials.

   כניסה לדף Credentials

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

מגדירים את הדוגמה

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

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

   drive/activity-v2/index.html

   הצגת הקוד ב-GitHub
   <!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>

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

   • ‫YOUR_CLIENT_ID: מזהה הלקוח שיצרתם כשהענקתם הרשאה לפרטי כניסה לאפליקציית אינטרנט.
   • ‫YOUR_API_KEY: מפתח ה-API שיצרתם כדרישה מוקדמת.

מריצים את הדוגמה

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

   npm install http-server
   

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

   npx http-server -p 8000
   

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

אפליקציית JavaScript פועלת ומפעילה את Google Drive Activity API.

השלבים הבאים

• התנסות עם ממשקי Google Workspace API ב-API Explorer
  • פתרון בעיות באימות ובהרשאות
  • מאמרי העזרה של Drive Activity API
  • הקטע google-api-javascript-client ב-GitHub