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 pracę z przesłanymi przez uczniów pracami. 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ńcowegocourses.*.addOnAttachments.create. Żądanie musi zawierać w treści wystąpienie elementu AddOnAttachment.

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

• title: nazwa ciągu znaków załącznika.
• teacherViewUri: identyfikator URI widoku załącznika dla nauczyciela.
• studentViewUri: identyfikator URI widoku załącznika dla ucznia.
• studentWorkReviewUri: identyfikator URI, pod którym nauczyciel może zobaczyć pracę ucznia w załączniku. To pole jest wymagane tylko w przypadku załączników typu aktywność.

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

• dueDate i dueTime, jeśli określasz termin przesłania 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 AddOnAttachmentdokumentacji zasobu.

Weryfikowanie danych logowania i roli użytkownika

Element iframe Widok ucznia, element iframe Sprawdzanie prac uczniów i element iframe Widok nauczyciela służą do wyświetlania treści użytkownikowi, a nie do modyfikowania zadania w Classroom. Gdy otworzy się jeden z tych widoków, możesz wykonać te czynności:

• Uzyskaj dane logowania OAuth użytkownika.
• Wyślij żądanie courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext lub announcements.getAddOnContext na podstawie itemType, aby potwierdzić rolę użytkownika.
• Sprawdź odpowiedź, aby zobaczyć, czy zawiera ona TeacherContext lub StudentContext. Można zwrócić tylko jedną wartość, która odpowiada roli użytkownika w kursie.
• Jeśli bieżący użytkownik jest uczniem, a wartość parametru itemType to courseWork, zapisz submissionId z odpowiedzi wraz z pracą ucznia. submissionIdsDopasowanie w ramkach iframe dodatku jest wymagane do przekazywania ocen i wyświetlania prac uczniów nauczycielom w narzędziu do oceniania.
• Jeśli dodatek zna już attachmentId, wyświetl odpowiedni interfejs załącznika.
• W przeciwnym razie załącznik musiał zostać skopiowany z innego elementu strumienia lub kursu. Wskazówki dotyczące tego scenariusza znajdziesz w przewodniku Postępowanie w przypadku skopiowanych treści.

Szczegóły zadania przesłanego przez ucznia

Typowy proces przesyłania obejmuje te etapy:

1. Uczeń uruchamia studentViewUri, aby wykonać działanie.
2. Dodatek pobiera submissionId z metody getAddOnContext za pomocą danych logowania ucznia.
3. Wartości submissionId i attachmentId są przechowywane przez dewelopera dodatku 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 naszej stronie poświęconej skopiowanym treściom.
4. Nauczyciel, który chce sprawdzić prace uczniów, uruchamia studentWorkReviewUri. Żądanie zawiera te parametry zapytania:courseId, itemId, itemType, attachmentId i submissionId.
5. Deweloper dodatku używa tych 4 identyfikatorów do pobierania prac uczniów. Użyj punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions, aby pobrać lub zmodyfikować informacje o przesłanym przez ucznia zadaniu.

Wykrywanie stanu przesłania

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ę przesłanego zadania (pointsEarned) i jego bieżący stan (postSubmissionState). Stan przesłanego zadania może mieć jedną z tych wartości:

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

Użyj tego punktu końcowego, aby wykryć stan zadania ucznia w dodatku. W zależności od zwróconego stanu możesz dostosować widoki lub opcje udostępniane uczniowi. Mogą to być funkcje takie jak:

• Wyświetlanie stanu oddania projektów w dodatku. Może to pomóc uczniom uniknąć potencjalnych nieporozumień i zapewnić, że nie zapomną o oddaniu projektu.
• ograniczyć uprawnienia do edytowania przesłanych informacji. Jeśli projekt ma stan CREATED lub RECLAIMED_BY_STUDENT, uczeń może mieć możliwość edytowania przesłanego projektu. Jeśli projekt ma stan TURNED_IN lub RETURNED, uczeń może nie mieć możliwości edytowania przesłanego zadania.

Oceny i wiele załączników

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

Ustawianie oceny przesłanej pracy

Możesz zmodyfikować przesłane przez ucznia zadanie, wysyłając żądanie PATCH do punktu końcowego courses.courseWork.addOnAttachments.studentSubmissions. Treść żądania musi zawierać instancję elementu AddOnAttachmentStudentSubmission ze zmienionymi wartościami. Ustaw pole pointsEarned, aby zmodyfikować ocenę przesłanego pliku. Wartość przekazana w pointsEarned staje się oceną w wersji roboczej widoczną dla nauczyciela w interfejsie Classroom. Nauczyciele mogą modyfikować ocenę roboczą przed zwróceniem projektu uczniom. Więcej informacji o tym, jak oceny są prezentowane 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ść utworzonego już AddOnAttachment, wysyłając żądanie PATCH do punktu końcowego addOnAttachments.maxPoints

Kiedy ustawić ocenę

Masz pewną swobodę w określaniu, kiedy ocena jest przekazywana z powrotem do Google Classroom. Kluczowe jest to, czy zdecydujesz się przechowywać dane logowania nauczyciela, ponieważ tylko on może modyfikować ocenę.

Istnieją 2 momenty, 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 ustawić oceny po wykonaniu przez ucznia zadania, musisz zapisać dane logowania nauczyciela w trybie offline, a następnie pobrać je i użyć do zmodyfikowania oceny po wykonaniu przez ucznia zadania. Ta metoda ma kilka potencjalnych zalet:

• zapewniać płynne aktualizacje ocen; Nauczyciele nie muszą podejmować żadnych specjalnych działań, aby oceny pojawiły się w interfejsie Classroom.
• Udostępniać w czasie rzeczywistym informacje o postępach klasy w realizacji projektu. Ustawiając oceny w miarę przesyłania załączników przez uczniów, nauczyciele mogą sprawdzić, czy uczniowie rozumieją materiał, bez konieczności otwierania każdego przesłanego projektu.

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ł swoją pracę. Po przesłaniu projektu ustaw ocenę 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 przesłane przez ucznia zadanie w ramce iframe sprawdzania zadań uczniów. Może to jednak nie być zbyt wygodne dla użytkowników, ponieważ oceny w interfejsie Classroom nie są aktualizowane w czasie rzeczywistym, a nauczyciele muszą otwierać ramkę iframe z przeglądem pracy ucznia w przypadku każdego przesłanego zadania.

Wykrywanie zmian w ocenach projektów

nauczyciele mogą edytować ustawienia ocen w Classroom po utworzeniu projektu. Takie zmiany mogą obejmować:

• zmienić przypisaną wartość punktową,
• zmiana wartości maxPoints projektu;
• zmiana tego, czy projekt ma być oceniany;

Aby sprawdzić bieżące ustawienia oceniania zadania, wyślij GET żądanie do punktu końcowego courses.courseWork. Odpowiedź zawiera bieżącą wartość maxPoints. Zadanie bez oceny ma wartość null lub zero maxPoints.

Jeśli ocena została przekazana z powrotem 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. Sprawdź tę wartość i w razie potrzeby ją zaktualizuj, jeśli Twój produkt umożliwia nauczycielom edytowanie wyniku ucznia w przypadku konkretnego działania.