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

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

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

يمكنك إنشاء تطبيق ويب JavaScript ينشئ الطلبات إلى Google Sheets API.

الأهداف

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

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

• Node.js & عدد النبضات في الدقيقة مثبت.
• Google Cloud مشروعك.

• حساب على Google

إعداد البيئة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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، انتقِل إلى القائمة menu. > واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد.

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

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

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

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

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

   sheets/quickstart/index.html

   عرض على GitHub

   <!DOCTYPE html>
   <html>
     <head>
       <title>Sheets API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>Sheets 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://sheets.googleapis.com/$discovery/rest?version=v4';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/spreadsheets.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 listMajors();
           };
   
           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 and majors of students in a sample spreadsheet:
          * https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
          */
         async function listMajors() {
           let response;
           try {
             // Fetch first 10 files
             response = await gapi.client.sheets.spreadsheets.values.get({
               spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
               range: 'Class Data!A2:E',
             });
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
           const range = response.result;
           if (!range || !range.values || range.values.length == 0) {
             document.getElementById('content').innerText = 'No values found.';
             return;
           }
           // Flatten to string to display
           const output = range.values.reduce(
               (str, row) => `${str}${row[0]}, ${row[4]}\n`,
               'Name, Major:\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 Sheets API.

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

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