Краткое руководство по JavaScript

Создайте веб-приложение JavaScript, которое отправляет запросы к Gmail API.

В кратких руководствах объясняется, как настроить и запустить приложение, вызывающее Google Workspace API. В этом кратком руководстве используется упрощенный подход к аутентификации, который подходит для тестовой среды. Для рабочей среды рекомендуем изучить информацию об аутентификации и авторизации, прежде чем выбирать учетные данные доступа, подходящие для вашего приложения.

В этом кратком руководстве используются рекомендуемые клиентские библиотеки API Google Workspace, которые упрощают аутентификацию и авторизацию.

Цели

• Настройте среду.
• Настройте образец.
• Запустите пример.

Требования

• Установлены Node.js и npm.
• Проект Google Cloud.

• Аккаунт Google с включенным сервисом Gmail.

Как настроить среду

Чтобы выполнить инструкции из этого руководства, настройте среду.

Включение API

Прежде чем использовать API Google, их нужно включить в облачном проекте Google Cloud. В одном облачном проекте Google Cloud можно включить один или несколько API.

• В консоли Google Cloud включите Gmail API.

  Включите API

Как настроить окно запроса доступа OAuth

Если вы используете новый проект Google Cloud, настройте окно запроса доступа OAuth. Если вы уже выполнили этот шаг для своего облачного проекта, перейдите к следующему разделу.

1. В Google API Console нажмите на значок меню menu > Google Auth platform (Платформа Google Auth) > Branding (Брендинг).

   Перейти к брендингу

2. Если вы уже настроили платформу Google Auth, то можете задать следующие настройки окна запроса доступа OAuth в разделах Брендинг, Аудитория и Доступ к данным. Если вы видите сообщение Google Auth platform not configured yet (Платформа Google Auth ещё не настроена), нажмите Get Started (Начать).
1. В разделе Информация о приложении в поле Название приложения введите название приложения.
2. В поле Электронный адрес службы поддержки укажите адрес, по которому пользователи смогут обращаться с вопросами о согласии.
3. Нажмите Далее.
4. В разделе Аудитория выберите Внутренние.
5. Нажмите Далее.
6. В разделе Контактная информация укажите адрес электронной почты, на который вы хотите получать уведомления об изменениях в проекте.
7. Нажмите Далее.
8. В разделе Завершение ознакомьтесь с Правилами в отношении пользовательских данных сервисов API Google и, если вы согласны с ними, установите флажок Я принимаю Правила в отношении пользовательских данных сервисов API Google.
9. Нажмите Продолжить.
10. Нажмите Создать.
3. Пока вы можете пропустить добавление областей действия. Если в будущем вы создадите приложение для использования за пределами организации Google Workspace, вам нужно будет изменить тип пользователя на Внешний. Затем добавьте области авторизации, необходимые для вашего приложения. Подробную информацию вы найдете в руководстве по настройке запроса согласия OAuth.

Как авторизовать учетные данные для веб-приложения

Чтобы аутентифицировать конечных пользователей и получить доступ к их данным в приложении, создайте один или несколько идентификаторов клиента OAuth 2.0. Идентификатор клиента используется для идентификации одного приложения на серверах OAuth Google. Если ваше приложение работает на нескольких платформах, вам нужно создать отдельный идентификатор клиента для каждой из них.

1. В консоли Google Cloud нажмите на значок меню menu > Google Auth platform (Платформа Google Auth) > Clients (Клиенты).

   Перейти в раздел "Клиенты"

2. Нажмите Create Client (Создать клиента).
3. Нажмите Тип приложения > Веб-приложение.
4. В поле Name (Название) введите название учетных данных. Это название показывается только в консоли Google Cloud.
5. Добавьте авторизованные URI, связанные с вашим приложением:
   • Клиентские приложения (JavaScript). В разделе Разрешенные источники JavaScript нажмите Добавить URI. Затем введите URI, который будет использоваться для запросов браузера. Это домены, из которых ваше приложение может отправлять запросы к API на сервер OAuth 2.0.
   • Серверные приложения (Java, Python и т. д.) – в разделе Разрешенные URI перенаправления нажмите Добавить URI. Затем введите URI конечной точки, на который сервер OAuth 2.0 может отправлять ответы.
6. Если ваше приложение – это ИИ-агент, который выполняет действия от имени пользователей, выберите Использовать этот клиент для агента на основе ИИ. Если ваше приложение поддерживает как рабочие процессы ИИ-агентов, так и стандартные пользовательские функции, создайте отдельные клиенты OAuth для каждого случая. После создания клиента изменить эту настройку нельзя.
7. Нажмите Создать.

   Новые учетные данные появятся в разделе Идентификаторы клиентов OAuth 2.0.

   Обратите внимание, что секретные коды клиентов не используются для веб-приложений.

8. Сохраните идентификатор клиента, чтобы использовать его позже в этом кратком руководстве.

Создание ключа API

1. В консоли Google Cloud нажмите на значок меню menu > APIs & Services (API и сервисы) > Credentials (Учетные данные).

   Перейти к учетным данным

2. Нажмите Create credentials (Создать учетные данные) > API key (Ключ API).
3. Появится новый ключ API.
   • Нажмите "Копировать" content_copy, чтобы скопировать ключ API для использования в коде приложения. Ключ API также можно найти в разделе "Ключи API" учетных данных проекта.
   • Чтобы предотвратить несанкционированное использование, рекомендуем ограничить места и API, для которых можно использовать ключ API. Подробнее о том, как добавить ограничения API…

Настройка образца

1. В рабочем каталоге создайте файл с названием index.html.

2. Вставьте в файл 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 – созданный вами ключ API.

Запустите пример

1. В рабочей папке установите пакет http-server:

   npm install http-server
   

2. Запустите веб-сервер из своего рабочего каталога. Для этого используйте следующую команду:

   npx http-server -p 8000
   

3. В браузере перейдите на страницу http://localhost:8000.
4. Появится запрос на предоставление доступа:
   1. Если вы ещё не вошли в аккаунт Google, сделайте это. Если вы вошли в несколько аккаунтов, выберите один из них для авторизации.
   2. Нажмите Принимаю.

Ваше JavaScript-приложение запускается и вызывает Gmail API.

Дальнейшие действия

• Попробуйте Google Workspace API в API Explorer
  • Устранение неполадок с аутентификацией и авторизацией
  • Справочная документация по Gmail API
  • Раздел google-api-javascript-client на GitHub