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

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

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

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

Цели

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

Требования

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

• Домен Google Workspace с включенным доступом к API.
• Аккаунт Google в этом домене с правами администратора.

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

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

Включение API

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

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

  Включите API

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

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

1. В Google API Console нажмите на значок меню > 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. В разделе Finish (Завершение) ознакомьтесь с Правилами в отношении пользовательских данных сервисов API Google и, если вы согласны с ними, выберите I agree to the Google API Services: User Data Policy (Я принимаю Правила в отношении пользовательских данных сервисов API Google).
9. Нажмите Продолжить.
10. Нажмите Создать.
3. Пока вы можете пропустить добавление областей действия. Если в будущем вы создадите приложение для использования за пределами организации Google Workspace, вам нужно будет изменить тип пользователя на Внешний. Затем добавьте области авторизации, необходимые вашему приложению. Подробную информацию вы найдете в руководстве по настройке запроса согласия OAuth.

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

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

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

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

2. Нажмите Создать клиента.
3. Нажмите Тип приложения > Веб-приложение.
4. В поле Название введите название учетных данных. Это название показывается только в консоли 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 нажмите на значок меню > APIs & Services (API и сервисы) > Credentials (Учетные данные).

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

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

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

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

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