На этой странице представлен общий обзор работы запросов в API Google Classroom. Цель — помочь читателям, которые ещё не знакомы с ресурсно-ориентированным проектированием или API Google Workspace.
Конкретные примеры кода см. в соответствующих руководствах по API, например, Создание и управление курсами или Создание и управление курсовыми работами .
Ресурсно-ориентированный дизайн
Как упоминалось в разделе «Ресурсы API» , API Classroom следует ресурсно-ориентированным шаблонам проектирования . Большинство ресурсов имеют методы для стандартных операций, таких как создание, чтение, обновление и удаление экземпляров ресурса.
Например, с помощью 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() возвращается пустой ответ.
Другие операции
Не все операции, доступные в Classroom API, можно реализовать с помощью вышеупомянутых стандартных операций, например, изменение назначенных ресурсов CourseWork . В таких случаях доступны специальные методы, например, метод modifyAssignees . Поведение этих методов определяется индивидуально, и вам следует ознакомиться с документацией по каждому из них.