Esta página descreve uma visão geral de alto nível de como as solicitações funcionam na API Google Classroom. O objetivo é ajudar leitores que ainda não estão familiarizados com o design orientado a recursos ou com as APIs do Google Workspace.
Para exemplos de código específicos, consulte os guias de API correspondentes, por exemplo, Criar & gerenciar cursos ou Criar & gerenciar cursos.
Design voltado a recursos
Conforme mencionado na Estrutura da API, a API Classroom segue padrões de design orientado a recursos. A maioria dos recursos tem métodos para operações padrão, como criar, ler, atualizar e excluir instâncias do recurso.
Por exemplo, é possível create(), patch(), get(), list()
e delete() uma sala de aula Course usando a API.
Criar
Para criar um novo recurso, como um Course, chame o método create() do
recurso correspondente.
As chamadas Create() sempre exigem os detalhes iniciais e críticos do
recurso correspondente como entrada. Por exemplo, para criar um Course, chame o
método create() no recurso Course e especifique o name e
description na solicitação, junto com informações opcionais, como o room.
Para subrecursos (às vezes chamados de recursos filhos), os identificadores do recurso
pai também são necessários. Por exemplo, ao criar um CourseWork em um
Course, o id Course é necessário para estabelecer a qual Course o
CourseWork pertence.
Os métodos Create() retornam uma instância do recurso recém-criado na resposta
de chamada da API. O recurso retornado geralmente tem campos adicionais
gerados pelo servidor, como o recurso id ou creationTime.
Patch
Para modificar recursos existentes, chame o método patch(), que às vezes é chamado de update(), no recurso correspondente. O método patch() é quase
idêntico ao create(), com duas diferenças principais. Ao chamar o método patch(),
é necessário especificar:
- O
iddo recurso a ser modificado. - Uma lista de campos, chamada de
updateMask, para determinar quais campos do recurso serão atualizados. Isso é opcional nos casos em que há um conjunto padrão de campos ou os campos são inferidos.
Os métodos Patch() retornam a instância completa do recurso atualizado na resposta de chamada
da API, com todas as alterações concluídas.
Receber e listar
Há dois métodos para recuperar recursos: get() e list().
O método get() recupera um recurso específico por algum identificador. Por
exemplo, buscar um Course com base em id ou alias. A chamada get()
retorna o recurso completo diretamente.
O método list() recupera vários recursos do mesmo tipo em uma única
solicitação, sem a necessidade de identificadores de recursos individuais. Muitas vezes, a
operação list() recebe todos os subrecursos de algum recurso pai, por
exemplo, recuperando todos os CourseWork em um Course. Isso é útil para
minimizar solicitações, em comparação com a realização de várias chamadas get(), e é particularmente
valioso quando você não sabe o id dos recursos que você quer.
Em geral, os métodos list() têm uma quantidade máxima de recursos que podem ser
retornados em uma única chamada, e limites mais baixos podem ser configurados incluindo um
valor pageSize com a chamada. Nos casos em que há mais recursos do que o
limite, o método list() aceita paginação. Cada "página" de resultados
retornados fornece um pageToken, que pode ser incluído em uma chamada list()
posterior para buscar o próximo lote de recursos.
Excluir
O método delete() aceita um identificador de recurso, como id, e exclui o
recurso correspondente. Se o delete() for bem-sucedido, uma resposta vazia será
retornada.
Outras operações
Nem todas as operações possíveis com a API Classroom podem ser realizadas
com as operações padrão mencionadas, por exemplo, modificar os
designados de um recurso CourseWork. Nesses casos, métodos personalizados estão
disponíveis, como o método modifyAssignees. O comportamento desses métodos
é personalizado, e você precisa consultar a documentação deles individualmente.