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

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

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

أنشئ تطبيق ويب مكتوب بلغة JavaScript يُرسل طلبات إلى Google Drive Activity API.

الأهداف

• اضبط إعدادات البيئة.
• إعداد العيّنة
• شغِّل العيّنة.

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

• Node.js وnpm مثبَّتَين
• أحد مشاريع Google Cloud

• حساب على Google

إعداد البيئة

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

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

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

• في Google Cloud Console، فعِّل Google Drive Activity API.

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

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

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

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

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

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

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

5. راجِع ملخّص تسجيل تطبيقك. لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق يبدو جيدًا، انقر على الرجوع إلى لوحة البيانات.

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

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

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

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

2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. انقر على نوع التطبيق > تطبيق الويب.
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. ولا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
5. أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة ذات الصلة بتطبيقك:
   • التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل عنوان URL لاستخدامه في طلبات المتصفّح. يحدِّد هذا النطاقات التي يمكن لتطبيقك من خلالها إرسال طلبات واجهة برمجة التطبيقات إلى خادم 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، الصِق نموذج الرمز التالي:

   drive/activity-v2/index.html

   العرض على GitHub

   <!DOCTYPE html>
   <html>
     <head>
       <title>Drive Activity API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Drive Activity 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/driveactivity/v2/rest';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/drive.activity.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 listActivities();
           };
   
           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 recent activity.
          */
         async function listActivities() {
           let response;
           try {
             response = await gapi.client.driveactivity.activity.query({
               'pageSize': 10,
             });
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
   
           const activities = response.result.activities;
           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 = getTimeInfo(activity);
                 const action = getActionInfo(activity['primaryActionDetail']);
                 const actors = activity.actors.map(getActorInfo);
                 const targets = activity.targets.map(getTargetInfo);
                 return `${str}${time}: ${truncated(actors)}, ${action}, ${truncated(targets)}\n`;
               },
               'Activities:\n');
           document.getElementById('content').innerText = output;
         }
   
         // Utility methods for formatting activity records
   
         /**
          * Returns a string representation of the first N elements in a list.
          * @param {string[]} array - Values to join
          * @param {number} limit - # of elements to show
          * @return {string} formatted string
          */
         function truncated(array, limit = 2) {
           const contents = array.slice(0, limit).join(', ');
           const more = array.length > limit ? ', ...' : '';
           return `[${contents}${more}]`;
         }
   
         /**
          * Returns the first found property name in an object.
          * @param {object} object - Object to search
          * @return {string} key name or 'unknown'
          */
         function getOneOf(object) {
           const props = Object.getOwnPropertyNames(object);
           if (props.length === 0) {
             return 'unknown';
           }
           return props[0];
         }
   
         /**
          * Returns a time associated with an activity.
          * @param {object} activity - Activity record
          * @return {string} Formatted timestamp
          */
         function getTimeInfo(activity) {
           if ('timestamp' in activity) {
             return activity.timestamp;
           }
           if ('timeRange' in activity) {
             return activity.timeRange.endTime;
           }
           return 'unknown';
         }
   
         /**
          * Returns the type of action.
          * @param {object} actionDetail
          * @return {string} Action type as string
          */
         function getActionInfo(actionDetail) {
           return getOneOf(actionDetail);
         }
   
         /**
          * Returns user information, or the type of user if not a known user.
          * @param {object} user - User record
          * @return {string} user type as string
          */
         function getUserInfo(user) {
           if ('knownUser' in user) {
             const knownUser = user['knownUser'];
             const isMe = knownUser['isCurrentUser'] || false;
             return isMe ? 'people/me' : knownUser['personName'];
           }
           return getOneOf(user);
         }
   
         /**
          * Returns actor information, or the type of actor if not a user.
          * @param {object} actor - Actor record
          * @return {string} actor type as string
          */
         function getActorInfo(actor) {
           if ('user' in actor) {
             return getUserInfo(actor['user']);
           }
           return getOneOf(actor);
         }
   
         /**
          * Returns the type of a target and an associated title.
          * @param {object} target - Activity target record
          * @return {string} target type as string
          */
         function getTargetInfo(target) {
           if ('driveItem' in target) {
             const title = target.driveItem.title || 'unknown';
             return `driveItem:"${title}"`;
           }
           if ('drive' in target) {
             const title = target.drive.title || 'unknown';
             return `drive:"${title}"`;
           }
           if ('fileComment' in target) {
             const parent = target.fileComment.parent || {};
             const title = parent.title || 'unknown';
             return `fileComment:"${title}"`;
           }
           return `${getOneOf(target)}:unknown`;
         }
       </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 واستدعائه لواجهة برمجة التطبيقات Google Drive Activity API.

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

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