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

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

أنشئ تطبيق ويب بلغة JavaScript يرسل طلبات إلى Gmail API.

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

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

الأهداف

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

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

Node.js وnpm مثبَّتان.
مشروع على Google Cloud:

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

إعداد البيئة

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

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

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

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

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

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

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

في Google API Console، انتقِل إلى "القائمة" > منصة مصادقة Google > العلامة التجارية.
الانتقال إلى "هوية العلامة التجارية"
إذا سبق لك ضبط إعدادات Google Auth Platform، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في الهوية البصرية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة تفيد بأنّه لم يتم إعداد منصة Google Auth بعد، انقر على البدء:

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

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

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

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

في Google Cloud Console، انتقِل إلى "القائمة" > منصة Google Auth > العملاء.
الانتقال إلى "العملاء"
انقر على إنشاء عميل (Create Client).
انقر على نوع التطبيق > تطبيق ويب.
في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud Console.
أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة ذات الصلة بتطبيقك:
- التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف موارد منتظم (URI) لاستخدامه في طلبات المتصفّح. يحدّد هذا الإعداد النطاقات التي يمكن لتطبيقك إرسال طلبات بيانات من واجهة برمجة التطبيقات منها إلى خادم OAuth 2.0.
- التطبيقات من جهة الخادم (Java وPython والمزيد): ضمن معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف موارد منتظم (URI) لنقطة النهاية يمكن لخادم OAuth 2.0 إرسال الردود إليه.
اختياري: إذا كان تطبيقك عبارة عن وكيل ذكاء اصطناعي يتّخذ إجراءات نيابةً عن المستخدمين، اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي. إذا كان تطبيقك يتيح كلاً من سير عمل وكيل الذكاء الاصطناعي وميزات المستخدم العادية، أنشئ عملاء OAuth منفصلين لكل منهما. لا يمكنك تغيير هذا الإعداد بعد إنشاء العميل.
انقر على إنشاء.
تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عملاء OAuth 2.0.

يُرجى العِلم أنّ أسرار العميل لا تُستخدَم في تطبيقات الويب.
احفظ معرّف العميل لاستخدامه لاحقًا في دليل التشغيل السريع هذا.

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

في وحدة تحكّم Google Cloud، انتقِل إلى "القائمة" > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
الانتقال إلى "بيانات الاعتماد"
انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
سيتم عرض مفتاح واجهة برمجة التطبيقات الجديد.
- انقر على "نسخ" لنسخ مفتاح واجهة برمجة التطبيقات لاستخدامه في رمز تطبيقك. يمكن أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
- لمنع الاستخدام غير المصرّح به، ننصحك بفرض قيود على مكان استخدام مفتاح واجهة برمجة التطبيقات وواجهات برمجة التطبيقات التي يمكن استخدامه معها. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إضافة قيود على واجهة برمجة التطبيقات.

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

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

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

gmail/quickstart/index.html

العرض على GitHub

<!DOCTYPE html>
<html>
  <head>
    <title>Gmail API Quickstart</title>
    <meta charset="utf>-8&<quot;> /
<  /h>ead
 < >body
    pGmail API <Qu>icksta<rt/p

    !--Add buttons to initiate auth sequence and >sign <out--
    button id="authorize_button" onclick>="ha<ndleAut>hClic<k()"Authorize/button
    button id="signout_but>ton"<; oncli>ck=&qu<ot;handleSignoutClick()"Sign Out/button

 ><   p>re id=<"content" style=&qu>ot;white-space: pre-wrap;"/pre

    script type="text/javascript"
      /* exported gapiLoaded */
      /* exported gisLoaded */
      /* exported handleAuthClick */
      /* exported handleSignoutClick */

      // TODO(developer): S<et to client I>D and API key from the Dev<eloper Conso>le
      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 = 'vis>ible';
        }
      }

      /**
       *  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.getElemen<tById(&>#39;c<ontent').innerText = 'No labels found.';
          return;
        }><
      >  // <Flatten to string to display
        const output = labels.reduce(
            (str,>< label)> = <`${st>r<}${la>bel.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

غيِّر القيم في السلسلة على الشكل التالي:

‫YOUR_CLIENT_ID: معرّف العميل الذي أنشأته عند تفويض بيانات الاعتماد لتطبيق ويب
‫YOUR_API_KEY: مفتاح واجهة برمجة التطبيقات الذي أنشأته.

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

في دليل العمل، ثبِّت حزمة http-server:
```
npm install http-server
```
في دليل العمل، ابدأ خادم ويب:
```
npx http-server -p 8000
```

في المتصفّح، انتقِل إلى http://localhost:8000.
سيظهر لك طلب لمنح الإذن بالوصول:
1. إذا لم تكن مسجِّلاً الدخول إلى حساب Google، سجِّل الدخول عندما يُطلب منك ذلك. إذا كنت مسجّلاً الدخول إلى حسابات متعددة، اختَر حسابًا واحدًا لاستخدامه في التفويض.
2. انقر على قبول.

يتم تشغيل تطبيق JavaScript واستدعاء Gmail API.

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

تجربة واجهات برمجة تطبيقات Google Workspace في "مستكشف واجهات برمجة التطبيقات"

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