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

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

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

إنشاء تطبيق ويب بلغة JavaScript يقدّم طلبات إلى Google Classroom API

الأهداف

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

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

• تم تثبيت Node.js وnpm.
• مشروع Google Cloud:

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

إعداد البيئة

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

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

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

• في "وحدة تحكُّم Google Cloud"، فعِّل Google Classroom API.

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

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

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

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

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

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

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

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

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

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

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

   الانتقال إلى "بيانات الاعتماد"

2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. انقر على نوع التطبيق > تطبيق الويب.
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في وحدة تحكم Google Cloud.
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، انتقِل إلى رمز القائمة menu > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

   الانتقال إلى "بيانات الاعتماد"

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

إعداد النموذج

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

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

   classroom/quickstart/index.html

   العرض على GitHub

   <!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>

   استبدل ما يلي:

   • YOUR_CLIENT_ID: معرّف العميل الذي أنشأته عند تفويض بيانات الاعتماد لتطبيق ويب
   • YOUR_API_KEY: مفتاح واجهة برمجة التطبيقات الذي أنشأته كـ متطلبات أساسية.

تنفيذ عيّنة

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.

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

• تحديد مشاكل المصادقة والمصادقة وحلّها
• المستندات المرجعية في Classroom API
• قسم google-api-javascript-client على GitHub