На этой странице представлен общий обзор того, как работают запросы в API Google Classroom. Цель — помочь читателям, которые еще не знакомы с ресурсно-ориентированным дизайном или API Google Workspace.
Конкретные примеры кода см. в соответствующих руководствах по API, например «Создание курсов и управление ими» или «Создание курсовых работ и управление ими» .
Ресурсно-ориентированный дизайн
Как упоминалось в структуре API , Classroom API соответствует шаблонам ресурсо-ориентированного проектирования . Большинство ресурсов имеют методы для стандартных операций, таких как создание, чтение, обновление и удаление экземпляров ресурса.
Например, с помощью API можно create() , patch() , get() , list() и delete() классный Course .
Создавать
Чтобы создать новый ресурс, например Course , вызовите метод create() для соответствующего ресурса.
Вызовы Create() всегда требуют исходных, важных сведений о соответствующем ресурсе в качестве входных данных. Например, чтобы создать Course , вызовите метод create() ресурса Course и укажите в запросе name и description , а также дополнительную информацию, такую как room .
Для подресурсов (иногда называемых дочерними ресурсами) также требуются идентификаторы родительского ресурса. Например, при создании CourseWork внутри Course id Course необходим для определения того, к какому Course принадлежит CourseWork .
Методы Create() возвращают экземпляр вновь созданного ресурса в ответе на вызов API. Возвращенный ресурс обычно содержит дополнительные поля, сгенерированные сервером, такие как id ресурса или creationTime .
Пластырь
Чтобы изменить существующие ресурсы, вызовите метод patch() (который иногда называют update() ) для соответствующего ресурса. Метод patch() почти идентичен методу create() , с двумя ключевыми отличиями; при вызове метода patch() необходимо указать:
-
idресурса, который необходимо изменить. - Список полей, называемый
updateMask, для определения того, какие поля ресурса необходимо обновить. Это необязательно в случаях, когда существует набор полей по умолчанию или поля являются выведенными.
Методы Patch() возвращают полный экземпляр обновленного ресурса в ответе на вызов API со всеми выполненными изменениями.
Получите и перечислите
Существует два метода получения ресурсов: get() и list() .
Метод get() извлекает определенный ресурс по некоторому идентификатору. Например, получение Course по id или alias . Вызов get() напрямую возвращает весь ресурс.
Метод list() извлекает несколько ресурсов одного типа в одном запросе без необходимости использования отдельных идентификаторов ресурсов. Часто операция list() получает все подресурсы некоторого родительского ресурса, например, извлекая все CourseWork внутри Course . Это полезно для минимизации количества запросов по сравнению с выполнением нескольких вызовов get() и особенно ценно, когда вы не знаете id нужных ресурсов.
Как правило, методы list() имеют некоторый максимальный объем ресурсов, который может быть возвращен за один вызов, а более низкие пределы можно настроить, включив в вызов значение pageSize . В случаях, когда ресурсов больше лимита, метод list() поддерживает нумерацию страниц ; каждая возвращаемая «страница» результатов предоставляет pageToken , который можно включить в последующий вызов list() для получения следующего пакета ресурсов.
Удалить
Метод delete() принимает идентификатор ресурса, например id , и удаляет соответствующий ресурс. Если метод delete() выполнен успешно, возвращается пустой ответ.
Прочие операции
Не все операции, возможные с API Classroom, могут быть выполнены с помощью вышеупомянутых стандартных операций, например, изменение правопреемников ресурса CourseWork . В этих случаях доступны пользовательские методы, например modifyAssignees . Поведение этих методов индивидуально, и вам следует обратиться к документации по ним индивидуально.