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

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

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

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

מטרות

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

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

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

• חשבון Google.

הגדרת הסביבה

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

הפעלת ה-API

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

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

  להפעלת ה-API

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

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

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

   מעבר לדף 'מיתוג'

2. אם כבר הגדרתם את , תוכלו להגדיר את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים מיתוג, קהל וגישה לנתונים. אם מופיעה ההודעה עדיין לא הוגדר, לוחצים על תחילת העבודה:
1. בקטע App Information (פרטי האפליקציה), בשדה App name (שם האפליקציה), מזינים שם לאפליקציה.
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.
3. מפתח ה-API החדש מוצג.
   • לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. אפשר גם למצוא את מפתח ה-API בקטע API keys (מפתחות API) בפרטי הכניסה של הפרויקט.
   • לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש במפתח ה-API. פרטים נוספים זמינים במאמר החלת הגבלות על מפתחות API.

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

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

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

   sheets/quickstart/index.html

   הצגת הקוד ב-GitHub
   <!DOCTYPE html>
   <html>
     <head>
       <title>Sheets API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Sheets 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://sheets.googleapis.com/$discovery/rest?version=v4';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/spreadsheets.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 listMajors();
           };
   
           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 names and majors of students in a sample spreadsheet:
          * https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
          */
         async function listMajors() {
           let response;
           try {
             // Fetch first 10 files
             response = await gapi.client.sheets.spreadsheets.values.get({
               spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
               range: 'Class Data!A2:E',
             });
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
           const range = response.result;
           if (!range || !range.values || range.values.length == 0) {
             document.getElementById('content').innerText = 'No values found.';
             return;
           }
           // Flatten to string to display
           const output = range.values.reduce(
               (str, row) => `${str}${row[0]}, ${row[4]}\n`,
               'Name, Major:\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 פועלת ושולחת קריאה אל Google Sheets API.

השלבים הבאים

• פתרון בעיות באימות ובהרשאות
• מסמכי עזר של Sheets API
• בקטע google-api-javascript-client ב-GitHub