Обновите прикрепленные файлы Link до дополнительных файлов Класса.

Один из способов, которым учителя могут добавлять сторонний контент в Classroom, — это вставить ссылку в виде вложения-ссылки на странице создания задания. Чтобы расширить возможности, уже знакомые учителям, теперь вы можете настроить надстройку так, чтобы она позволяла учителям преобразовывать вложение-ссылку в дополнение .

Обзор

Если вы настроите надстройку с этой возможностью, преподавателям будет предложено обновить ссылку на вложение надстройки при вставке ссылки на страницу создания задания. Предложение сделать это будет выдано только в том случае, если у них уже установлено дополнение.

После того, как преподаватель соглашается обновить ссылку до дополнительного вложения, запускается iframe обновления ссылки со следующими параметрами запроса:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (только если пользователь уже авторизовал ваше приложение)

Первые четыре параметра запроса соответствуют параметрам запроса, запущенным в iframe обнаружения вложений . Параметр запроса urlToUpgrade является новым и может помочь вам оценить, как следует создавать вложение-надстройку. Затем вы можете использовать другие параметры запроса для проверки того, вошёл ли пользователь в систему, и вызвать метод CreateAddOnAttachment для courseWork , courseWorkMaterials или announcements в зависимости от значения itemType . В iframe можно отобразить экран загрузки, чтобы сообщить преподавателю о создании вложения-надстройки.

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

Технические детали реализации

В этом разделе освещаются некоторые важные технические детали этой функции.

Прочитайте параметр запроса urlToUpgrade

Параметр запроса urlToUpgrade кодируется в URI при передаче в iframe Link Upgrade. Для получения исходного URL необходимо декодировать его. Например, если вы используете JavaScript, для этого можно использовать функцию decodeURIComponent() .

Чтобы обеспечить оптимальную работу этой функции, отправьте postMessage после успешного создания вложения-дополнения. Это закроет iframe. Подробнее см . на странице с описанием реализации iframe .

Подробности конфигурации

Для интеграции этой функции в ваше дополнение необходимы следующие конфигурации:

  • URL-адрес для iframe обновления ссылки : это URL-адрес, который открывается в iframe, когда учитель соглашается на обновление.

  • Шаблоны URL, которые Classroom должен обнаружить и попытаться обновить : Шаблоны URL могут состоять из хоста и нескольких префиксов пути.

    • Вы можете предоставить несколько шаблонов URL.
    • Если вы не укажете никаких префиксов пути, можно обновить любой URL-адрес, соответствующий хосту.
    • Обновляться могут только URL-адреса со схемой https .
    • Шаблоны URL не должны содержать localhost .
    • Префиксы пути не должны содержать параметры запроса или фрагменты URL.
    • В настоящее время префиксы путей могут поддерживать подстановочные знаки, но хосты не могут:
      • example.com — допустимый хост, а /foo и /bar/*/baz — допустимые префиксы пути.
      • example.*.host.com не является допустимым хостом.
    • Подстановочный знак между компонентами префикса пути соответствует только одному компоненту и не соответствует нескольким компонентам, разделённым косой чертой. Рассмотрим шаблон URL с хостом example.com и префиксом пути /bar/*/baz :
      • https://example.com/bar/123/baz является допустимым соответствием шаблону URL.
      • https://example.com/bar/123/baz/456/789 является допустимым соответствием шаблону URL.
      • https://example.com/bar/123/456/baz не является допустимым соответствием шаблону URL, поскольку подстановочный знак в префиксе пути не соответствует /123/456/ .

Процесс разработки

Отправьте URL-адрес iframe обновления ссылок и шаблоны URL-адресов для вашего тестового или производственного дополнения по электронной почте на адрес classroom-link-upgrade-external@google.com .

Вы можете предоставить конфигурации для любого проекта Google Cloud, представляющего собой надстройку Classroom. Мы рекомендуем сначала предоставить конфигурации для надстройки с приватным доступом, чтобы можно было разрабатывать и тестировать её в демонстрационном домене, не влияя на реальных пользователей.

Вы получите ответ на свой адрес электронной почты, как только настройки будут активированы. Обратите внимание, что шаблоны URL, использующие localhost , не поддерживаются для этой функции.

Отформатируйте электронное письмо, включив в него следующее:

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
-   Host:HOST_1
-   Path prefixes:
  -   PATH_PREFIX_1
  -   PATH_PREFIX_2

-   Host:HOST_2
-   Path prefixes:
  -   PATH_PREFIX_3
  -   PATH_PREFIX_4

// add more hosts and path prefixes as needed

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

  • GCP_PROJECT_NUMBER : номер проекта Google Cloud, с которым связано дополнение.
  • LINK_UPGRADE_IFRAME_URL : URL-адрес, который должен открываться в iframe обновления ссылки.
  • HOST_1 : Хост, который Classroom должен обнаружить. Поддерживается только схема https .
  • PATH_PREFIX_1 и PATH_PREFIX_2 : префиксы пути, связанные с HOST_1 , которые Classroom должен обнаружить и попытаться обновить.
  • HOST_2 : Хост, который Classroom должен обнаружить. Поддерживается только схема https .
  • PATH_PREFIX_3 и PATH_PREFIX_4 : префиксы пути, связанные с HOST_2 , которые Classroom должен обнаружить и попытаться обновить.

Ниже приведены рекомендации, которые следует учитывать при реализации этой функции.

Избегайте дополнительной работы для учителей

Мы настоятельно рекомендуем использовать iframe для упрощения входа в систему (при необходимости) или отображения индикатора загрузки. Для максимального удобства пользователя не следует запрашивать у преподавателя дополнительную информацию после того, как он согласился обновить вставленную ссылку до вложения к дополнению. Однако, если это невозможно для вашего дополнения, вы можете использовать iframe «Обновление ссылки» для сбора необходимой дополнительной информации. iframe также можно использовать для уведомления преподавателя о невозможности обновления ссылки или о возникновении ошибки.

Включать понятные сообщения об ошибках доступа

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