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

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

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

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

מטרות

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

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

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

• דומיין Google Workspace עם גישה מופעלת ל-API.
• חשבון Google בדומיין הזה עם הרשאות אדמין.

הגדרת הסביבה

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

הפעלת ה-API

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

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

  להפעלת ה-API

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

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

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

   כניסה לדף Branding

2. אם כבר הגדרתם את , תוכלו להגדיר את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטע מיתוג, קהל וגישה לנתונים. אם מופיעה ההודעה not configured yet, לוחצים על Get Started:
1. בקטע פרטי האפליקציה, בשדה שם האפליקציה, מזינים שם לאפליקציה.
2. בקטע כתובת אימייל לתמיכה במשתמשים, בוחרים כתובת אימייל לתמיכה שבה המשתמשים יוכלו לפנות אליכם אם יש להם שאלות לגבי ההסכמה שלהם.
3. לוחצים על הבא.
4. בקטע קהל, בוחרים באפשרות פנימי.
5. לוחצים על הבא.
6. בקטע פרטים ליצירת קשר, מזינים כתובת אימייל שאליה יישלחו התראות על שינויים בפרויקט.
7. לוחצים על הבא.
8. בקטע סיום, קוראים את המדיניות בנושא נתוני משתמשים בשירותי Google API. אם מסכימים, בוחרים באפשרות אני מסכים/ה למדיניות בנושא נתוני משתמשים בשירותי Google API.
9. לוחצים על המשך.
10. לוחצים על יצירה.
3. בשלב הזה, אפשר לדלג על הוספת היקפי הרשאות. בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך לשנות את סוג המשתמש לחיצוני. לאחר מכן מוסיפים את היקפי ההרשאה הנדרשים לאפליקציה. למידע נוסף, קראו את המדריך המלא בנושא הגדרת הסכמה ל-OAuth.

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

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

1. במסוף Google Cloud, נכנסים לתפריט > > 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 (מפתח API).
3. מפתח ה-API החדש מוצג.
   • לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. אפשר למצוא את מפתח ה-API גם בקטע 'מפתחות API' בפרטי הכניסה של הפרויקט.
   • לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש במפתח ה-API. פרטים נוספים זמינים במאמר החלת הגבלות על מפתחות API.

הגדרת הדוגמה

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

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

   adminSDK/reports/index.html

   הצגת הקוד ב-GitHub
   <!DOCTYPE html>
   <html>
     <head>
       <title>Reports API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Reports 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/reports_v1/rest';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/admin.reports.audit.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 listLoginActivity();
           };
   
           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 10 recent login activities.
          */
         async function listLoginActivity() {
           let response;
           try {
             const request = {
               'userKey': 'all',
               'applicationName': 'login',
               'maxResults': 10,
             };
             response = await gapi.client.reports.activities.list(request);
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
   
           const activities = response.result.items;
           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 = activity.id.time;
                 const email = activity.actor.email;
                 const eventName = activity.events[0].name;
                 return `${str}-${time}: ${email} (${eventName})\n`;
               },
               'Logins:\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>

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

   • 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. לוחצים על אישור.

אפליקציית JavaScript פועלת ומפעילה את Admin SDK API.

השלבים הבאים

• פתרון בעיות באימות ובהרשאות
• מאמרי העזרה של ה-API של דוחות Admin SDK
• הקטע google-api-javascript-client ב-GitHub