التشغيل السريع للغة JavaScript

تشرح أدلة بدء الاستخدام السريع كيفية إعداد وتشغيل تطبيق يستدعي واجهة برمجة تطبيقات Google Workspace.

تستخدم مشاريع Google Workspace للبدء السريع في استخدام مكتبات برامج واجهة برمجة التطبيقات لمعالجة بعض تفاصيل عملية المصادقة والتفويض. وننصحك باستخدام مكتبات البرامج لتطبيقاتك. يستخدم دليل البدء السريع هذا نهج مصادقة مبسطًا ومناسبًا لبيئة الاختبار. بالنسبة إلى بيئة الإنتاج، نقترح التعرّف على معلومات حول المصادقة والتفويض قبل اختيار بيانات اعتماد الوصول المناسبة لتطبيقك.

إنشاء تطبيق ويب JavaScript يُجري الطلبات إلى Google Classroom API

الأهداف

  • إعداد البيئة:
  • عليك إعداد العيّنة.
  • شغِّل النموذج.

المتطلبات الأساسية

  • حساب Google for Education مع تفعيل Google Classroom

إعداد البيئة

لإكمال عملية البدء السريع هذه، عليك إعداد بيئتك.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.

إذا كنت تستخدم مشروعًا جديدًا على Google Cloud لإكمال عملية البدء السريع هذه، عليك ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth وإضافة نفسك كمستخدم تجريبي. إذا كنت قد أكملت هذه الخطوة بالفعل لمشروعك Cloud، انتقل إلى القسم التالي.

  1. في Google Cloud Console، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

    الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

  2. اختر نوع المستخدِم لتطبيقك، ثمّ انقر على إنشاء.
  3. أكمل نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

  4. في الوقت الحالي، يمكنك تخطي إضافة النطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق للاستخدام خارج مؤسستك على Google Workspace، عليك إضافة نطاقات التفويض التي يتطلبها تطبيقك والتحقّق منها.

  5. في حال اختيار خارجي لنوع المستخدم، أضِف مستخدمي الاختبار:
    1. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
    2. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين مختبِرين معتمدين آخرين، ثم انقر على حفظ ومتابعة.
  6. مراجعة ملخص تسجيل التطبيق. لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق يبدو على ما يرام، انقر على الرجوع إلى لوحة البيانات.

تفويض بيانات الاعتماد لتطبيق ويب

للمصادقة بصفتك مستخدمًا نهائيًا والوصول إلى بيانات المستخدم في تطبيقك، عليك إنشاء معرّف عميل OAuth 2.0 واحد أو أكثر. يُستخدم معرّف العميل لتحديد تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على أنظمة أساسية متعددة، يجب إنشاء معرِّف عميل منفصل لكل نظام أساسي.
  1. في وحدة تحكُّم Google Cloud، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى صفحة "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
  3. انقر على نوع التطبيق > تطبيق الويب.
  4. في الحقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud Console.
  5. أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة والمرتبطة بتطبيقك:
    • التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف موارد منتظم (URI) لاستخدامه في طلبات المتصفِّح. يحدِّد هذا الإعداد النطاقات التي يمكن لتطبيقك من خلالها إرسال طلبات واجهة برمجة التطبيقات إلى خادم OAuth 2.0.
    • التطبيقات من جهة الخادم (Java وPython وغيرهما): ضمن معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرِّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) لنقطة النهاية الذي يمكن لخادم OAuth 2.0 إرسال الردود.
  6. انقر على إنشاء. ستظهر شاشة إنشاء عميل OAuth وتعرض معرِّف العميل الجديد وسر العميل.

    دوِّن معرّف العميل. لا يتم استخدام أسرار العميل لتطبيقات الويب.

  7. انقر على حسنًا. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.

دوِّن بيانات الاعتماد هذه لأنك بحاجة إليها لاحقًا في دليل البدء السريع هذا.

إنشاء مفتاح واجهة برمجة التطبيقات

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى صفحة "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
  3. يتم عرض مفتاح واجهة برمجة التطبيقات الجديد.
    • انقر على رمز النسخ لنسخ مفتاح واجهة برمجة التطبيقات لاستخدامه في رمز تطبيقك. يمكن أيضًا العثور على مفتاح واجهة برمجة التطبيقات في القسم "مفاتيح واجهة برمجة التطبيقات" من بيانات اعتماد مشروعك.
    • انقر على تقييد المفتاح لتعديل الإعدادات المتقدمة والحد من استخدام مفتاح واجهة برمجة التطبيقات. للمزيد من التفاصيل، يُرجى الاطّلاع على تطبيق القيود على مفتاح واجهة برمجة التطبيقات.

إعداد العيّنة

  1. في دليل العمل، أنشئ ملفًا باسم index.html.

  2. في ملف index.html، الصق نموذج الرمز التالي:

    Classroom/quickstart/index.html
    <!DOCTYPE html>
<html>
  <head>
    <title>Classroom API Quickstart</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <p>Classroom 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://classroom.googleapis.com/$discovery/rest';

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

        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 of the first 10 courses the user has access to. If
       * no courses are found an appropriate message is printed.
       */
      async function listCourses() {
        let response;
        try {
          response = await gapi.client.classroom.courses.list({
            pageSize: 10,
          });
        } catch (err) {
          document.getElementById('content').innerText = err.message;
          return;
        }

        const courses = response.result.courses;
        if (!courses || courses.length == 0) {
          document.getElementById('content').innerText = 'No courses found.';
          return;
        }
        // Flatten to string to display
        const output = courses.reduce(
            (str, course) => `${str}${course.name}\n`,
            'Courses:\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 يقدم طلبات إلى Google Classroom API.

الخطوات التالية