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 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 utilizador ao adicionar uma atribuição na propriedade atribuições no objeto de tarefa. O ID do utilizador a atribuir a tarefa é o nome da propriedade aberta nas atribuições e a propriedade orderHint na atribuição tem de ser especificada.

Detalhes de planos e tarefas

Os recursos do Planner são dispostos em objetos básicos e objetos detalhados. Os objetos básicos fornecem acesso a propriedades comuns dos recursos, adequadas para vistas de lista, enquanto os objetos de detalhe fornecem acesso a grandes propriedades dos recursos adequados para vistas desagregar.

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 as aplicações cliente processem os códigos de erro relacionados com o controlo de versões 409 e 412 ao ler a versão mais recente do item e resolver as alterações em conflito.

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 quaisquer propriedades. Por exemplo, as propriedades plannerAssignments com valores complexos têm de declarar a propriedade @odata.type com o valor microsoft.graph.plannerAssignment.
• Os valores de sugestão de encomenda não têm o formato correto. Por exemplo, um valor de sugestão de encomenda está a ser definido diretamente para o valor devolvido ao cliente.
• Os dados são logicamente inconsistentes. Por exemplo, a data de início da tarefa é posterior à data para conclusão 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, veja Limites do Planner . 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 partilhados com um limite de utilizadores foi excedido. Este limite baseia-se na propriedade sharedWith no recurso plannerPlanDetails .
MaximumTasksCreatedByUser	O número máximo de tarefas criadas por um limite de utilizador foi excedido. Este limite baseia-se na propriedade createdBy no recurso plannerTask .
MaximumTasksAssignedToUser	O número máximo de tarefas atribuídas a um limite de utilizadores foi excedido. Este limite baseia-se na propriedade de atribuições no recurso plannerTask .
MaximumTasksInProject	O número máximo de tarefas num limite de planos foi excedido. Este limite baseia-se na propriedade planId no recurso plannerTask .
MaximumActiveTasksInProject	O número máximo de tarefas que não estão concluídas num limite de planos foi excedido. Este limite baseia-se nas propriedades planId e percentComplete no recurso plannerTask .
MaximumBucketsInProject	O número máximo de registos num limite de planos foi excedido. Este limite baseia-se 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 utilizador, que é atualmente 200. Para obter detalhes sobre os limites, veja Limites do Planner.

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.