Como as solicitações funcionam

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 as APIs do Google Workspace.

Para exemplos de código específicos, consulte os guias de API correspondentes, como Criar & gerenciar cursos ou Criar e gerenciar atividades.

Design voltado a recursos

Conforme mencionado em Recursos 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() um Course do Google Sala de Aula usando a API.

Criar

Para criar um 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 name e description na solicitação, além de informações opcionais como room.

Para sub-recursos (às vezes chamados de recursos filhos), também são necessários identificadores do recurso pai. Por exemplo, ao criar um CourseWork em um Course, o Course id é 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 da chamada da API. O recurso retornado geralmente tem campos adicionais gerados pelo servidor, como id ou creationTime.

Patch

Para modificar recursos atuais, chame o método patch() (à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:

1. O id do recurso a ser modificado.
2. Uma lista de campos, chamada de updateMask, para determinar quais campos do recurso serão atualizados. Isso é opcional quando há um conjunto padrão de campos ou quando eles são inferidos.

Os métodos Patch() retornam a instância completa do recurso atualizado na resposta da chamada de API, com todas as mudanças 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 dos identificadores de recursos individuais. Muitas vezes, a operação list() recebe todos os sub-recursos de algum recurso pai, por exemplo, recuperando todos os CourseWork em um Course. Isso é útil para minimizar solicitações em comparação com várias chamadas get() e é particularmente valioso quando você não conhece o id dos recursos desejados.

Em geral, os métodos list() têm uma quantidade máxima de recursos que podem ser retornados em uma única chamada, e limites menores 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() oferece suporte à 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 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 acima. Por exemplo, modificar os atribuídos de um recurso CourseWork. Nesses casos, métodos personalizados estão disponíveis, como o modifyAssignees. O comportamento desses métodos é personalizado, e você precisa consultar a documentação de cada um deles.