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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

أنشئ تطبيق ويب جافا سكريبت يقدم طلبات إلى واجهة برمجة تطبيقات Gmail.

الأهداف

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

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

  • حساب Google تم فيه تفعيل Gmail.

إعداد البيئة

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

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

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

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

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

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

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

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

  7. انقر على حسنًا. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.
  8. اختياري: إذا كنت تنشئ بيانات اعتماد باعتبارها متطلبًا أساسيًا لبدء التشغيل السريع في JavaScript، عليك أيضًا إنشاء مفتاح واجهة برمجة تطبيقات.

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

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

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

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

    gmail/quickstart/index.html
    <!DOCTYPE html>
<html>
  <head>
    <title>Gmail API Quickstart</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <p>Gmail 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/gmail/v1/rest';

      // Authorization scopes required by the API; multiple scopes can be
      // included, separated by spaces.
      const SCOPES = 'https://www.googleapis.com/auth/gmail.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 listLabels();
        };

        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 all Labels in the authorized user's inbox. If no labels
       * are found an appropriate message is printed.
       */
      async function listLabels() {
        let response;
        try {
          response = await gapi.client.gmail.users.labels.list({
            'userId': 'me',
          });
        } catch (err) {
          document.getElementById('content').innerText = err.message;
          return;
        }
        const labels = response.result.labels;
        if (!labels || labels.length == 0) {
          document.getElementById('content').innerText = 'No labels found.';
          return;
        }
        // Flatten to string to display
        const output = labels.reduce(
            (str, label) => `${str}${label.name}\n`,
            'Labels:\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>

    استبدل ما يلي:

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

  1. في دليل العمل، ابدأ خادم ويب:

    Python 2.x

    python -m SimpleHTTPServer 8000

    Python

    python3 -m http.server 8000

  2. في متصفّحك، انتقِل إلى http://localhost:8000.

  3. عند تشغيل النموذج لأول مرة، سيطلب منك تفويض الوصول:

    1. إذا لم تكن قد سجلت الدخول إلى حسابك في Google من قبل، فسيُطلب منك تسجيل الدخول. إذا كنت قد سجلت الدخول إلى حسابات متعددة، فحدد حسابًا واحدًا لاستخدامه للتفويض.
    2. انقر على قبول.
    3. انسخ الرمز من المتصفح، والصقه في موجه سطر الأوامر، واضغط على Enter.

    يتم تخزين معلومات التفويض في نظام الملفات، لذا في المرة التالية التي يتم فيها تشغيل نموذج الشفرة، لن تتم مطالبتك بالتفويض.

لقد نجحت في إنشاء أول تطبيق جافا سكريبت يرسل طلبات إلى Gmail API.

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