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

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

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

أنشئ تطبيق ويب JavaScript لتقديم الطلبات إلى Google Calendar API.

الأهداف

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

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

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

• حساب Google مع تفعيل "تقويم Google"

إعداد البيئة

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

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

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

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

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

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

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

1. في Google Cloud Console، انتقِل إلى القائمة 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 Console.
5. أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة والمرتبطة بتطبيقك:
   • التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف موارد منتظم (URI) لاستخدامه لطلبات المتصفّح. يحدّد هذا العمود النطاقات التي يمكن لتطبيقك من خلالها إرسال طلبات واجهة برمجة التطبيقات إلى خادم OAuth 2.0.
   • التطبيقات من جهة الخادم (Java وPython وغيرهما): ضمن معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) لنقطة النهاية الذي يمكن لخادم OAuth 2.0 إرسال الردود إليه.
6. انقر على إنشاء. تظهر الشاشة التي تم إنشاؤها من خلال عميل OAuth، وتعرض معرِّف العميل وسر العميل الجديدين.

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

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

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

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

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

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

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

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

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

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

   calendar/quickstart/index.html

   العرض على GitHub

   <!DOCTYPE html>
   <html>
     <head>
       <title>Google Calendar API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Google Calendar 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/calendar/v3/rest';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/calendar.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 listUpcomingEvents();
           };
   
           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 summary and start datetime/date of the next ten events in
          * the authorized user's calendar. If no events are found an
          * appropriate message is printed.
          */
         async function listUpcomingEvents() {
           let response;
           try {
             const request = {
               'calendarId': 'primary',
               'timeMin': (new Date()).toISOString(),
               'showDeleted': false,
               'singleEvents': true,
               'maxResults': 10,
               'orderBy': 'startTime',
             };
             response = await gapi.client.calendar.events.list(request);
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
   
           const events = response.result.items;
           if (!events || events.length == 0) {
             document.getElementById('content').innerText = 'No events found.';
             return;
           }
           // Flatten to string to display
           const output = events.reduce(
               (str, event) => `${str}${event.summary} (${event.start.dateTime || event.start.date})\n`,
               'Events:\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 وطلب واجهة برمجة تطبيقات Google Calendar API.

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

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