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

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

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

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

الأهداف

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

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

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

• حساب Google

إعداد البيئة

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

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

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

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

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

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

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

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

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

2. إذا سبق لك إعداد منصة Google للمصادقة، يمكنك إعداد إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة لم يتم إعداد منصة Google للمصادقة بعد، انقر على البدء:
1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
3. انقر على التالي.
4. ضمن الجمهور، اختَر داخلي.
5. انقر على التالي.
6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات من خلاله بشأن أي تغييرات تطرأ على مشروعك.
7. انقر على التالي.
8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت موافقًا عليها، ضَع علامة في المربّع أوافق على سياسة بيانات المستخدمين في خدمات Google API.
9. انقر على متابعة.
10. انقر على إنشاء.
3. يمكنك في الوقت الحالي تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على دليل إعداد شاشة موافقة OAuth الكامل Configure OAuth consent.

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

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول 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.

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

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

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

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

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

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.

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

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