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

Quickstarts نحوه راه‌اندازی و اجرای برنامه‌ای را توضیح می‌دهد که Google Workspace API را فراخوانی می‌کند.

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

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

اهداف

  • محیط خود را تنظیم کنید.
  • نمونه را تنظیم کنید
  • نمونه را اجرا کنید.

پیش نیازها

  • یک حساب Google با فعال بودن جیمیل.

محیط خود را تنظیم کنید

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

API را فعال کنید

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

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

  1. در کنسول Google Cloud، به منو > APIs & Services > صفحه رضایت OAuth بروید.

    به صفحه رضایت OAuth بروید

  2. برای نوع User Internal را انتخاب کنید، سپس روی Create کلیک کنید.
  3. فرم ثبت نام برنامه را تکمیل کنید، سپس روی ذخیره و ادامه کلیک کنید.

  4. در حال حاضر، می‌توانید از افزودن دامنه‌ها صرفنظر کنید و روی ذخیره و ادامه کلیک کنید. در آینده، وقتی برنامه‌ای را برای استفاده خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید و سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید.

  5. خلاصه ثبت برنامه خود را مرور کنید. برای ایجاد تغییرات، روی ویرایش کلیک کنید. اگر ثبت برنامه خوب به نظر می رسد، روی بازگشت به داشبورد کلیک کنید.

اعتبارنامه یک برنامه وب را تأیید کنید

برای احراز هویت کاربران نهایی و دسترسی به داده های کاربر در برنامه خود، باید یک یا چند شناسه مشتری OAuth 2.0 ایجاد کنید. شناسه مشتری برای شناسایی یک برنامه واحد در سرورهای OAuth Google استفاده می شود. اگر برنامه شما روی چندین پلتفرم اجرا می شود، باید برای هر پلتفرم یک شناسه مشتری جداگانه ایجاد کنید.
  1. در کنسول Google Cloud، به منو > APIs & Services > Credentials بروید.

    به Credentials بروید

  2. روی ایجاد اعتبارنامه > شناسه مشتری OAuth کلیک کنید.
  3. روی نوع برنامه > برنامه وب کلیک کنید.
  4. در قسمت نام ، نامی را برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نشان داده می شود.
  5. URI های مجاز مرتبط با برنامه خود را اضافه کنید:
    • برنامه‌های سمت کلاینت (جاوا اسکریپت) - در زیر مبدا مجاز جاوا اسکریپت ، روی افزودن URI کلیک کنید. سپس، یک URI را برای استفاده برای درخواست های مرورگر وارد کنید. این دامنه‌هایی را که برنامه شما می‌تواند درخواست‌های API را به سرور OAuth 2.0 ارسال کند، مشخص می‌کند.
    • برنامه‌های سمت سرور (جاوا، پایتون و موارد دیگر) - در زیر URI‌های مجاز تغییر مسیر ، روی Add URI کلیک کنید. سپس، یک URI نقطه پایانی را وارد کنید که سرور OAuth 2.0 می‌تواند پاسخ‌ها را به آن ارسال کند.
  6. روی ایجاد کلیک کنید. صفحه ایجاد شده توسط سرویس گیرنده OAuth ظاهر می شود که شناسه مشتری و راز مشتری جدید شما را نشان می دهد.

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

  7. روی OK کلیک کنید. اعتبار جدید ایجاد شده در شناسه های مشتری OAuth 2.0 ظاهر می شود.

این اعتبارنامه ها را یادداشت کنید زیرا بعداً در این شروع سریع به آنها نیاز خواهید داشت.

یک کلید API ایجاد کنید

  1. در کنسول Google Cloud، به منو > APIs & Services > Credentials بروید.

    به Credentials بروید

  2. روی ایجاد اعتبارنامه > کلید API کلیک کنید.
  3. کلید API جدید شما نمایش داده می شود.
    • روی Copy کلیک کنید تا کلید API خود را برای استفاده در کد برنامه خود کپی کنید. کلید API را می‌توانید در بخش «کلیدهای API» اعتبار پروژه‌تان پیدا کنید.
    • برای به‌روزرسانی تنظیمات پیشرفته و محدود کردن استفاده از کلید API، روی Restrict key کلیک کنید. برای جزئیات بیشتر، به اعمال محدودیت‌های کلید API مراجعه کنید.

نمونه را تنظیم کنید

  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. در پوشه کاری خود، بسته http-server را نصب کنید:

    npm install http-server

  2. در فهرست کاری خود، یک وب سرور راه اندازی کنید:

    npx http-server -p 8000
  1. در مرورگر خود به http://localhost:8000 بروید.
  2. یک اعلان برای مجوز دسترسی می بینید:
    1. اگر قبلاً وارد حساب Google خود نشده اید، هنگامی که از شما خواسته شد وارد شوید. اگر به چندین حساب وارد شده اید، یک حساب را برای استفاده از مجوز انتخاب کنید.
    2. روی Accept کلیک کنید.

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

مراحل بعدی