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

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

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

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

Цели

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

Требования

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

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

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

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

Включение API

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

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

  Включите API

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

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

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

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

2. Если вы уже настроили платформу аутентификации Google, вы можете задать следующие настройки окна запроса доступа 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 нажмите на значок меню > Платформа аутентификации Google > Клиенты.

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

2. Нажмите Создать клиента.
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 нажмите на значок меню > APIs & Services (API и сервисы) > Credentials (Учетные данные).

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

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

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

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

2. Вставьте в файл index.html следующий образец кода:

   people/quickstart/index.html

   Посмотреть на GitHub
   <!DOCTYPE html>
   <html>
     <head>
       <title>People API Quickstart</title>
       <meta charset="utf-8" />
     </head>
     <body>
       <p>People 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/people/v1/rest';
   
         // Authorization scopes required by the API; multiple scopes can be
         // included, separated by spaces.
         const SCOPES = 'https://www.googleapis.com/auth/contacts.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 listConnectionNames();
           };
   
           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 display name if available for 10 connections.
          */
         async function listConnectionNames() {
           let response;
           try {
             // Fetch first 10 files
             response = await gapi.client.people.people.connections.list({
               'resourceName': 'people/me',
               'pageSize': 10,
               'personFields': 'names,emailAddresses',
             });
           } catch (err) {
             document.getElementById('content').innerText = err.message;
             return;
           }
           const connections = response.result.connections;
           if (!connections || connections.length == 0) {
             document.getElementById('content').innerText = 'No connections found.';
             return;
           }
           // Flatten to string to display
           const output = connections.reduce(
               (str, person) => {
                 if (!person.names || person.names.length === 0) {
                   return `${str}Missing display name\n`;
                 }
                 return `${str}${person.names[0].displayName}\n`;
               },
               'Connections:\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-приложение запускается и вызывает People API.

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

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