Na tej stronie znajdziesz ogólne informacje o tym, jak działają żądania w Google Classroom API. Chcemy pomóc czytelnikom, którzy nie znają jeszcze projektowania zorientowanego na zasoby ani interfejsów API Google Workspace.
Przykłady kodu znajdziesz w odpowiednich przewodnikach po interfejsie API, np. Tworzenie kursów i zarządzanie nimi lub Tworzenie prac domowych i zarządzanie nimi.
Projektowanie zorientowane na zasoby
Jak wspomnieliśmy w sekcji Zasoby interfejsu API, interfejs API Classroom 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() Course w Classroom.
Utwórz
Aby utworzyć nowy zasób, np. Course, wywołaj metodę create() dla odpowiedniego zasobu.
Wywołania Create() zawsze wymagają początkowych, kluczowych szczegółów odpowiedniego zasobu jako danych wejściowych. Aby na przykład utworzyć Course, wywołaj metodę create() w zasobie Course i w żądaniu podaj name i description oraz opcjonalne informacje, takie jak room.
W przypadku zasobów podrzędnych (czasami nazywanych zasobami zależnymi) wymagane są też identyfikatory zasobu nadrzędnego. Na przykład podczas tworzenia elementu CourseWork w ramach elementu Course potrzebny jest element Course id, aby określić, do którego elementu Course należy element CourseWork.
Metody Create() zwracają w odpowiedzi na wywołanie interfejsu API instancję nowo utworzonego zasobu. Zwrócony zasób zwykle zawiera dodatkowe pola wygenerowane przez serwer, takie jak id lub creationTime.
Poprawka
Aby zmodyfikować istniejące zasoby, wywołaj metodę patch() (czasami nazywaną update()) w odpowiednim zasobie. Metoda patch() jest niemal identyczna z metodą create(), ale występują między nimi 2 kluczowe różnice. Podczas wywoływania metody patch() musisz określić:
idzasobu do zmodyfikowania.- Lista pól, zwana
updateMask, która określa, które pola w zasobie mają zostać zaktualizowane. Jest to opcjonalne w przypadku domyślnego zestawu pól lub gdy pola są wywnioskowane.
Metody Patch() zwracają pełną instancję zaktualizowanego zasobu w odpowiedzi na wywołanie interfejsu API ze wszystkimi wprowadzonymi zmianami.
Pobierz i wyświetl
Zasoby można pobierać na 2 sposoby: get() i list().
Metoda get() pobiera konkretny zasób na podstawie 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. Często operacja list() pobiera wszystkie zasoby podrzędne danego zasobu nadrzędnego, np. wszystkie CourseWork w ramach Course. Jest to przydatne do minimalizowania liczby żądań w porównaniu z wykonywaniem wielu wywołań get(), a szczególnie cenne, gdy nie znasz id zasobów, których potrzebujesz.
Zazwyczaj metody list() mają maksymalną liczbę zasobów, które można zwrócić w jednym wywołaniu, a niższe limity można skonfigurować, uwzględniając w wywołaniu wartość pageSize. W przypadku, gdy zasobów jest więcej niż limit, metoda list() obsługuje podział na strony. Każda „strona” wyników, która jest zwracana, zawiera pageToken, który można uwzględnić w kolejnym wywołaniu list(), aby pobrać następną partię zasobów.
Usuń
Metoda delete() akceptuje identyfikator zasobu, np. id, i usuwa odpowiedni zasób. Jeśli operacja delete() się uda, zwracana jest pusta odpowiedź.
Inne operacje
Nie wszystkie operacje możliwe w interfejsie Classroom API można wykonać za pomocą wspomnianych standardowych operacji. Przykładem jest modyfikowanie osób przypisanych do zasobu CourseWork. W takich przypadkach dostępne są metody niestandardowe, np. metoda modifyAssignees. Działanie tych metod jest dostosowane do konkretnych potrzeb, dlatego należy zapoznać się z ich dokumentacją.