Compartilhar via


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"
}

Confira também