Usar a API REST do Planner

Artigo
07/04/2024

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

É 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 utilizar a API do Planner, é útil compreender 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 noutro recurso. O recurso que contém o plannerPlanContainer determina as regras de autorização do plano e todas as tarefas no mesmo e o ciclo de vida do plano. Pode criar um plano num contentor de um dos seguintes tipos: driveItem, grupo do Microsoft 365, projeto planner, lista ou utilizador.

O tipo de contentor mais comum é um grupo.

Tipo de contêiner: grupos Microsoft 365

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

Os membros do grupo podem criar, editar, resolver e eliminar tarefas no plano. Os membros do grupo também podem alterar algumas propriedades ao nível do plano, como o nome do plano ou os nomes das etiquetas. Além disso, quando o grupo é eliminado, todos os planos no grupo são eliminados 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 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.

Tipo de contentor: Utilizador

O tipo de contentor do utilizador suporta planos pessoais, em que o utilizador é o único utilizador a controlar as respetivas tarefas individuais. Isto fornece a flexibilidade para os utilizadores partilharem ou colaborarem nos seus planos pessoais. Os planos criados para um único utilizador são eliminados automaticamente quando o utilizador é eliminado.

Para criar um novo plano no contentor de um utilizador, defina a propriedade de contentor num objeto de plano com o tipo .user

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

Em alternativa, pode especificar o URL de um utilizador.

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

Os utilizadores podem atualizar os seus planos pessoais para planos baseados em grupos ao mover o plano do contentor de utilizador para um contentor de grupo, alterando o tipo de contentor do plano de 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

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 de desagregação.

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.

Os princípios de ordenação são descritos nas sugestões 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.

Tipo de recurso do Planner	Instâncias assinadas
tarefas	Criadas pelo usuário Atribuídas ao usuário Pertencentes a um plano que o usuário possui Contidas em um plano compartilhado com o usuário por meio da coleção sharedWith do plano
planos	Compartilhado com o usuário por meio da coleção sharedWith do plano
buckets	Contidas em um plano compartilhado com o usuário por meio da coleção sharedWith do plano

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 payload delta que a consulta delta do Planner pode devolver atualmente são dos seguintes tipos:

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

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 nos objetos criados recentemente.
Um objeto plannerTask recentemente criado é seguido pelo respetivo objeto plannerTaskDetails correspondente.
Um objeto plannerPlan recentemente criado é seguido pelo 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:

O autor da chamada inicia uma consulta de sincronização delta, obtendo um nextLink e uma coleção de alterações vazia.
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.
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.
O autor da chamada aplica as alterações da resposta delta retornada nos objetos em seu cache.
O autor da chamada segue o novo deltaLink para obter o próximo deltaLink e alterações desde que o atual deltaLink foi gerado.
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 às versões mais antigas dos recursos, se a alteração pretendida não entrar em conflito com as alterações mais recentes aceites 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 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 tinham o tipo errado especificado ou nenhum tipo especificado ou não continham 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 tinham o formato correto. Por exemplo, um valor de sugestão de encomenda foi 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 o 403 código de estado quando um limite definido pelo serviço é excedido. Em caso afirmativo, a propriedade de código no tipo de recurso de erro indica o tipo de limite excedido pelo pedido. Os valores possíveis para os tipos de limite são:

Valor	Descrição
MaximumProjectsOwnedByUser	O número máximo de planos contidos num limite de grupo foi excedido. A propriedade de contentor do recurso plannerPlan determina este limite.
MaximumProjectsSharedWithUser	O número máximo de planos partilhados com um limite de utilizadores foi excedido. A propriedade sharedWith no recurso plannerPlanDetails determina este limite.
MaximumTasksCreatedByUser	O número máximo de tarefas criadas por um limite de utilizador foi excedido. A propriedade createdBy no recurso plannerTask determina este limite.
MaximumTasksAssignedToUser	O número máximo de tarefas atribuídas a um limite de utilizador foi excedido. A propriedade atribuições no recurso plannerTask determina este limite.
MaximumTasksInProject	O número máximo de tarefas num limite de planos foi excedido. A propriedade planId no recurso plannerTask determina este limite.
MaximumActiveTasksInProject	O número máximo de tarefas que não estão concluídas num limite de planos foi excedido. As propriedades planId e percentComplete no recurso plannerTask determinam este limite.
MaximumBucketsInProject	O número máximo de registos num limite de planos foi excedido. A propriedade planId no recurso plannerBucket determina este limite.
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.
MaximumFavoritePlansForUser	A propriedade favoritePlanReferences no recurso plannerUser contém demasiados valores.
MaximumRecentPlansForUser	A propriedade recentPlanReferences no recurso plannerUser contém demasiados valores.
MaximumContextsOnPlan	A propriedade contextosno recurso plannerPlan contém demasiados valores.

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.

Compartilhar via