Usar a API REST do Planner

É possível usar a API do Planner no Microsoft Graph para criar e atribuir tarefas aos usuários em um grupo no Microsoft 365.

Antes de começar a usar a API do Planner, é útil entender como os objetos principais se relacionam entre si e com os grupos do Microsoft 365.

Planejar contêineres

No Microsoft Planner, os planos estão sempre contidos em outro recurso. O recurso recipiente, plannerPlanContainer, determina as regras de autorização do plano e todas as tarefas nele contidas, além do ciclo de vida do plano. Você pode criar um plano em um contêiner de um dos seguintes tipos: driveItem, grupo do Microsoft 365, plannerTask, projeto do Planner, lista,teamsChannel ou usuário.

O tipo mais comum de contêiner é um grupo.

Tipo de contêiner: grupos Microsoft 365

Os planos geralmente estão contidos em grupos na API do Planner.

Os membros do grupo podem criar, editar, resolver e excluir tarefas no plano. Os membros do grupo também podem alterar algumas propriedades no nível do plano, como o nome do plano ou os nomes dos rótulos. Além disso, quando o grupo é excluído, todos os planos do grupo são excluídos automaticamente. Por outro lado, se um grupo for restaurado, todos os planos serão restaurados automaticamente.

Para obter os planos pertencentes a um grupo, faça a seguinte solicitação HTTP.

GET /groups/{group-id}/planner/plans

Ao criar um novo plano, defina a propriedade do contêiner em um objeto de plano para fazer de um grupo seu contêiner. Os planos devem estar contidos em um recurso com suporte.

Observação: O usuário que cria o plano deve ser membro do grupo que contém o plano. Ao criar um novo grupo usando Criar grupo, você não é adicionado ao grupo como membro. Depois que o grupo for criado, adicione a si mesmo como membro usando membros de postagem do grupo.

Tipo de contêiner: tarefa do planejador

O plannerTask tipo de contêiner dá suporte a planos a serem contidos em uma tarefa do Planner. Os planos contidos em uma tarefa do Planner são excluídos quando a tarefa é excluída.

Para criar um novo plano no contêiner de uma tarefa do Planner, defina a propriedade do contêiner em um objeto de plano com o tipo definido como plannerTaske defina id como a ID da tarefa do Planner.

{
    "container": {
        "id": "{task-id}",
        "type": "plannerTask"
    }
}

Como alternativa, você pode especificar a URL de uma tarefa do Planner.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/planner/tasks/{task-id}"
    }
}

Tipo de contêiner: canal do Teams

O teamsChannel tipo de contêiner dá suporte a planos criados em canais compartilhados no Teams, onde o canal é o contêiner do plano. Os planos fixados em canais compartilhados são excluídos quando o canal é excluído.

Para criar um novo plano no contêiner de um canal do Teams, defina a propriedade do contêiner em um objeto de plano com o tipo como teamsChannel, e a ID deve ser formatada como "{team-id}/channels/{channel-id}".

{
    "container": {
        "id": "{team-id}/channels/{channel-id}",
        "type": "teamsChannel"
    }
}

Como alternativa, você pode especificar a URL de um canal compartilhado no Teams.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}"
    }
}

Tipo de contêiner: Usuário

O tipo de contêiner de usuário dá suporte a planos pessoais, em que o usuário é o único usuário que acompanha suas tarefas individuais. Isso fornece flexibilidade para os usuários compartilharem ou colaborarem em seus planos pessoais. Os planos criados para um único usuário são excluídos automaticamente quando o usuário é excluído.

Para criar um novo plano no contêiner de um usuário, defina a propriedade container em um objeto de plano com o tipo sendo user.

{
    "container": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user"
    }
}

Como alternativa, você pode especificar a URL para um usuário.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/users/{id}"
    }
}

Os usuários podem atualizar seus planos pessoais para planos baseados em grupo, movendo o plano do contêiner de usuário para um contêiner de grupo, alterando o tipo de contêiner do plano user para .group

Planos

Os planos são os contêineres das tarefas. Para criar uma tarefa em um plano, defina a propriedade planId no objeto da tarefa como a ID do plano ao criar a tarefa. Atualmente, as tarefas não podem ser criadas sem planos. Para recuperar as tarefas em um plano de, faça a solicitação HTTP a seguir.

GET /planner/plans/{plan-id}/tasks

Metas

As metas expressam os resultados de alto nível que um conjunto de tarefas em um plano pretende realizar. Um plano pode ter várias metas, e uma tarefa pode ser associada a várias metas.

Para recuperar as metas em um plano, faça a seguinte solicitação HTTP.

GET /planner/plans/{plan-id}/goals

Use a propriedade goalIds somente leitura em um objeto plannerTask para identificar as metas associadas à tarefa.

Tarefas

Cada tarefa pode ser atribuída a um usuário adicionando uma atribuição na propriedade assignments no objeto de tarefa. A ID do usuário para atribuir a tarefa é o nome da propriedade open em atribuições, e a propriedade orderHint na atribuição deve ser especificada.

Detalhes de planos e tarefas

Os recursos do Planner são organizados em objetos básicos e objetos de detalhe. Os objetos básicos fornecem acesso a propriedades comuns dos recursos, adequadas para exibições de lista, enquanto os objetos de detalhe fornecem acesso a grandes propriedades dos recursos adequadas para exibições detalhadas.

Visualização

Além do plano de dados e tarefas, a API do Planner também oferece recursos para criar uma visualização comum de dados nos clientes. Há vários tipos de visualização de dados disponíveis para as tarefas, conforme listado na tabela a seguir.

As colunas personalizadas no painel de tarefas do bucket são representadas pelos objetos bucket, e a sua ordem, pela propriedade orderHint no objeto.

Os princípios de ordenação são descritos nas dicas de ordem do Planner.

Controlar alterações usando a consulta delta

A consulta delta do Planner dá suporte a objetos consulta nos quais o usuário está inscrito.

Os usuários ficam inscritos nos seguintes objetos.

Preencher o cache de objetos para consultas delta

Se quiser usar a API de consulta delta do Planner, mantenha um cache local de objetos nos quais o usuário está interessado em observar para aplicar as alterações do feed de resposta delta.

Os objetos de conteúdo delta que a consulta delta do Planner pode retornar atualmente são dos seguintes tipos:

• plannerTask
• plannerTaskDetails
• plannerPlan
• plannerPlanDetails
• plannerBucket
• plannerAssignedToTaskBoardTaskFormat
• plannerBucketTaskBoardTaskFormat
• plannerAssignedToTaskBoardTaskFormat

Use os métodos GET correspondente nos recursos para obter o estado inicial de objetos a ser preenchido no cache local.

Olhando o histórico para o plano

O Planner dá suporte a uma API para obter o histórico de alterações feitas em tarefas dentro de um plano.

Diferenciar entre a criação de objeto e a modificação de objeto

Em determinados cenários, o autor da chamada pode querer distinguir entre a criação de objeto e a modificação do objeto dentro do feed de consulta delta do Planner.

Essas diretrizes podem ser usadas para inferir a criação do objeto:

• A propriedade createdBy aparece em objetos recém-criados.
• Um objeto plannerTask recém-criado é seguido por seu objeto plannerTaskDetails correspondente.
• Um objeto plannerPlan recém-criado é seguido por seu objeto plannerPlanDetails correspondente.

Uso

O autor da chamada deve ter um cache que contenha objetos inscritos. Para obter detalhes sobre como preencher o cache local de objetos inscritos, confira Preencher o cache de objetos para consultas delta.

O fluxo de chamadas da consulta delta do Planner é assim:

1. O autor da chamada inicia uma consulta de sincronização delta, obtendo um nextLink e uma coleção de alterações vazia.
2. O autor da chamada deve preencher o cache do objeto para consultas delta com objetos nos quais o usuário esteja inscrito, atualizando o cache.
3. O autor da chamada segue o nextLink fornecido na consulta de sincronização delta inicial para obter um novo deltaLink para alterações desde a etapa anterior.
4. O autor da chamada aplica as alterações da resposta delta retornada nos objetos em seu cache.
5. O autor da chamada segue o novo deltaLink para obter o próximo deltaLink e alterações desde que o atual deltaLink foi gerado.
6. O autor da chamada aplica as alterações (caso existam) e espera um pouco antes de executar novamente as etapas anterior e atual.

Versão do recurso do Planner

O Planner cria versões de todos os recursos usando etags. Esses etags são devolvidos com a propriedade @odata.etag em cada recurso. As solicitações PATCH e DELETE requerem que a última etag conhecida pelo cliente seja especificada com um cabeçalho If-Match. O Planner permite alterações em versões mais antigas de recursos, se a alteração pretendida não entrar em conflito com alterações mais recentes aceitas pelo serviço Planner no mesmo recurso. Os clientes podem identificar qual etag para o mesmo recurso é mais recente ao calcular qual valor de etag é maior em comparação com a cadeia de caracteres ordinal. Cada recurso tem uma etag única. Os valores de Etag para diferentes recursos, incluindo recursos com relações de contenção, não podem ser comparados. Espera-se que os aplicativos cliente lidem com códigos409 de erro relacionados ao controle de versão e 412 lendo a versão mais recente do item e resolvendo as alterações conflitantes.

Condições de erro comuns do Planner

Além dos erros gerais que se aplicam ao Microsoft Graph, algumas condições de erro são específicas da API do Planner.

400 Solicitação Incorreta

Em alguns cenários comuns, as solicitações POST e PATCH podem retornar um código de status 400. Estas são algumas das mais comuns:

• As propriedades de Tipo Aberto tinham o tipo errado especificado ou nenhum tipo especificado ou não continham propriedades. Por exemplo, as propriedades plannerAssignments com valores complexos precisam declarar a propriedade @odata.type com o valor microsoft.graph.plannerAssignment.
• Os valores de dica de pedido não tinham o formato correto. Por exemplo, um valor de dica de pedido foi definido diretamente para o valor retornado ao cliente.
• Os dados são logicamente inconsistentes. Por exemplo, a data de início da tarefa é posterior à data de conclusão da tarefa.

403 Proibido

Além dos erros gerais, a API do Planner também retorna o código de 403 status quando um limite definido pelo serviço é excedido. Nesse caso, a propriedade code no tipo de recurso de erro indica o tipo de limite excedido pela solicitação. Os valores possíveis para os tipos de limite são:

412 Falha na Pré-condição

Todas as APIs do Planner POST, PATCH, e DELETE solicitações exigem que o If-Match cabeçalho seja especificado com o último valor de etag conhecido do recurso que está sujeito à solicitação. O código de status 412 também pode ser retornado se o valor da etag especificado na solicitação já não corresponder a uma versão do recurso no serviço. Nesse caso, os clientes devem ler o recurso novamente e obter uma nova etag.