Como trabalhar com blocos de anotações de classe assíncronos
Aplica-se aos: Blocos de anotações corporativos no Office 365
Escolas, faculdades e universidades em todo o mundo usam Blocos de Anotações de Classe do OneNote para ajudar a promover a produtividade, o compromisso e a colaboração. Você pode usar blocos de anotações de classe para cada aula, projeto, semestre e tarefa.
O ponto de extremidade classNotebooks é usado para executar tarefas comuns de blocos de anotações de classe, como criar blocos de anotações de classe, assim como adicionar ou remover alunos por meio de chamadas assíncronas.
Observação
A API do OneNote fornece o ponto de extremidade classNotebooks para operações específicas relacionadas a blocos de anotações de classe.
API assíncrona
Para fazer chamadas assíncronas para o ponto de extremidade classNotebooks, envie uma solicitação com um cabeçalho Prefer: respond-async.
Resposta
| Dados da resposta | Descrição |
|---|---|
| Código de êxito | Um código de status HTTP 202. |
| Cabeçalho Location | A URL para pesquisar o status da operação. A pesquisa do ponto de extremidade da operação retorna um objeto OperationModel, que contém o status da operação e outras informações. |
| Cabeçalho X-CorrelationId | Um GUID que identifica de forma exclusiva a solicitação. Você pode usar esse valor juntamente com o valor Date do cabeçalho ao trabalhar com o suporte da Microsoft para solucionar problemas. |
Modelo de operação
| Modelo de operação | Descrição |
|---|---|
| Id | A identificação da operação. |
| Status | O status pode ser: completed, running, not started, ou failed. - Se for completed, a propriedade resourceLocation contém o ponto de extremidade do recurso para a nova classNotebook. - Se for running, as propriedades createdDateTime e lastActionDateTime mostram quando a solicitação foi criada e quando foi executada pela última vez. - Se for failed, as propriedades error e @api.diagnostics fornecem informações sobre o erro. |
| createdDateTime | Mostra quando a solicitação foi criada. |
| lastActionDateTime | Mostra quando a solicitação foi criada e quando foi executada pela última vez. |
| resourceLocation | O ponto de extremidade para o recurso. |
| resourceId | O ID do recurso. |
Construção da URI da solicitação
Para construir o URI da solicitação, confira Construção do URI da solicitação no tópico Como trabalhar com blocos de anotações de classe.
Criação de blocos de anotações de classe
Para criar um bloco de anotações de classe em uma chamada assíncrona, envie uma solicitação POST para o ponto de extremidade classNotebooks com o cabeçalho Prefer: respond-async.
POST ../classNotebooks
Para o corpo da mensagem e o objeto JSON com os parâmetros de criação do bloco de anotações de classe, confira Criação de blocos de anotação de classe.
Exemplo
A solicitação a seguir cria um bloco de anotações de classe chamado Math 101.
Solicitação
POST https://www.onenote.com/v1.0/me/notes/classNotebooks?sendemail=true
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"name": "Math 101",
"studentSections": [
"Handouts",
"Class Notes",
"Homework",
"Quizzes"
],
"teachers": [
{
"id": "teacher1@contoso.com",
"principalType": "Person"
}
],
"students": [
{
"id": "student1@contoso.com",
"principalType": "Person"
},
{
"id": "student2@contoso.com",
"principalType": "Person"
},
{
"id": "student3@contoso.com",
"principalType": "Person"
},
{
"id": "student4@contoso.com",
"principalType": "Person"
}
],
"hasTeacherOnlySectionGroup": true
}
Resposta
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
Examine o ponto de extremidade Location da operação para obter o status da operação de criação da classe.
Solicitação
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
Resposta
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebook-ee91aafb-5685-4357-9465-77d611ef064c",
"status":"completed",
"createdDateTime":"2018-06-01T23:44:29.349Z",
"lastActionDateTime":"2018-06-01T23:44:29.349Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e",
"resourceId":"1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e"
}
Adição de alunos e professores
Alunos e professores devem ser adicionados para ter acesso ao bloco de anotações de classe. A adição de um aluno também cria um grupo de seções do aluno. Este grupo de seções só é acessível pelo aluno e pelo professor e contém as seções do aluno definidas para o bloco de anotações.
Para adicionar um aluno ou professor a um bloco de anotações de classe em uma chamada assíncrona, envie uma solicitação POST para o ponto de extremidade apropriado com um cabeçalho Prefer: respond-async.
Adicionar um aluno
POST ../classNotebooks/{notebook-id}/students
Adicionar um professor
POST ../classNotebooks/{notebook-id}/teachers
Para o corpo da mensagem e o objeto JSON com os parâmetros de criação do bloco de anotações de classe, confira Adição de alunos ou professores.
Exemplo
A solicitação a seguir adiciona um professor ao bloco de anotações de classe especificado.
Solicitação
POST https://www.onenote/api/v1.0/me/notes/classNotebooks/ 1-b68a21fd-cdb3-41f1-a566-0772872a8a0c//teachers
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"id": "teacher2@contoso.com",
"principalType": "Person"
}
Resposta
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
Examine o ponto de extremidade Location da operação para obter o status da operação de adição do professor.
Solicitação
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
Resposta
{
"@odata.context":"https://www.onenote/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9",
"status":"completed",
"createdDateTime":"2018-06-12T22:23:47.548Z",
"lastActionDateTime":"2018-06-12T22:23:47.548Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
Remoção de alunos ou professores
A remoção de alunos e professores de um bloco de anotações de classe revoga seu acesso ao bloco de anotações, mas não exclui nenhum conteúdo. Para remover um aluno ou professor de um bloco de anotações de classe em uma chamada assíncrona, envie uma solicitação DELETE para o ponto de extremidade apropriado com um cabeçalho Prefer: respond-async.
Remover um aluno
DELETE ../classNotebooks/{notebook-id}/students/{student-id}
Remover um professor
DELETE ../classNotebooks/{notebook-id}/teachers/{teacher-id}
Você pode remover um aluno ou um professor por solicitação.
Exemplo
A solicitação a seguir remove o professor especificado do bloco de anotações de classe especificado.
Solicitação
DELETE https://www.onenote.com/api/v1.0/me /notes/classNotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net
Authorization: Bearer {token}
Accept: application/json
Prefer: respond-async
Resposta
HTTP/1.1 202 Accepted
Location: https://www.onenotecom/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
Examine o ponto de extremidade Location da operação para obter o status da operação de remoção do professor.
Solicitação
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
Resposta
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a",
"status":"completed",
"createdDateTime":"2018-06-12T22:40:06.708Z",
"lastActionDateTime":"2018-06-12T22:40:06.708Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
Transferência do bloco de anotações
Para transferir um bloco de anotações do um professor para outro em uma chamada assíncrona, envie uma solicitação POST para o ponto de extremidade classNotebooks.
POST ../classnotebooks/{notebook-id}/Microsoft.OneNote.Api.classnotebooktransfer
Esta API requer privilégios administrativos do inquilino.
No corpo da mensagem, envie o objeto JSON com os parâmetros de transferência do bloco de anotações de classe.
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationNotebookName": "notebook-name"
}
}
| Parâmetro | Descrição |
|---|---|
| destinationNotebookName | O nome do bloco de anotações no destino. |
| destinationTeacher | Um objeto de segurança. |
| sourceTeacher | Um objeto de segurança. |
Os professores de origem e destino são representados por um objeto de segurança que contém os seguintes parâmetros.
| Parâmetro | Descrição |
|---|---|
| id | O nome UPN do Office 365. Para saber mais sobre usuários e grupos, confira a Documentação da API do Azure AD Graph. |
| principalType | Pessoa |
Exemplo
O exemplo a seguir transfere um bloco de anotações de classe denominado Math 101.
Solicitação
POST https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-9a43afaa-7dc9-4405-b661-b735ebf722a0/Microsoft.OneNote.Api.classnotebooktransfer
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"teacher1@contososd.org"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"teacher2@contososd.org"
},
"destinationNotebookName": "Math 101"
}
}
Resposta
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
Examine o ponto de extremidade Location da operação para obter o status da transferência do bloco de anotações.
Solicitação
GET https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
Resposta
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"transfer9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}
Atualizar associação
Para atualizar a associação de um bloco de anotações de classe em uma chamada assíncrona, enviar uma solicitação POST ao ponto de extremidade classNotebooks com um cabeçalho Prefer: respond-async.
POST
../groups/{groupId}/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
Para o corpo da mensagem e o objeto JSON com os parâmetros da ação de atualização da associação, confira a seção Atualizar associação em Como trabalhar com os blocos de anotações de classe.
Exemplo
O exemplo a seguir sincroniza o bloco de anotações de classe padrão de um grupo unificado.
Solicitação
POST https://www.onenote.com/api/v1.0/myOrganization/groups/1d13f814-83e5-4c11-8294-53bf40defd91/notes/classnotebooks/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
Resposta
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
Examine o ponto de extremidade Location da operação para obter o status da atualização da associação de um bloco de anotações de classe.
Solicitação
GET https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
Resposta
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"updateMembership-9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}