Przenoszenie załączników z linkami do załączników dodatków do Classroom

Jednym ze sposobów dodawania przez nauczycieli treści innych firm do Classroom jest wklejenie linku jako załącznika w postaci linku na stronie tworzenia projektu. Aby wykorzystać wiedzę nauczycieli, możesz teraz skonfigurować dodatek tak, aby nauczyciele mogli uaktualnić załącznik w postaci linku do załącznika dodatku.

Przegląd

Jeśli skonfigurujesz dodatek z tą funkcją, nauczyciele będą proszeni o uaktualnienie linku do załącznika dodatku, gdy wkleją załącznik w postaci linku na stronie tworzenia projektu. Nauczyciele będą proszeni o to tylko wtedy, gdy mają już zainstalowany dodatek.

Gdy nauczyciel zgodzi się na uaktualnienie linku do załącznika dodatku, zostanie uruchomiony element iframe uaktualnienia linku z tymi parametrami zapytania:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (tylko jeśli użytkownik autoryzował już Twoją aplikację)

Pierwsze 4 parametry zapytania odzwierciedlają parametry zapytania uruchomione w elemencie iframe wykrywania załączników . Parametr zapytania urlToUpgrade jest nowy i może pomóc Ci ocenić, jak należy utworzyć załącznik dodatku. Następnie możesz użyć innych parametrów zapytania, aby sprawdzić, czy użytkownik jest zalogowany, i wywołać metodę CreateAddOnAttachment w usłudze courseWork, courseWorkMaterials lub announcements na podstawie wartości itemType. W elemencie iframe możesz wyświetlić ekran wczytywania, aby poinformować nauczyciela, że tworzony jest załącznik dodatku.

Po utworzeniu załącznika dodatku element iframe zostanie zamknięty, a nauczyciel będzie mógł wyświetlić załącznik w projekcie w zwykły sposób.

Szczegóły implementacji technicznej

W tej sekcji znajdziesz ważne informacje techniczne dotyczące tej funkcji.

Odczytywanie parametru zapytania urlToUpgrade

Parametr zapytania urlToUpgrade jest kodowany w formacie URI, gdy jest przekazywany do elementu iframe uaktualnienia linku. Aby uzyskać adres URL w oryginalnej postaci, musisz go zdekodować. Jeśli na przykład używasz JavaScriptu, możesz to zrobić za pomocą funkcji decodeURIComponent().

Aby zapewnić optymalną wygodę użytkowników, po pomyślnym utworzeniu załącznika dodatku wyślij postMessage. Spowoduje to zamknięcie elementu iframe. Więcej informacji znajdziesz na stronie Szczegóły implementacji elementu iframe.

Szczegóły konfiguracji

Aby zintegrować tę funkcję z dodatkiem, musisz skonfigurować te ustawienia:

  • Adres URL elementu iframe uaktualnienia linku: jest to adres URL, który otwiera się w elemencie iframe, gdy nauczyciel zgodzi się na uaktualnienie.

  • Wzorce adresów URL, które Classroom ma wykrywać i próbować uaktualnić: wzorce adresów URL mogą składać się z hosta i kilku prefiksów ścieżki.

    • Możesz podać kilka wzorców adresów URL.
    • Jeśli nie podasz żadnych prefiksów ścieżki, można uaktualnić dowolny adres URL pasujący do hosta.
    • Uaktualnić można tylko adresy URL ze schematem https.
    • Wzorce adresów URL nie mogą zawierać localhost.
    • Prefiksy ścieżki nie mogą zawierać parametrów zapytania ani fragmentów adresów URL.
    • Prefiksy ścieżki mogą obecnie obsługiwać symbole wieloznaczne, ale hosty nie:
      • example.com to prawidłowy host, a /foo i /bar/*/baz to prawidłowe prefiksy ścieżki.
      • example.*.host.com nie jest prawidłowym hostem.
    • Symbol wieloznaczny między komponentami prefiksu ścieżki pasuje tylko do jednego komponentu i nie pasuje do wielu komponentów oddzielonych ukośnikami. Rozważ wzorzec adresu URL z hostem example.com i prefiksem ścieżki /bar/*/baz:
      • https://example.com/bar/123/baz to prawidłowe dopasowanie do wzorca adresu URL.
      • https://example.com/bar/123/baz/456/789 to prawidłowe dopasowanie do wzorca adresu URL.
      • https://example.com/bar/123/456/baz nie jest prawidłowym dopasowaniem do wzorca adresu URL, ponieważ symbol wieloznaczny w prefiksie ścieżki nie pasuje do /123/456/.

Proces programowania

Wyślij adres URL elementu iframe uaktualnienia linku i wzorce adresów URL dla testowego lub produkcyjnego dodatku na adres classroom-link-upgrade-external@google.com.

Możesz podać konfiguracje dla dowolnego projektu w chmurze Google, który reprezentuje dodatek Classroom. Zalecamy, aby najpierw podać konfiguracje dodatku z widocznością prywatną, aby móc programować i testować w domenie demonstracyjnej bez wpływu na aktywnych użytkowników.

Gdy konfiguracje zostaną włączone, otrzymasz odpowiedź na e-maila. Pamiętaj, że w przypadku tej funkcji nie są obsługiwane wzorce adresów URL, które używają localhost.

Sformatuj e-maila tak, aby zawierał te informacje:

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

Zastąp te elementy:

  • GCP_PROJECT_NUMBER: numer projektu w chmurze Google Cloud z którym jest powiązany dodatek.
  • LINK_UPGRADE_IFRAME_URL: adres URL, który powinien otworzyć się w elemencie iframe uaktualnienia linku.
  • HOST_1: host, który ma wykrywać Classroom. Obsługiwany jest tylko schemat https.
  • PATH_PREFIX_1 i PATH_PREFIX_2: prefiksy ścieżki powiązane z HOST_1, które Classroom ma wykrywać i próbować uaktualnić.
  • HOST_2: host, który ma wykrywać Classroom. Obsługiwany jest tylko schemat https.
  • PATH_PREFIX_3 i PATH_PREFIX_4: prefiksy ścieżki powiązane z HOST_2, które Classroom ma wykrywać i próbować uaktualnić.

Oto kilka sugestii, które warto wziąć pod uwagę podczas implementowania tej funkcji.

Unikanie dodatkowej pracy dla nauczycieli

Zdecydowanie zalecamy używanie elementu iframe do ułatwienia logowania (jeśli jest wymagane) lub wyświetlania wskaźnika wczytywania. Aby zapewnić najlepsze wrażenia użytkownikom, po tym, jak nauczyciel zgodzi się na uaktualnienie wklejonego linku do załącznika dodatku, nie powinien być proszony o żadne dodatkowe informacje. Jeśli jednak nie jest to możliwe w przypadku Twojego dodatku, możesz użyć elementu iframe uaktualnienia linku, aby zebrać dodatkowe informacje, których potrzebujesz. Element iframe może też służyć do informowania nauczyciela, jeśli uaktualnienie linku jest niemożliwe lub wystąpił błąd.

Dołączanie przyjaznych dla użytkownika komunikatów o błędach dostępu

Jeśli nauczyciele wkleją i uaktualnią link, do którego nie mają dostępu, wyświetl w elemencie iframe przyjazny dla użytkownika komunikat o błędzie, aby nauczyciele wiedzieli o problemie. Element iframe może też służyć do przyznawania nauczycielowi odpowiednich uprawnień dostępu do treści.