Interakcja z załącznikami

Na tej stronie znajdziesz szczegółowe informacje o tworzeniu załączników, zalecane działania, gdy użytkownicy otwierają załączniki, oraz o pracy z zadaniami przesłanymi przez uczniów. Pamiętaj, że podczas wysyłania tych żądań może być konieczne podanie parametrów związanych z załącznikami.

Tworzenie załącznika

Utwórz załącznik, wysyłając żądanie CREATE do odpowiedniego punktu końcowego courses.*.addOnAttachments.create. Żądanie musi zawierać w treści instancję AddOnAttachment.

Podczas tworzenia załącznika wymagane są te pola:

• title – nazwa załącznika.
• teacherViewUri – identyfikator URI widoku nauczyciela załącznika.
• studentViewUri – identyfikator URI widoku ucznia załącznika.
• studentWorkReviewUri– identyfikator URI, który umożliwia nauczycielowi wyświetlenie pracy ucznia w załączniku. To pole jest wymagane tylko w przypadku załączników typu aktywność.

Możesz też uwzględnić niektóre z tych opcjonalnych pól:

• dueDate i dueTime, jeśli chcesz określić termin oddania załącznika.
• maxPoints – maksymalna ocena za załącznik. Jeśli chcesz obsługiwać przekazywanie ocen, musi to być wartość różna od zera. Dotyczy tylko załączników typu aktywność.

Więcej informacji o tych polach znajdziesz w dokumentacji zasobu AddOnAttachment.

Weryfikowanie danych logowania i roli użytkownika

Ramka iframe widoku ucznia, ramka iframe sprawdzania pracy ucznia i ramka iframe widoku nauczyciela służą do wyświetlania treści użytkownikowi, a nie do modyfikowania projektu w Classroom. Gdy otworzy się jeden z tych widoków, wykonaj te czynności:

• Uzyskaj dane logowania OAuth użytkownika.
• Na podstawie itemType wyślij żądanie courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext lub announcements.getAddOnContext , aby zweryfikować rolę użytkownika.
• Sprawdź odpowiedź, aby zobaczyć, czy są w niej TeacherContext lub StudentContext. Można zwrócić tylko jedną z nich, która odpowiada roli użytkownika w kursie.
• Jeśli bieżący użytkownik jest uczniem, a itemType to courseWork, zapisz submissionId z odpowiedzi zawierającej pracę ucznia. submissionIds są zgodne w ramkach iframe dodatku i są wymagane do przekazywania ocen oraz wyświetlania zadań uczniów nauczycielom w narzędziu do oceniania.
• Jeśli dodatek zna już attachmentId, wyświetl odpowiedni interfejs załącznika.
• W przeciwnym razie ten załącznik musiał zostać skopiowany z innego elementu strumienia lub kursu. Zalecenia dotyczące tego scenariusza znajdziesz w przewodniku Obsługa skopiowanych treści

Szczegóły zadania przesłanego przez ucznia

Typowy proces przesyłania wygląda tak:

1. Uczeń uruchamia studentViewUri, aby wykonać zadanie.
2. Dodatek pobiera submissionId z metody getAddOnContext za pomocą danych logowania ucznia.
3. Deweloper dodatku zapisuje submissionId i attachmentId jako unikalny identyfikator pracy ucznia. Jeśli nauczyciel skopiuje projekt w Classroom, możesz użyć klucza złożonego z tych 2 parametrów, aby wyświetlić nowy załącznik w skopiowanym projekcie. Więcej informacji znajdziesz na stronie Skopiowane treści.
4. Nauczyciel, który chce sprawdzić pracę ucznia, uruchamia studentWorkReviewUri. Żądanie zawiera te parametry zapytania: courseId, itemId, itemType, attachmentId i submissionId.
5. Deweloper dodatku używa tych 4 identyfikatorów, aby pobrać zadania ucznia. Aby pobrać lub zmodyfikować informacje o zadaniu przesłanym przez ucznia, użyj punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions.

Wykrywanie stanu zadania

Wyślij żądanie GET do punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions, aby uzyskać szczegółowe informacje o konkretnym submissionId. Otrzymasz obiekt AddOnAttachmentStudentSubmission, który zawiera ocenę zadania (pointsEarned) i jego bieżący stan (postSubmissionState). Stan zadania może mieć jedną z tych wartości:

• NEW, jeśli uczeń nigdy nie otworzył zadania.
• CREATED, jeśli uczeń utworzył zadanie, ale jeszcze go nie przesłał.
• TURNED_IN, jeśli uczeń przesłał pracę nauczycielowi.
• RETURNED, jeśli nauczyciel zwrócił zadanie uczniowi.
• RECLAIMED_BY_STUDENT, jeśli uczeń „wycofał” swoją pracę.

Użyj tego punktu końcowego, aby wykryć stan pracy ucznia w dodatku. Następnie możesz dostosować widoki lub opcje udostępniane uczniowi w zależności od zwróconego stanu. Może to obejmować takie funkcje jak:

• Wyświetlanie stanu oddania projektów w dodatku. Może to pomóc uczniom uniknąć potencjalnych nieporozumień i upewnić się, że nie zapomną oddać projektu.
• Ograniczanie uprawnień do edytowania zadania. Jeśli projekt ma stan CREATED lub RECLAIMED_BY_STUDENT, uczeń może mieć możliwość edytowania swojego zadania. Jeśli projekt ma stan TURNED_IN lub RETURNED, uczeń może nie mieć możliwości edytowania swojego zadania.

Oceny i wiele załączników

Do ustawienia oceny za pojedynczy projekt można użyć tylko 1 załącznika dodatku. Jeśli nauczyciel utworzy więcej niż 1 załącznik typu aktywność, który zawiera wartość maxPoints, tylko pierwszy taki załącznik może ustawić ocenę projektu. Aby wyłączyć przekazywanie ocen za załącznik, pozostaw wartość maxPoints nieustawioną lub ustaw ją na zero.

Ustawianie oceny zadania

Możesz zmodyfikować zadanie przesłane przez ucznia, wysyłając żądanie PATCH do punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions. Treść żądania musi zawierać instancję AddOnAttachmentStudentSubmission ze zmodyfikowanymi wartościami. Aby zmodyfikować ocenę zadania, ustaw pole pointsEarned. Wartość przekazana w pointsEarned staje się oceną roboczą widoczną dla nauczyciela w interfejsie Classroom. Nauczyciele mogą modyfikować ocenę roboczą przed zwróceniem projektu uczniom. Szczegółowe informacje o tym, jak oceny są wyświetlane nauczycielom, znajdziesz w artykule Omówienie oceniania w interfejsie Classroom.

Pamiętaj, że ocenę możesz ustawić za pomocą pointsEarned tylko wtedy, gdy spełnione są te warunki:

• Załącznik musi mieć dodatnią wartość maxPoints.
• Dodatek musi być pierwotnym twórcą załącznika.

Pamiętaj też, że możesz zmodyfikować wartość maxPoints już utworzonego AddOnAttachment, wysyłając żądanie PATCH do punktu końcowego addOnAttachments.

Kiedy ustawić ocenę

Możesz wybrać, kiedy ocena ma zostać przekazana do Google Classroom. Kluczowa różnica polega na tym, czy chcesz przechowywać dane logowania nauczyciela, ponieważ tylko nauczyciel może modyfikować ocenę.

Istnieją 2 momenty w dodatku , w których możesz przekazać ocenę do Google Classroom: gdy uczeń ukończy pracę lub gdy nauczyciel otworzy pracę ucznia w ramce iframe sprawdzania pracy ucznia.

Jeśli chcesz ustawiać oceny, gdy uczeń ukończy pracę, musisz przechowywać dane logowania nauczyciela w trybie offline, a następnie pobrać je i użyć do zmodyfikowania oceny, gdy uczeń ukończy pracę. Ta metoda ma kilka potencjalnych korzyści:

• Umożliwia bezproblemowe aktualizowanie ocen. Nauczyciele nie muszą podejmować żadnych specjalnych działań, aby oceny były widoczne w interfejsie Classroom.
• Umożliwia uzyskiwanie w czasie rzeczywistym informacji o postępach klasy w projekcie. Ustawiając oceny, gdy uczniowie kończą załączniki, nauczyciele mogą sprawdzić, czy uczniowie rozumieją materiał, bez konieczności otwierania każdego zadania.

Pamiętaj, że to podejście umożliwia też asynchroniczną synchronizację ocen. Możesz okresowo wysyłać zapytania do punktu końcowego AddOnAttachmentStudentSubmission, aby wykryć, kiedy uczeń przesłał pracę. Gdy praca zostanie przesłana, ustaw ocenę zadania za pomocą zapisanych danych logowania.

Jeśli nie chcesz wczytywać danych logowania nauczyciela podczas sesji ucznia, możesz użyć danych logowania aktywnego nauczyciela, gdy wczytuje on zadanie ucznia w ramce iframe sprawdzania pracy ucznia. Może to jednak nie zapewnić szczególnie płynnego działania, ponieważ oceny w interfejsie Classroom nie są aktualizowane w czasie rzeczywistym, a nauczyciele musieliby otwierać ramkę iframe sprawdzania pracy ucznia w każdym zadaniu.

Wykrywanie zmian w ocenach projektów

Nauczyciele mogą edytować ustawienia oceniania w Classroom po utworzeniu projektu. Takie zmiany mogą obejmować:

• Zmiana przypisanej wartości punktowej.
• Zmiana wartości maxPoints projektu.
• Zmiana ustawienia, czy projekt ma być oceniany.

Aby sprawdzić bieżące ustawienia oceniania projektu, zalecamy wysłanie żądania GET do punktu końcowego courses.courseWork. Odpowiedź zawiera bieżącą wartość maxPoints. Projekt nieoceniany ma wartość maxPoints równą null lub zero.

Jeśli ocena została przekazana do Classroom, użyj punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions, aby pobrać lub zmienić ocenę załącznika dodatku. Wartość oceny jest ustawiana za pomocą pola pointsEarned. Jeśli Twój produkt umożliwia nauczycielom edytowanie wyniku ucznia w przypadku konkretnej aktywności, rozważ sprawdzenie i w razie potrzeby zaktualizowanie tej wartości.