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

Jednym ze sposobów dodawania treści innych firm do Classroom jest wklejenie linku jako załącznika z linkiem na stronie tworzenia projektu. Aby wykorzystać wiedzę nauczycieli, możesz teraz skonfigurować dodatek tak, aby umożliwiał im przekształcenie załącznika z linkiem w załącznik dodatku.

Przegląd

Jeśli skonfigurujesz dodatek z tą funkcją, nauczyciele będą otrzymywać prośbę o przekształcenie linku w załącznik dodatku, gdy wkleją załącznik w postaci linku na stronie tworzenia zadania. Nauczyciele są 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 Link Upgrade 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 ramce 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 interfejsu courseWork, courseWorkMaterials lub announcements w zależności od wartości itemType. W elemencie iframe możesz wyświetlić ekran ładowania, aby poinformować nauczyciela, że tworzony jest załącznik dodatku.

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

Szczegóły techniczne implementacji

W tej sekcji znajdziesz ważne szczegóły techniczne dotyczące tej funkcji.

Odczytaj parametr zapytania urlToUpgrade.

Parametr zapytania urlToUpgrade jest kodowany w formacie URI, gdy jest przekazywany w elemencie iframe Link Upgrade. Aby uzyskać adres URL w oryginalnej postaci, musisz go zdekodować. Jeśli na przykład używasz JavaScriptu, możesz w tym celu użyć funkcji decodeURIComponent().

Aby zapewnić optymalną wygodę użytkowników, wyślij postMessage, gdy dodatek zostanie utworzony. Spowoduje to zamknięcie elementu iframe. Więcej informacji znajdziesz na stronie z informacjami o implementacji iframe.

Szczegóły konfiguracji

Aby zintegrować tę funkcję z dodatkiem, musisz zastosować te konfiguracje:

  • Adres URL elementu iframe do ulepszenia linku: jest to adres URL, który otwiera się w elemencie iframe, gdy nauczyciel wyrazi zgodę na ulepszenie.

  • Wzorce adresów URL, które Classroom ma wykrywać i próbować uaktualnić: wzorce adresów URL mogą składać się z hosta i wielu przedrostkó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żek nie mogą zawierać parametrów zapytania ani fragmentów adresu URL.
    • Prefiksy ścieżek mogą obecnie obsługiwać symbole wieloznaczne, ale hosty nie:
      • example.com jest prawidłowym hostem, a /foo i /bar/*/baz są prawidłowym prefiksem ś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 rozdzielonych ukośnikami. Rozważmy wzorzec adresu URL z hostem example.com i prefiksem ścieżki /bar/*/baz:
      • https://example.com/bar/123/baz jest prawidłowym dopasowaniem 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 pasuje do wzorca adresu URL, ponieważ symbol wieloznaczny w prefiksie ścieżki nie pasuje do adresu /123/456/.

Proces programowania

Wyślij adres URL elementu iframe uaktualnienia linku i wzorce adresów URL dla testowego lub produkcyjnego dodatku, wysyłając e-maila na adres classroom-link-upgrade-external@google.com.

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

Gdy konfiguracje zostaną włączone, otrzymasz odpowiedź na e-maila. Pamiętaj, że wzorce adresów URL korzystające z połączenia typu localhost nie są obsługiwane w przypadku tej funkcji.

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

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 następujące elementy:

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

Oto sugestie, które warto wziąć pod uwagę podczas wdrażania tej funkcji.

Unikanie dodatkowej pracy dla nauczycieli

Zdecydowanie zalecamy używanie elementu iframe do ułatwiania logowania (w razie potrzeby) lub wyświetlania wskaźnika wczytywania. Aby zapewnić jak najlepsze wrażenia użytkownikom, po wyrażeniu zgody na uaktualnienie wklejonego linku do załącznika dodatku nauczyciel 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 Link Upgrade, aby zebrać dodatkowe potrzebne informacje. Element iframe może też służyć do informowania nauczyciela, że uaktualnienie linku nie jest możliwe lub wystąpił błąd.

Wyświetlanie zrozumiałych komunikatów o błędach dostępu

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