Na tej stronie znajdziesz ogólny opis sposobu działania żądań w interfejsie Google Classroom API. Celem jest pomoc czytelnikom, którzy nie znają jeszcze projektowania zorientowanego na zasoby lub interfejsów API Google Workspace.
Przykłady kodu znajdziesz w odpowiednich przewodnikach dotyczących interfejsów API, np. Tworzenie i zarządzanie kursami lub Tworzenie i zarządzanie zajęciami.
Projektowanie zorientowane na zasoby
Jak wspomniano w strukturze interfejsu API, interfejs Classroom API jest zgodny z wzorcami architektury zorientowanej na zasoby. Większość zasobów ma metody standardowych operacji, takich jak tworzenie, odczytywanie, aktualizowanie i usuwanie instancji zasobu.
Za pomocą interfejsu API można na przykład create(), patch(), get(), list() i delete() tworzyć zajęcia w Google Classroom Course.
Utwórz
Aby utworzyć nowy zasób, np. Course, wywołaj metodę create() odpowiedniego zasobu.
Create() wymagają zawsze podania jako danych wejściowych początkowych, kluczowych informacji o odpowiadającym zasobie. Aby na przykład utworzyć Course, wywołaj metodę create() zasobu Course i określ w prośbie parametry name i description, a także opcjonalne informacje, takie jak room.
W przypadku zasobów podrzędnych (czasem nazywanych podrzędnymi) wymagane są też identyfikatory zasobu nadrzędnego. Na przykład podczas tworzenia CourseWork w Course musisz podać Course id, aby określić, do której Course należy CourseWork.
Metody Create() zwracają w odpowiedzi na wywołanie interfejsu API instancję nowo utworzonego zasobu. Zwracany zasób zwykle zawiera dodatkowe pola generowane przez serwer, takie jak zasób id lub creationTime.
Poprawka
Aby zmodyfikować istniejące zasoby, wywołaj metodę patch() (czasami nazywaną update()) na odpowiednim zasobie. Metoda patch() jest prawie identyczna z metodą create(), z 2 głównymi różnicami: podczas wywoływania metody patch() musisz określić:
idzasobu, który chcesz zmodyfikować.- lista pól (nazywana
updateMask), która określa, które pola zasobu mają zostać zaktualizowane; Jest to opcjonalne, jeśli istnieje domyślny zestaw pól lub pola są wnioskowane.
Patch() zwracają w odpowiedzi na wywołanie interfejsu API pełny egzemplarz zaktualizowanego zasobu wraz ze wszystkimi wprowadzonymi zmianami.
Pobieranie i wyświetlanie listy
Istnieją 2 metody pobierania zasobów: get() i list().
Metoda get() pobiera określony zasób za pomocą identyfikatora. Na przykład pobieranie Course na podstawie id lub alias. Wywołanie get() zwraca bezpośrednio pełny zasób.
Metoda list() pobiera wiele zasobów tego samego typu w jednym żądaniu bez konieczności podawania identyfikatorów poszczególnych zasobów. Operacja list() często pobiera wszystkie podzasoby zasobu nadrzędnego, na przykład pobiera wszystkie CourseWork w zasobach Course. Jest to przydatne w przypadku minimalizowania liczby żądań w porównaniu z wykonywaniem wielu wywołań funkcji get(). Jest to szczególnie przydatne, gdy nie znasz id zasobów, których potrzebujesz.
Zazwyczaj metody list() mają maksymalną liczbę zasobów, które mogą zostać zwrócone w pojedynczym wywołaniu. Można skonfigurować niższe limity, podając wartość parametru pageSize w wywołaniu. W przypadku większej liczby zasobów niż limit metoda list() obsługuje podział na strony. Każda zwracana „strona” wyników zawiera pageToken, który można uwzględnić w kolejnych wywołaniach metody list(), aby pobrać kolejną partię zasobów.
Usuń
Metoda delete() przyjmuje identyfikator zasobu, np. id, i usuwa odpowiadający mu zasób. Jeśli operacja delete() się powiedzie, zwrócona zostanie pusta odpowiedź.
Inne operacje
Nie wszystkie operacje możliwe w interfejsie Classroom API mogą być wykonywane za pomocą wspomnianych standardowych operacji, na przykład modyfikowania przypisanych do zasobu CourseWork. W takich przypadkach dostępne są metody niestandardowe, np. metoda modifyAssignees. Sposób działania tych metod jest dostosowywany, dlatego należy zapoznać się z poszczególnymi dokumentacjami.