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.

Dica: talvez você note métodos update() ao lado de métodos patch(). Embora ambos modifiquem um recurso, eles têm comportamentos diferentes. Update() substitui completamente um recurso por um novo, enquanto patch() atualiza apenas campos selecionados. Por exemplo, courses.update() substitui um Course inteiro, enquanto courses.patch() usa o fieldMask mencionado acima para modificar apenas campos específicos no Course. Para simplificar, a API Google Sala de Aula usa quase exclusivamente patch(), e é recomendável que você use esse método em geral.

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.