شروع سریع جاوا اسکریپت

برنامه وب جاوا اسکریپتی ایجاد کنید که درخواست‌هایی به Directory API ارسال کند.

«شروع‌های سریع» نحوه راه‌اندازی و اجرای برنامه‌ای را که میانای برنامه‌سازی کاربردی Google Workspace را فراخوانی می‌کند توضیح می‌دهد. این شروع سریع از یک رویکرد اصالت‌سنجی ساده‌شده استفاده می‌کند که برای محیط آزمایشی مناسب است. برای محیط تولید، توصیه می‌کنیم قبل‌از انتخاب کردن اطلاعات اعتباری دسترسی که برای برنامه‌تان مناسب است، درباره اصالت‌سنجی و صدور مجوز اطلاعات کسب کنید.

این شروع سریع از کتابخانه‌های کارخواه میانای برنامه‌سازی کاربردی توصیه‌شده Google Workspace برای مدیریت برخی‌از جزئیات جریان اصالت‌سنجی و صدور مجوز استفاده می‌کند.

اهداف

• محیط را راه‌اندازی کنید.
• نمونه را راه‌اندازی کنید.
• نمونه را اجرا کنید.

پیش‌نیازها

• Node.js و npm نصب شده باشد.
• پروژه Google Cloud.

• دامنه Google Workspace با دسترسی به میانای برنامه‌سازی کاربردی فعال.
• «حساب Google» در آن دامنه با امتیازهای سرپرست.

راه‌اندازی محیط

برای تکمیل این شروع سریع، محیط خود را راه‌اندازی کنید.

فعال کردن میانای برنامه‌سازی کاربردی

قبل‌از استفاده از Google API، باید آن‌ها را در پروژه Google Cloud فعال کنید. می‌توانید یک یا چند میانای برنامه‌سازی کاربردی را در یک پروژه Google Cloud روشن کنید.

• در کنسول Google Cloud، «میانای برنامه‌سازی کاربردی دایرکتوری» را فعال کنید.

  فعال کردن میانای برنامه‌سازی کاربردی

پیکربندی صفحه کسب رضایت OAuth

اگر از پروژه Google Cloud جدیدی برای تکمیل این راهنمای شروع سریع استفاده می‌کنید، صفحه رضایت OAuth را پیکربندی کنید. اگر قبلاً این مرحله را برای پروژه Cloud خود تکمیل کرده‌اید، به بخش بعدی بروید.

1. در «کنسول Google API»، به «منو» menu > پلاتفرم Google Auth > نمانام‌سازی بروید.

   رفتن به نمانام‌سازی

2. اگر قبلاً پلاتفرم «احراز هویت Google» را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه موافقت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم «احراز هویت Google» هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:
1. در بخش اطلاعات برنامه، در قسمت نام برنامه، نامی برای برنامه وارد کنید.
2. در ایمیل پشتیبانی کاربر، نشانی ایمیل پشتیبانی را انتخاب کنید تا کاربران بتوانند درصورت داشتن سؤال درباره رضایتشان با شما تماس بگیرند.
3. روی بعدی کلیک کنید.
4. در بخش مخاطبان، داخلی را انتخاب کنید.
5. روی بعدی کلیک کنید.
6. در بخش اطلاعات تماس، نشانی ایمیلی را وارد کنید که بتوانید ازطریق آن از هرگونه تغییر در پروژه‌تان مطلع شوید.
7. روی بعدی کلیک کنید.
8. در بخش پایان، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و اگر موافقید، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
9. روی ادامه کلیک کنید.
10. روی ایجاد کردن کلیک کنید.
3. فعلاً می‌توانید از افزودن دامنه‌ها صرف‌نظر کنید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید. سپس محدوده‌های مجوز موردنیاز برنامه‌تان را اضافه کنید. برای کسب اطلاعات بیشتر، راهنمای کامل پیکربندی رضایت OAuth را ببینید.

مجاز کردن اطلاعات اعتباری برای برنامه وب

برای اصالت‌سنجی کاربران نهایی و دسترسی به داده‌های کاربر در برنامه‌تان، باید یک یا چند شناسه کارخواه OAuth 2.0 ایجاد کنید. از شناسه کارخواه برای شناسایی یک برنامه واحد در سرورهای OAuth Google استفاده می‌شود. اگر برنامه‌تان در چند پلاتفرم اجرا می‌شود، باید برای هر پلاتفرم شناسه کارخواه جداگانه‌ای ایجاد کنید.

1. در «کنسول Google Cloud»، به «منو» menu > پلاتفرم Google Auth > کاربران بروید.

   رفتن به «مشتریان»

2. روی ایجاد کارخواه کلیک کنید.
3. روی نوع برنامه > برنامه وب کلیک کنید.
4. در فیلد نام، نامی برای اطلاعات اعتباری تایپ کنید. این نام فقط در Google Cloud Console نشان داده می‌شود.
5. ‫URIهای مجاز مربوط به برنامه‌تان را اضافه کنید:
   • برنامه‌های سمت کارخواه (جاوا اسکریپت)–در بخش مبدأهای مجاز جاوا اسکریپت، روی افزودن شناسه منبع یکسان کلیک کنید. سپس، نشانی وبی را برای استفاده در درخواست‌های مرورگر وارد کنید. این مورد دامنه‌هایی را که برنامه شما می‌تواند از آن‌ها درخواست‌های API به سرور OAuth 2.0 ارسال کند مشخص می‌کند.
   • برنامه‌های سمت سرور (Java،‏ Python، و غیره)–در بخش نشانی‌های وب هدایت مجاز، روی افزودن نشانی وب کلیک کنید. سپس، یک URI نقطه پایان وارد کنید که سرور OAuth 2.0 بتواند پاسخ‌ها را به آن ارسال کند.
6. اختیاری: اگر برنامه شما عامل هوش مصنوعی است که ازطرف کاربران کنش انجام می‌دهد، استفاده از این کارخواه برای عامل هوش مصنوعی را انتخاب کنید. اگر برنامه‌تان هم از گردش‌های کاری عامل هوش مصنوعی و هم از ویژگی‌های کاربر استاندارد پشتیبانی می‌کند، برای هرکدام کارخواه OAuth جداگانه‌ای ایجاد کنید. پس‌از ایجاد مشتری نمی‌توانید این تنظیم را تغییر دهید.
7. روی ایجاد کردن کلیک کنید.

   اعتبارنامه جدیدی که ایجاد شده است در بخش شناسه‌های کارخواه OAuth 2.0 نشان داده می‌شود.

   توجه داشته باشید که از رمزهای کارخواه برای برنامه‌های وب استفاده نمی‌شود.

8. شناسه کارخواه را برای استفاده بعدی در این راهنمای شروع سریع ذخیره کنید.

ایجاد کلید میانای API (کلید میانای برنامه‌سازی کاربردی)

1. در کنسول Google Cloud، به «منو» menu > میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری بروید.

   رفتن به «اطلاعات اعتباری»

2. روی ایجاد اطلاعات کاربری > کلید میانای برنامه‌سازی کاربردی کلیک کنید.
3. کلید API جدید شما نمایش داده می‌شود.
   • برای کپی کردن کلید API برای استفاده در کد برنامه، روی «کپی کردن» content_copy کلیک کنید. کلید میانای API را می‌توانید در بخش «کلیدهای میانای API» در اعتبارنامه‌های پروژه‌تان نیز پیدا کنید.
   • برای جلوگیری از استفاده غیرمجاز، توصیه می‌کنیم مکان و میاناهای برنامه‌سازی کاربردی‌ای را که کلید میانای برنامه‌سازی کاربردی می‌تواند در آن‌ها استفاده شود محدود کنید. برای جزئیات بیشتر، افزودن محدودیت‌های API را ببینید.

راه‌اندازی نمونه

1. در فهرست راهنمای کاری‌تان، فایلی به‌نام index.html ایجاد کنید.

2. در فایل 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: کلید میانای API که ایجاد کرده‌اید.

اجرای نمونه

1. در دایرکتوری کاری‌تان، بسته http-server را نصب کنید:

   npm install http-server
   

2. در دایرکتوری کاری‌تان، سرور وبی را شروع کنید:

   npx http-server -p 8000
   

3. در مرورگرتان، به http://localhost:8000 بروید.
4. اعلانی برای مجاز کردن دسترسی می‌بینید:
   1. اگر ازقبل به سیستم «حساب Google» خود وارد نشده‌اید، وقتی از شما خواسته شد به سیستم وارد شوید. اگر به سیستم چند حساب وارد شده‌اید، یک حساب را برای استفاده جهت صدور مجوز انتخاب کنید.
   2. روی Accept (پذیرش) کلیک کنید.

برنامه جاوا اسکریپت شما اجرا می‌شود و Directory API را فراخوانی می‌کند.

مراحل بعدی

• امتحان کردن «میاناهای برنامه‌سازی کاربردی Google Workspace» در «کاوشگر میاناهای برنامه‌سازی کاربردی»
  • عیب‌یابی مشکلات اصالت‌سنجی و صدور مجوز
  • راهنمای توسعه‌دهندگان Directory API
  • سند مرجع Directory API
  • بخش google-api-javascript-client GitHub