دليل سريع للبدء باستخدام JavaScript

يمكنكم إنشاء تطبيق ويب بلغة JavaScript يرسل طلبات إلى Admin SDK API.

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

يستخدم دليل البدء السريع هذا مكتبات عملاء واجهة برمجة التطبيقات المقترَحة من Google Workspace للتعامل مع بعض تفاصيل عملية المصادقة والتفويض.

الأهداف

• إعداد البيئة
• إعداد النموذج
• تشغيل النموذج

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

• Node.js وnpm مثبت.
• مشروع على Google Cloud.

• نطاق Google Workspace مفعّلة فيه إمكانية الوصول إلى واجهة برمجة التطبيقات
• حساب Google في هذا النطاق لديه امتيازات المشرف

إعداد البيئة

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

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

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

• في Google Cloud Console، فعِّلوا Admin SDK API.

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

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

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

1. في Google API Console، انتقِلوا إلى "القائمة" menu > منصة Google للمصادقة > العلامة التجارية.

   الانتقال إلى "العلامة التجارية"

2. إذا سبق لكم إعداد منصة Google للمصادقة، يمكنكم إعداد الإعدادات التالية لشاشة طلب الموافقة المتعلّقة ببروتوكول OAuth في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لكم رس0الة لم يتم إعداد منصة Google للمصادقة بعد، انقروا على البدء:
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 API Console، انتقِلوا إلى "القائمة" > منصة Google للمصادقة > العملاء.

   الانتقال إلى "العملاء"

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

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

   يُرجى العِلم أنّه لا يتم استخدام أسرار العميل لتطبيقات الويب.

7. احفظوا معرّف العميل لاستخدامه لاحقًا في دليل البدء السريع هذا.

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

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

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

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

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

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: مفتاح واجهة برمجة التطبيقات الذي أنشأتموه.

تشغيل النموذج

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.

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

• جرِّبوا Google Workspace APIs في أداة مستكشف واجهات برمجة التطبيقات
  • تحديد مشاكل المصادقة والتفويض وحلّها
  • المستندات المرجعية لواجهة برمجة تطبيقات تقارير مدير SDK
  • google-api-javascript-client قسم على GitHub