Diretrizes da API LMS para integração do suplemento do bloco de anotações de classe do OneNote
Aplica-se aos: Blocos de anotações empresariais no Office 365
Este documento fornece as chamadas de API necessárias para o OneNote enumerar classes e atribuições, definir atribuições, baixar notas e atualizar notas em qualquer LMS.
Todas as solicitações devem ser autenticadas. Todas as solicitações devem ser feitas sobre HTTPS.
Observação
É recomendável que cada LMS implemente o fluxo de concessão do código de autorização para a implementação do oauth2. Isso impede que o usuário a inconveniência de inserir as credenciais cada vez que um token de acesso expira.
Recuperar uma lista de classes
Fazer uma solicitação GET para <Specify URL for retrieving list of classes>.
O LMS deve retornar uma matriz JSON de classes para o usuário autenticado no momento.
Cada classe deve ter as seguintes propriedades:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para a turma, exclusivo na instalação do LMS |
| nome | sequência de caracteres | sequência de caracteres |
Recuperar uma lista de alunos em uma classe
Fazer uma solicitação GET para <Specify URL for retrieving list of students in a class>.
O LMS deve retornar uma matriz JSON de alunos na classe.
Cada aluno deve ter as seguintes propriedades:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para o aluno, exclusivo na instalação do LMS |
| nome | sequência de caracteres | Nome legível do aluno |
| sequência de caracteres | sequência de caracteres | Endereço de e-mail do aluno |
Recuperar uma lista de atribuições para uma classe
Fazer uma solicitação GET para <Specify URL for retrieving list of assignments for a class>.
O LMS deve retornar uma matriz JSON de tarefas para a turma.
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para a tarefa, exclusivo na instalação do LMS |
| título | sequência de caracteres | Título da atribuição |
| descrição | sequência de caracteres | Descrição de atribuição |
| gradetypeid | sequência de caracteres | Identificador para o tipo de nota, exclusivo na instalação do LMS |
| dueDate | data em cadeia de caracteres (formato: 2016-12-25T00:00:00) | Data de conclusão da atribuição. O LMS não irá armazenar, nem utilizar a parte da hora. |
| url | sequência de caracteres | URL da tarefa. Disponível apenas nas versões suportadas do LMS. |
| Nome da propriedade opcional | Tipo | Descrição |
|---|---|---|
| gradetypeid | sequência de caracteres | Identificador para o tipo de nota, exclusivo na instalação do LMS |
| mín | inteiro | Pontuação mínima que pode ser atribuída a um aluno |
| máx | inteiro | Pontuação máxima que pode ser atribuída a um aluno |
| validgradevalues | lista | Valores válidos para notas para esta atribuição |
Definir uma atribuição a uma classe
Fazer uma solicitação POST para <Specify URL for setting an assignment to a class>.
As seguintes variáveis de formulário POST são necessárias:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| título | cadeia de caracteres (comprimento máximo: 280) | Título da atribuição |
| dueDate | data em cadeia de caracteres (formato: 2016-12-25T00:00:00) | Data de vencimento da atribuição |
| descrição | sequência de caracteres | Descrição de atribuição |
| Nome da propriedade opcional | Tipo | Descrição |
|---|---|---|
| gradetypeid | sequência de caracteres | Identificador para o tipo de nota, exclusivo na instalação do LMS |
| mín | inteiro | Pontuação mínima que pode ser atribuída a um aluno |
| máx | inteiro | Pontuação máxima que pode ser atribuída a um aluno |
| validgradevalues | lista | Valores válidos para notas para esta atribuição |
O LMS retornará um objeto JSON com uma propriedade de identificador único. O valor dessa propriedade será o identificador da atribuição recém-definida.
Recuperar uma lista de notas de uma atribuição
Fazer uma solicitação GET para <Specify URL for retrieving grades for a given assignment>.
O LMS deve retornar uma matriz JSON de alunos que receberam a atribuição e suas notas/pontuação.
Cada segmento JSON do aluno deve ter as seguintes propriedades:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para o aluno, exclusivo na instalação do LMS |
| sequência de caracteres | Endereço de e-mail do aluno | |
| avaliado | booliano | Indica se um ponto foi fornecido pelo professor |
| obtainedMark | inteiro | Ponto opcional obtido pelo aluno (por exemplo, 85) |
| maxMark | inteiro | Maior ponto possível opcional (por exemplo, 100) |
| comentários | sequência de caracteres | Comentários opcionais dados ao aluno (por exemplo, "Ótimo trabalho") |
| sequência de caracteres | sequência de caracteres | Nota opcional dada ao aluno (por exemplo, "A") |
Observe que o LMS pode oferecer suporte à classificação de números diferentes de 100. Nesse caso (maxMark não é igual a 100), o OneNote pode precisar converter o valor de obtainedMark se ele não puder ser exibido na interface do usuário do OneNote.
Definir uma nota para um aluno
Fazer uma solicitação POST para <Specify URL for setting grade for a given student>.
As seguintes variáveis de formulário POST podem ser incluídas:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para o aluno, um guid |
| fonte | sequência de caracteres | Sempre defina o valor para "onenote" |
| obtainedMark | inteiro | Ponto alcançado pelo aluno |
| maxMark | inteiro | Maior ponto possível |
| obtainedGrade | sequência de caracteres | Nota ou nível alcançado pelo aluno (por exemplo, "A") |
| comentários | sequência de caracteres | Comentários de texto livre para o aluno |
Obter os tipos de notas
Fazer uma solicitação GET para <Specify URL for getting grade types>.
O LMS deve retornar uma matriz JSON de tipos de notas. Cada tipo de nota deve ter as seguintes propriedades:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para o tipo de nota, exclusivo na instalação do LMS |
| gradeTypeCategory | GradeTypeCategory | Categoria para o tipo de nota, exclusivo na instalação do LMS |
| máx | inteiro | Pontuação máxima possível |
| descrição | sequência de caracteres | Exibe a sequência de caracteres para o tipo de nota |
Obtenha o tipo de notas específicas
Fazer uma solicitação GET para <Specify URL for getting grade type by id>.
O LMS deve retornar um JSON com um tipo de nota único, que possui as seguintes propriedades:
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
| id | sequência de caracteres | Identificador para o tipo de nota, exclusivo na instalação do LMS |
| gradeTypeCategory | GradeTypeCategory | Categoria para o tipo de nota, exclusivo na instalação do LMS |
| máx | inteiro | Pontuação máxima possível |
| descrição | sequência de caracteres | Exibe a sequência de caracteres para o tipo de nota |
APIs para criar/excluir classes e excluir atribuições
Estas APIs são opcionais, mas altamente recomendadas para testes de integração. A equipe Microsoft do bloco de anotações de classe usa esses pontos de extremidade para fins de limpeza.
enum GradeTypeCategory
{
/// <summary>
/// no grade type category.
/// </summary>
None,
/// <summary>
/// Numeric grade type category.
/// </summary>
Numeric,
/// <summary>
/// Percent grade type category.
/// </summary>
Percentage,
/// <summary>
/// Letter grade type category.
/// </summary>
Letters,
}
Pré-requisitos de ambiente de teste
Seu ambiente de teste é composto de dois sistemas:
Locatário de teste do Office 365
Pode ser utilizado qualquer locatário do Office 365 ao qual você tenha acesso e existem várias contas de professor e aluno com licenças válidas do Office.
Demonstração de locatário do Office 365 está disponível para parceiros. Quando você configura esta demonstração de locatário, você pode escolher uma instância K–12 EDU personalizada e pré-populada com professores e alunos e SKUs educacionais.
Contas e ambientes de teste do LMS
Você precisará fornecer as seguintes informações para a equipe do Bloco de Anotações de Classe:
- URL base do seu LMS/SIS que hospeda os pontos de extremidade da API.
- ID do aplicativo (se não houver suporte oauth2): um ID de aplicativo exclusivo atribuído para o suplemento do bloco de anotações de classe que permite que você ser detectado como um aplicativo válido.
- Chave do aplicativo (se não houver suporte oauth2): O segredo do aplicativo para o ID de determinado aplicativo.
Pré-requisitos de informações de marketing
Imagem de logotipo. Não precisa ter alta resolução. Nossos logotipos atuais são na verdade menor do que 100K de tamanho e até 300x300 pixels no máximo.
Descrição. A descrição deve ser curta, com uma mensagem de aproximadamente 75 palavras (melhor em torno de 50) sobre sua oferta.
Link para o seu site. Para que seja possível aprender mais sobre sua oferta.
Logotipo do botão. Deve ser um logotipo de 64x64 pixels.
Confira também
- Blocos de anotações de classe do OneNote (visão geral e recursos)
- Trabalhar com blocos de anotações de equipe
- Desenvolvimento do OneNote
- Obter a estrutura e o conteúdo do OneNote
- Centro de Desenvolvimento do OneNote
- Blog de desenvolvedor do OneNote
- Perguntas sobre desenvolvimento do OneNote no Stack Overflow
- Repositórios do OneNote no GitHub