Обновите прикрепленные файлы 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 также можно использовать для предоставления учителю соответствующих разрешений на доступ к контенту.