Para acessar e realizar qualquer chamada na API, são necessários o Token de Acesso e um Id de Cliente na URL da requisição.
O Token de Acesso utilizado é vinculado ao seu usuário do ClassApp, e o Id de Cliente à uma aplicação criada.
A URL completa é essa:
Com isso, você já consegue realizar chamadas na API do ClassApp.
A primeira chamada a ser realizada serve para identificar qual o alcance de acesso da sua conta do ClassApp.
Todas as chamadas são realizadas utilizando o método POST, utilizando x-www-form-urlencoded como Application Type.
No campo query do body da requisição, utilize o seguinte conteúdo:
Você consegue retornar todos os elementos que a sua conta tiver acesso utilizando o objeto viewer.
Essa chamada, por exemplo, retorna alguns dos seus dados e as escolas (objeto organizations) que a sua conta de usuário tem acesso.
Note que, sempre que o objeto for multivalorado, é necessário chamar seus elementos pelo objeto nodes. Além disso, é possível obter várias informações sobre esse objeto:
Campo | Dado |
---|---|
nodes | Uma página dos elementos do objeto. Por padrão, retornará no máximo 40 valores. Tipo: Array do Objeto solicitado |
totalCount | O número total de elementos contidos no objeto. Tipo: Número |
pageInfo | Informações de Paginação. Tipo: Objeto Elementos: hasNextPage: Retorna verdadeiro se existe uma próxima página do objeto hasPreviousPage: Retorna verdadeiro se existe uma página anterior do objeto |
Para acessar uma escola específica e consultar a lista de alunos e funcionários, utilizaremos o objeto principal chamado node.
Esse objeto é responsável por retornar um elemento específico do objeto solicitado, dado um id como parâmetro.
Partindo da solicitação do viewer, há uma lista de id de organizações. Escolha uma delas e utilize no parâmetro id do node, como no exemplo a seguir:
Esse retorno nos dá uma lista simples de alunos, funcionários e administradores misturados. Vamos melhorá-la agora.
O objeto entities dentro de organization possui vários parâmetros. Iremos utilizar o parâmetro type para filtrar apenas alunos:
E agora, de funcionários:
Para conseguir fazer uma consulta com tanto funcionários quanto alunos, sem misturá-los, devemos utilizar o conceito de alias.
Um alias renomeia o objeto que estamos chamando para um nome personalizado. Já utilizamos alias nos exemplos anteriores quando pedimos id: dbId.
Esse alias, inclusive, é extremamente importante. O id real de cada elemento precisa ser consultado como dbId. O campo id dos objetos é reservada para o id do GraphQL Relay.
Voltando à nossa prática, podemos realizar duas consultas do objeto entities. Cada um com um alias diferente, para conseguirmos retornar duas listas separadas:
O primeiro passo para ter uma integração entre dois sistemas é garantir que os dados estejam sincronizados entre eles, ou seja, o sistema precisa saber quem são as pessoas dos dois lados.
Para sincronizar os dados do seu sistema com o ClassApp, existem duas maneiras. A primeira delas é salvar no seu banco de dados o id das pessoas do ClassApp. Para fazer isso, basta utilizar a query anterior para salvar os dados dos alunos. A outra opção é salvar o id do seu sistema no ClassApp.
O objeto Entity possui o campo eid. O campo eid é do tipo String, então não é necessário utilizar apenas números. Para realizar a sincronia, vamos introduzir o conceito de mutation. Enquanto uma chamada de query serve para solicitar os dados do sistema, a mutation serve para inserir, atualizar e até deletar dados. Uma mutation sempre utiliza um parâmetro input. Segue um exemplo para inserir um eid em um determinado aluno no ClassApp:
Com a sincronia das IDs, fica mais fácil de atualizar os dados dos alunos no ClassApp. Utilizando a mesma mutation de importEntity, é possível atualizar todos os dados do aluno.
Para atualizar esses dados, vamos utilizar um outro método para realizar as chamadas do GraphQL.
Ao realizar as chamadas na API, deve-se colocar a query/mutation no campo query da requisição. É possível adicionar os dados em um campo separado chamado variables.
Vamos utilizar o exemplo para importar alguns dados do aluno:
A vantagem de utilzar essa maneira, é que é possível utilizar a mesma mutation para atualizar dados de alunos diferentes, apenas trocando o objeto variables.
variables é um JSON que precisa conter, no primeiro nível, todas as variáveis que foram declaradas na query/mutation.
No exemplo, criamos a variável $studentData, que é do tipo ImportEntityInput!. Então criamos uma propriedade dentro do JSON com o mesmo nome da variável (studentData).
O tipo ImportEntityInput! possui os seguintes parâmetros principais:
Campo | Dado |
---|---|
organizationId(Required) | ID da organização que a entidade pertence Tipo: Número |
id | ID da entidade no ClassApp Tipo: Número |
eid | ID externo da entidade Tipo: String |
fullname | Nome Completo da Entidade Tipo: String |
type | Tipo da entidade Tipo: Enum Valores: STUDENT STAFF ADMIN |
addresses | Email/Telefone do aluno e dos responsáveis que receberão convite. Tipo: Array de Address |
groups | Grupos que o aluno fará parte no ClassApp. Geralmente utilizado para turmas. Tipo: Array de Groups Elementos: id: ID do Grupo a ser selecionado - tipo Número name: Nome do Grupo a ser selecionado - tipo String |
disabled | Verdadeiro para desabilitar o aluno, Falso para habilitar Tipo: Boolean |
Um input do Objeto Address tem os seguintes parâmetros principais:
Campo | Dado |
---|---|
address(Required) | O número de telefone ou o endereço de e-mail Tipo: String |
type(Required) | Tipo do endereço Tipo: Enum Valores: EMAIL PHONE |
tags | Qual a tag de usuário esse endereço será associado. Pode ser utilizado o id ou apenas o nome da tag Tipo: Array de Tags Elementos: id: ID da Tag a ser utilizada - tipo Número name: Nome da Tag a ser utilizada - tipo String |
Utilizando essa informação de um jeito mais prático, para importar todas os dados de um aluno, o uso seria o seguinte:
Para envio de mensagens simples, a mutation a ser utilizada é a CreateMessage. A mutation CreateMessage possui, como input um objeto do tipo CreateMessageInput! Os elementos mais importantes para se enviar as mensagens são os seguintes:
Campo | Dado |
---|---|
entityId(Required) | Id da entidade rementente Tipo: Número |
subject | Título/Assunto da Mensagem Tipo: String |
content | Conteúdo da mensagem. (Pode ter conteúdo HTML) Tipo: String |
isHtml | Flag para habilitar html no conteúdo. Se estiver falso, as tags html serão removidas da mensagem. Tipo: Boolean |
recipients(Required) | Ids das entidades que receberão a mensagem. É necessário escolher pelo menos um dos arrays para enviar. Tipo: Objeto de Arrays Elementos: entityIds: Ids do ClassApp das Entidades - Array de Número groupIds: Ids do ClassApp dos Grupos - Array de Número eids: Ids Externos das Entidades - Array de String |
tags | Para qual tipo de usuário a mensagem será enviada. Pode ser utilizado o id ou apenas o nome da tag Tipo: Array de Tags Elementos: id: ID da Tag a ser utilizada - tipo Número name: Nome da Tag a ser utilizada - tipo String |
Veja os exemplos abaixo: