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

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

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

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

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

الأهداف

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

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

نطاق Google Workspace تم تفعيل إذن الوصول إلى واجهة برمجة التطبيقات فيه
حساب Google في هذا النطاق يمتلك امتيازات المشرف

إعداد البيئة

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

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

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

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

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

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

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

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

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

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

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

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

في Google Cloud Console، انتقِل إلى "القائمة" > منصة Google Auth > العملاء.
الانتقال إلى "العملاء"
انقر على إنشاء عميل.
انقر على نوع التطبيق > تطبيق الويب.
في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في 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، ألصِق الرمز النموذجي التالي:

adminSDK/directory/index.html

العرض على GitHub

<!DOCTYPE html>
<html>
  <head>
    <title>Directory API Quickstart</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <p>Directory 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/admin/directory_v1/rest';

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

        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 first 10 users in the domain.
       */
      async function listUsers() {
        let response;
        try {
          const request = {
            'customer': 'my_customer',
            'maxResults': 10,
            'orderBy': 'email',
          };
          response = await gapi.client.directory.users.list(request);
        } catch (err) {
          document.getElementById('content').innerText = err.message;
          return;
        }

        const users = response.result.users;
        if (!users || users.length == 0) {
          document.getElementById('content').innerText = 'No users found.';
          return;
        }
        // Flatten to string to display
        const output = users.reduce(
            (str, user) => `${str}${user.primaryEmail} (${user.name.fullName})\n`,
            'Users:\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 واستدعاء واجهة برمجة التطبيقات Directory API.

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

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

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