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

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

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

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

מטרות

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

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

  • חשבון Google ש-Google Drive מופעל בו.

הגדרת הסביבה שלך

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

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

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

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

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

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

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

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

  5. אם בחרתם באפשרות חיצוני בשדה של סוג המשתמש, מוסיפים משתמשי בדיקה:
    1. בקטע משתמשי בדיקה, לוחצים על הוספת משתמשים.
    2. מזינים את כתובת האימייל שלכם ומשתמשים מורשים אחרים לבדיקה, ואז לוחצים על Save and Continue (שמירה והמשך).
  6. בודקים את הסיכום של רישום האפליקציה. כדי לערוך שינויים, לוחצים על עריכה. אם נראה שהרישום של האפליקציה בסדר, לוחצים על חזרה למרכז השליטה.

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

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

    כניסה לדף Credentials

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

    יש לשים לב ל-Client-ID. סודות לקוח לא משמשים לאפליקציות אינטרנט.

  7. לוחצים על אישור. פרטי הכניסה החדשים שייווצרו מופיעים בקטע מזהי לקוח ב-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, מדביקים את קוד הדוגמה הבא:

    drive/quickstart/index.html
    <!DOCTYPE html>
<html>
  <head>
    <title>Drive API Quickstart</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <p>Drive 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/drive/v3/rest';

      // Authorization scopes required by the API; multiple scopes can be
      // included, separated by spaces.
      const SCOPES = 'https://www.googleapis.com/auth/drive.metadata.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 listFiles();
        };

        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 metadata for first 10 files.
       */
      async function listFiles() {
        let response;
        try {
          response = await gapi.client.drive.files.list({
            'pageSize': 10,
            'fields': 'files(id, name)',
          });
        } catch (err) {
          document.getElementById('content').innerText = err.message;
          return;
        }
        const files = response.result.files;
        if (!files || files.length == 0) {
          document.getElementById('content').innerText = 'No files found.';
          return;
        }
        // Flatten to string to display
        const output = files.reduce(
            (str, file) => `${str}${file.name} (${file.id})\n`,
            'Files:\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

  3. בדפדפן, עוברים אל http://localhost:8000.

  4. בפעם הראשונה שמריצים את הדוגמה, מוצגת בקשה לאשר גישה:

    1. אם לא התחברתם לחשבון Google שלכם, תתבקשו להיכנס אליו. אם נכנסתם לכמה חשבונות, בחרו חשבון אחד שישמש להרשאה.
    2. לוחצים על אישור.
    3. מעתיקים את הקוד מהדפדפן, מדביקים אותו בשורת הפקודה ולוחצים על Enter.

    פרטי ההרשאות נשמרים במערכת הקבצים, כך שבפעם הבאה שמריצים את הקוד לדוגמה לא מתבקשים להעניק הרשאה.

יצרתם בהצלחה את אפליקציית ה-JavaScript הראשונה שלכם, ששולחת בקשות לממשק ה-API של Google Drive.

השלבים הבאים