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 estejam familiarizados com o design orientado a recursos ou 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
Como 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() para o
recurso correspondente.
As chamadas Create() sempre exigem os detalhes iniciais e essenciais do
recurso correspondente como entrada. Por exemplo, para criar um Course, chame o método create() no recurso Course e especifique o name e o description na solicitação, além de informações opcionais, como room.
Para sub-recursos (à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 Course id é necessário para estabelecer a que Course o
CourseWork pertence.
Os métodos Create() retornam uma instância do recurso recém-criado na resposta da chamada de API. O recurso retornado normalmente tem outros campos
gerados pelo servidor, como o recurso id ou creationTime.
Patch
Para modificar recursos existentes, chame o método patch() (que às vezes é
chamado 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
updateMask, para determinar quais campos no 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
da chamada da API, com todas as alterações concluídas.
Obter 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. Geralmente, a
operação list() recebe todos os sub-recursos de algum recurso pai, por
exemplo, a recuperação de todos os CourseWork em um Course. Isso é útil para
minimizar solicitações, em comparação a fazer várias chamadas get() e particularmente
valioso quando você não sabe o id dos recursos que 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() é compatível com a paginação. Cada "página" de resultados retornada fornece um pageToken, que pode ser incluído em uma chamada list() subsequente 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 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, há métodos personalizados
disponíveis, como o método modifyAssignees. O comportamento desses métodos
é personalizado, e você precisa consultar a documentação deles individualmente.