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

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

Обзор

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

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

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

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

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