Usar a API REST do Planner

Artigo
03/26/2023

É 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 experimentar a API do Planner, vale a pena entender como os principais objetos na API do Planner se relacionam entre si e também com os grupos do Microsoft 365.

Planejar contêineres

No Microsoft Planner, os planos estão sempre contidos por outro recurso. O recurso contido determina as regras de autorização do plano e de todas as tarefas nele contidas, bem como o ciclo de vida do plano. Por exemplo, para planos contidos por grupos do Microsoft 365, os membros do grupo serão capazes de criar, editar, resolver e excluir tarefas no plano, bem como alterar algumas propriedades de nível de plano, como o nome do plano ou nomes de rótulos. Além disso, quando o grupo é excluído, todos os planos do grupo são excluídos automaticamente ou, se um grupo for restaurado, todos os planos serão restaurados automaticamente.

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

Tipo de contêiner: grupos Microsoft 365

Os planos geralmente estão contidos em grupos do Microsoft 365 na API do Planner. 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 está criando o plano deve ser membro do grupo que conterá 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.

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. No momento, 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

Tarefas

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

Detalhes de planos e tarefas

Planner recursos são organizados em objetos básicos e objetos de detalhes. Objetos básicos fornecem acesso a propriedades comuns dos recursos, adequados para exibições de lista, enquanto os objetos de detalhes fornecem acesso a grandes propriedades dos recursos adequados para exibições de detalhamento.

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 tarefas são exibidas como	As tarefas são ordenadas com informações de
Lista plana (tarefas em um plano)	Propriedade orderHint em tarefas
Lista plana (tarefas atribuídas a um usuário)	Propriedade assigneePriority em tarefas
Modo de exibição de quadro com colunas para os destinatários (atribuídos ao quadro de tarefas)	Objeto assignedToTaskBoardTaskFormat
O modo de exibição de quadro com colunas para o andamento da tarefa na direção de conclusão (quadro de tarefa de andamento)	Objeto progressTaskBoardTaskFormat
Modo de exibição de quadro com colunas personalizadas de tarefas (quadro de tarefa do bucket):	Objeto bucketTaskBoardTaskFormat

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

Toda a ordem é controlada pelos princípios descritos em Dicas de ordem do Planner.

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 estiver em conflito com as alterações mais recentes aceitas pelo serviço do 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. Não há comparações entre os valores de etags de recursos diferentes, incluindo aqueles com relações de confinamento. Espera-se que os aplicativos cliente lidem com códigos409 de erro relacionados à 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 Open Type não são de tipos corretos ou o tipo não é especificado ou não contêm nenhuma propriedade. Por exemplo, propriedades plannerAssignments com valores complexos precisam declarar a propriedade @odata.type com valor microsoft.graph.plannerAssignment.
Os valores de dica de pedido não têm o formato correto. Por exemplo, um valor de dica de pedido está sendo 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 vencimento da tarefa.

403 Proibido

Além dos erros gerais, a API do Planner também devolve esse 403 código de status quando um limite definido pelo serviço foi excedido. Se este for o caso, a propriedade code no tipo de recurso do erro indicará o tipo do limite excedido pela solicitação. Para obter detalhes sobre os limites, consulte Planner limites . Os valores possíveis para os tipos de limite são:

Valor	Descrição
MaximumProjectsOwnedByUser	Foi excedido o número máximo de planos contidos pelo limite do grupo. Este limite se aplica a planos contidos por um grupo com base na propriedade contêiner do recurso plannerPlan.
MaximumProjectsSharedWithUser	O número máximo de planos compartilhados com um limite de usuário foi excedido. Esse limite é baseado na propriedade sharedWith no recurso plannerPlanDetails .
MaximumTasksCreatedByUser	O número máximo de tarefas criadas por um limite de usuário foi excedido. Esse limite é baseado na propriedade createdBy no recurso plannerTask .
MaximumTasksAssignedToUser	O número máximo de tarefas atribuídas a um limite de usuário foi excedido. Esse limite é baseado na propriedade assignments no recurso plannerTask .
MaximumTasksInProject	O número máximo de tarefas em um limite de plano foi excedido. Esse limite é baseado na propriedade planId no recurso plannerTask .
MaximumActiveTasksInProject	O número máximo de tarefas que não são concluídas em um limite de plano foi excedido. Esse limite é baseado nas propriedades planId e percentComplete no recurso plannerTask .
MaximumBucketsInProject	O número máximo de buckets em um limite de plano foi excedido. Esse limite é baseado na propriedade planId no recurso plannerBucket .
MaximumUsersSharedWithProject	A propriedade sharedWith no recurso plannerPlanDetails contém demasiados valores.
MaximumReferencesOnTask	A propriedade referênciasno recurso plannerTaskDetails contém demasiados valores.
MaximumChecklistItemsOnTask	A propriedade lista de verificação no recurso plannerTaskDetails contém demasiados valores.
MaximumAssigneesInTasks	A propriedade tarefasno recurso plannerTask contém demasiados valores.
MaximumPlannerPlans	O grupo já contém o número máximo de planos pertencentes a um usuário, que atualmente é 200. Para obter detalhes sobre limites, consulte Planner limites.

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.