Обзор веб-приложений

API Google Picker — это JavaScript-API, который можно использовать в веб-приложениях, чтобы пользователи могли выбирать или загружать файлы из Google Диска. Пользователи могут предоставлять вашим приложениям разрешение на доступ к своим данным в Диске, обеспечивая безопасный и авторизованный способ взаимодействия со своими файлами.

Инструмент Google Picker действует как диалоговое окно «Открыть файл» для информации, хранящейся на Google Диске, и обладает рядом функций:

• Похожий внешний вид и функциональность на интерфейс Google Drive .
• Несколько вариантов отображения, показывающих предварительный просмотр и миниатюрные изображения файлов Google Drive.
• Встроенное модальное окно, благодаря которому пользователи никогда не покидают основное приложение.

Обратите внимание, что Google Picker не позволяет пользователям упорядочивать, перемещать или копировать файлы из одной папки в другую. Для управления файлами необходимо использовать либо API Google Drive , либо пользовательский интерфейс Drive.

Предварительные требования

Приложения, использующие Google Picker, должны соблюдать все действующие Условия предоставления услуг . Самое важное – вы должны корректно указывать свои данные в запросах.

У вас также должен быть проект в Google Cloud .

Настройте свою среду

Для начала использования API Google Picker необходимо настроить рабочую среду.

Включить API

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

  Включить API

Создайте ключ API

Ключ API представляет собой длинную строку, содержащую буквы верхнего и нижнего регистра, цифры, символы подчеркивания и дефисы, например, AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe . Этот метод аутентификации используется для анонимного доступа к общедоступным данным, таким как файлы Google Workspace, предоставленные с помощью параметра общего доступа «Любой пользователь в Интернете по этой ссылке». Для получения более подробной информации см. раздел «Управление ключами API» .

Для создания ключа API:

1. В консоли Google Cloud перейдите в menu > API и сервисы > Учетные данные .

   Перейдите в раздел «Учетные данные».

2. Нажмите «Создать учетные данные» > «Ключ API» .
3. Ваш новый API-ключ отображен.
   • Нажмите «Копировать content_copy , чтобы скопировать ключ API для использования в коде вашего приложения. Ключ API также можно найти в разделе «Ключи API» в учетных данных вашего проекта.
   • Для предотвращения несанкционированного использования мы рекомендуем ограничить места и типы API, для которых можно использовать ключ API. Более подробную информацию см. в разделе «Добавление ограничений API» .

Авторизация учетных данных для веб-приложения

Важно: при создании объекта Picker ваше приложение должно отправлять токен доступа OAuth 2.0 вместе с представлениями, которые получают доступ к личным данным пользователя. Чтобы запросить токен доступа, см. раздел «Использование OAuth 2.0 для доступа к API Google» .

Управление выбором Google

В оставшейся части этого руководства рассматривается, как загрузить и отобразить Google Picker из веб-приложения, а также реализовать функцию обратного вызова. Полный пример см. в разделе «Пример кода для веб-приложений» .

Загрузите библиотеку Google Picker.

Для загрузки библиотеки Google Picker вызовите метод gapi.load , указав имя библиотеки и функцию обратного вызова, которая будет вызвана после успешной загрузки:

    <script>
      let tokenClient;
      let accessToken = null;
      let pickerInited = false;
      let gisInited = false;

      // Use the API Loader script to load google.picker.
      function onApiLoad() {
        gapi.load('picker', onPickerApiLoad);
      }

      function onPickerApiLoad() {
        pickerInited = true;
      }

      function gisLoaded() {
        // Replace with your client ID and required scopes.
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'CLIENT_ID',
          scope: 'SCOPES',
          callback: '', // defined later
        });
        gisInited = true;
    }
    </script>
    <!-- Load the Google API Loader script. -->
    <script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>

Замените следующее:

• CLIENT_ID : Идентификатор клиента вашего веб-приложения.
• SCOPES : Одна или несколько областей доступа OAuth 2.0, которые вам необходимо запросить для доступа к API Google, в зависимости от необходимого уровня доступа. Для получения дополнительной информации см. раздел «Области доступа OAuth 2.0 для API Google» .

Библиотека JavaScript google.accounts.oauth2 помогает запрашивать согласие пользователя и получать токен доступа для работы с данными пользователя. Метод initTokenClient инициализирует новый клиент токена с идентификатором клиента вашего веб-приложения. Для получения дополнительной информации см. раздел «Использование модели токенов» .

Функция onApiLoad загружает библиотеки Google Picker. Функция обратного вызова onPickerApiLoad вызывается после успешной загрузки библиотеки Google Picker.

Примечание: Если вы используете TypeScript, вы можете установить @types/google.picker , чтобы использовать window.google.picker . Чтобы сообщить о проблеме с этими типами, создайте заявку в службу поддержки .

Отобразить Google Выбор

Функция createPicker гарантирует завершение загрузки API Google Picker и создание токена OAuth 2.0. Используйте метод PickerBuilder.setAppId , чтобы установить идентификатор приложения Google Drive, используя номер проекта Cloud, что позволит приложению получить доступ к файлам пользователя. Затем эта функция создает экземпляр Google Picker и отображает его:

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // Replace with your API key and App ID.
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('API_KEY')
            .setCallback(pickerCallback)
            .setAppId('APP_ID')
            .build();
        picker.setVisible(true);
      }

      // Request an access token.
      tokenClient.callback = async (response) => {
        if (response.error !== undefined) {
          throw (response);
        }
        accessToken = response.access_token;
        showPicker();
      };

      if (accessToken === 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: ''});
      }
    }

Замените следующее:

• API_KEY : Ваш API-ключ.
• APP_ID : Номер вашего облачного проекта.

Для создания экземпляра Google Picker необходимо создать объект Picker с помощью класса PickerBuilder . Класс PickerBuilder принимает View , токен OAuth 2.0, ключ разработчика и функцию обратного вызова, которая будет вызываться в случае успеха ( pickerCallback ).

Объект Picker отображает только одно View за раз. Укажите как минимум одно представление, либо по ViewId ( google.picker.ViewId.* ), либо создав экземпляр DocsView для дополнительного контроля над тем, как отображается представление.

Если в Google Picker добавлено несколько представлений, пользователи могут переключаться между ними, щелкая вкладку слева. Вкладки можно логически группировать с помощью объектов ViewGroup .

Список допустимых представлений см. в ViewId в справочнике Google Picker. Чтобы получить токен для любого из этих представлений, используйте область действия https://www.googleapis.com/auth/drive.file .

Реализуйте функцию обратного вызова для выбора элементов в Google Picker.

Функция обратного вызова Google Picker может использоваться для реагирования на действия пользователя в Google Picker, например, на выбор файла или нажатие кнопки «Отмена». Интерфейс ResponseObject передает информацию о выборе пользователя.

    // A callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        const doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      const message = `You picked: ${url}`;
      document.getElementById('result').textContent = message;
    }

Функция обратного вызова получает объект данных в формате JSON. Этот объект содержит Action пользователь выполняет с помощью Google Picker ( google.picker.Response.ACTION ). Если пользователь выбирает элемент, массив google.picker.Response.DOCUMENTS также заполняется. В этом примере на главной странице отображается google.picker.Document.URL . Подробную информацию о полях данных см. в интерфейсе ResponseObject .

Фильтрация по определенным типам файлов

Используйте ViewGroup для фильтрации определенных элементов. В следующем примере кода показано, как в дочернем представлении "Диск" отображаются только документы и презентации.

    const picker = new google.picker.PickerBuilder()
        .addViewGroup(
          new google.picker.ViewGroup(google.picker.ViewId.DOCS)
              .addView(google.picker.ViewId.DOCUMENTS)
              .addView(google.picker.ViewId.PRESENTATIONS))
        .setOAuthToken(oauthToken)
        .setDeveloperKey(developerKey)
        .setAppId(cloudProjectNumber)
        .setCallback(pickerCallback)
        .build();

Список допустимых типов представлений см. в ViewId .

Настройте внешний вид инструмента выбора Google.

С помощью объекта Feature можно включать или выключать функции для различных представлений. Для точной настройки внешнего вида окна Google Picker используйте методы PickerBuilder.enableFeature или PickerBuilder.disableFeature . Например, если у вас только одно представление, вы можете скрыть панель навигации ( Feature.NAV_HIDDEN ), чтобы предоставить пользователям больше места для просмотра элементов.

В следующем примере кода показана реализация функции выбора объекта поиска в электронной таблице:

    const picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.SPREADSHEETS)
        .enableFeature(google.picker.Feature.NAV_HIDDEN)
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();