Usar a API REST do PlannerUse the Planner REST API

É possível usar a API do Planner no Microsoft Graph para criar e atribuir tarefas aos usuários em um grupo no Office 365.You can use the Planner API in Microsoft Graph to create tasks and assign them to users in a group in Office 365.

Antes de começar com a API do Planner, você deve compreender como os objetos principais se relacionam entre si, bem como, com os grupos do Office 365.Before you get started with Planner API, you will want to understand how the main objects relate to each other as well as to Office 365 groups.

Grupos do Office 365Office 365 Groups

Os grupos do Office 365 são os proprietários dos planos da API do Planner.Office 365 groups are the owners of the plans in the Planner API. Para obter os planos pertencentes a um grupo, faça a solicitação HTTP a seguir.To get the plans owned by a group, make the following HTTP request.

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

Ao criar um novo plano, torne o grupo o proprietário do plano definindo a propriedade owner em um objeto de plano.When creating a new plan, make a group its owner by setting the owner property on a plan object. Os planos devem pertencer a grupos.Plans must be owned by groups.

Observação: o usuário que está criando o plano deve ser um membro do grupo que será proprietário do plano.Note: The user who is creating the plan must be a member of the group that will own the plan. Ao criar um novo grupo usando Criar grupo, você não é adicionado ao grupo como membro.When you create a new group by using Create group, you are not added to the group as a member. Depois que o grupo for criado, adicione a si mesmo como membro usando membros de postagem do grupo.After the group is created, add yourself as a member by using group post members.

PlanosPlans

Os planos são os contêineres das tarefas.Plans are the containers of tasks. Para criar uma tarefa em um plano, defina a propriedade planId no objeto da tarefa como a ID do plano ao criar a tarefa.To create a task in a plan, set the planId property on the task object to the ID of the plan while creating the task. No momento, as tarefas não podem ser criadas sem planos.Tasks currently cannot be created without plans. Para recuperar as tarefas em um plano de, faça a solicitação HTTP a seguir.To retrieve the tasks in a plan, make the following HTTP request.

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

TarefasTasks

Cada tarefa pode ser atribuída a um usuário ao adicionar uma atribuição à propriedade assignments no objeto task. A ID do usuário ao qual a tarefa será atribuída é o nome da propriedade open em assignments. Além disso, a propriedade orderHint na atribuição deve ser especificada.Each task can be assigned to a user by adding an assignment in the assignments property on the task object. The ID of the user to assign the task is the name of the open property on assignments, and the orderHint property on the assignment must be specified.

Detalhes de planos e tarefasTask and plan details

Os recursos do Planner são organizados em objetos básicos e objetos detalhados. Os objetos básicos oferecem acesso às propriedades comuns dos recursos, adequadas para modos de exibição de lista. No entanto, os objetos detalhados fornecem acesso a grandes propriedades dos recursos, adequadas para modos de exibição de busca detalhada.Planner resources are arranged into basic objects and detail objects. Basic objects provide access to common properties of the resources, suitable for list views, while the detail objects provide access to large properties of the resources suitable for drill down views.

VisualizaçãoVisualization

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.Aside from task and plan data, the Planner API also provides resources for creating a common visualization of data across clients. Há vários tipos de visualização de dados disponíveis para as tarefas, conforme listado na tabela a seguir.Several types of visualization data are available for tasks, as listed in the following table.

As tarefas são exibidas comoTasks are shown as As tarefas são ordenadas com informações deTasks are ordered with information from
Lista plana (tarefas em um plano)Flat list (tasks in a plan) Propriedade orderHint em tarefasorderHint property on tasks
Lista plana (tarefas atribuídas a um usuário)Flat list (tasks assigned to a user) Propriedade assigneePriority em tarefasassigneePriority property on tasks
Modo de exibição de quadro com colunas para os destinatários (atribuídos ao quadro de tarefas)Board view with columns for assignees (assigned to task board) Objeto assignedToTaskBoardTaskFormatassignedToTaskBoardTaskFormat object
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)Board view with columns for progress of the task towards completion (progress task board) Objeto progressTaskBoardTaskFormatprogressTaskBoardTaskFormat object
Modo de exibição de quadro com colunas personalizadas de tarefas (quadro de tarefa do bucket):Board view with custom columns of tasks (bucket task board): Objeto bucketTaskBoardTaskFormatbucketTaskBoardTaskFormat object

As colunas personalizadas no quadro de tarefas do bucket são representadas pelos objetos bucket e, sua ordem, pela propriedade orderHint no objeto.The custom columns in the bucket task board are represented by bucket objects, and their order by orderHint property on the object.

Toda a ordem é controlada pelos princípios descritos em Dicas de ordem do Planner.All the ordering is controlled by the principles described in Planner order hints.

Versão do recurso do PlannerPlanner resource versioning

O Planner cria versões de todos os recursos usando etags.Planner versions all resources using etags. Esses etags são retornados com a propriedade @odata.etag em cada recurso.These etags are returned with @odata.etag property on each resource. As solicitações PATCH e DELETE requerem que a última etag conhecida pelo cliente seja especificada com um cabeçalho If-Match.PATCH and DELETE requests require the last etag known by the client to be specified with a If-Match header. 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.Planner allows changes to older versions of resources, if the intended change does not conflict with newer changes accepted by the Planner service on the same resource. 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.The clients can identify which etag for the same resource is newer by calculating which etag value is greater in ordinal string comparison. Cada recurso tem uma etag única.Each resource has a unique etag. Não há comparações entre os valores de etags de recursos diferentes, incluindo aqueles com relações de confinamento.Etag values for different resources, including those with containment relationships, cannot be compared. Espera-se que os aplicativos cliente tratem dos controles de versão relacionados aos códigos de erro 409 e 412 lendo a versão mais recente do item e resolvendo as alterações conflitantes.The client apps are expected to handle versioning related error codes 409 and 412 by reading the latest version of the item and resolving the conflicting changes.

Condições de erro comuns do PlannerCommon Planner error conditions

Além dos erros gerais que se aplicam ao Microsoft Graph, algumas condições de erro são específicas da API do Planner.In addition to general errors that apply to Microsoft Graph, some error conditions are specific to the Planner API.

400 Solicitação Incorreta400 Bad request

Em alguns cenários comuns, as solicitações POST e PATCH podem retornar um código de status 400.In some common scenarios, POST and PATCH requests can return a 400 status code. Estas são algumas das mais comuns:The following are some of the common causes:

  • As propriedades Open Type não têm os tipos corretos ou o tipo não foi especificado ou não contêm propriedades. Por exemplo, as propriedades plannerAssignments com valores complexos precisam declarar a propriedade com valor .Open Type properties are not of correct types, or the type isn't specified, or they do not contain any properties. For example, plannerAssignments properties with complex values need to declare @odata.type property with value microsoft.graph.plannerAssignment.
  • Os valores da dica de ordem não têm o formato correto. Por exemplo, um valor de dica de ordem está sendo definido diretamente como o valor retornado ao cliente.Order hint values do not have the correct format. For example, an order hint value is being set directly to the value returned to the client.
  • Os dados são ilogicamente inconsistentes. Por exemplo, a data de início da tarefa é posterior à data de conclusão da tarefa.The data is logically inconsistent. For example, start date of task is later than due date of the task.

403 Proibido403 Forbidden

Além dos erros gerais, a API do Planner também retorna esse código de status 403 quando um limite definido pelo serviço é excedido.In addition to the general errors, the Planner API also returns the 403 status code when a service-defined limit has been exceeded. Se esse for o caso, a propriedade code no tipo de recurso do erro indicará o tipo do limite excedido pela solicitação.If this is the case, the code property on the error resource type will indicate the type of the limit exceeded by the request. Os valores possíveis para os tipos de limite são:The following are the possible values for the limit types.

ValorValue DescriçãoDescription
MaximumProjectsOwnedByUserMaximumProjectsOwnedByUser Foi excedido o número máximo de Planos pertencentes ao limite do grupo. Esse limite se baseia na propriedade owner no recurso plannerPlan.The maximum number of Plans owned by a group limit has been exceeded. This limit is based on the owner property on the plannerPlan resource.
MaximumProjectsSharedWithUserMaximumProjectsSharedWithUser Foi excedido o número máximo de Planos compartilhados com um limite de usuário. Esse limite se baseia na propriedade sharedWith no recurso plannerPlanDetails.The maximum number of Plans shared with a user limit has been exceeded. This limit is based on the sharedWith property on the plannerPlanDetails resource.
MaximumTasksCreatedByUserMaximumTasksCreatedByUser Foi excedido o número máximo de Tarefas criadas pelo limite do usuário. Esse limite se baseia na propriedade createdBy no recurso plannerTask.The maximum number of Tasks created by a user limit has been exceeded. This limit is based on the createdBy property on the plannerTask resource.
MaximumTasksAssignedToUserMaximumTasksAssignedToUser Foi excedido o número máximo de Tarefas atribuídas ao limite do usuário. Esse limite se baseia na propriedade assignments no recurso plannerTask.The maximum number of Tasks assigned to a user limit has been exceeded. This limit is based on the assignments property on the plannerTask resource.
MaximumTasksInProjectMaximumTasksInProject Foi excedido o número máximo de Tarefas no limite de um Plano. Esse limite se baseia na propriedade planId no recurso plannerTask.The maximum number of Tasks in a Plan limit has been exceeded. This limit is based on the planId property on the plannerTask resource.
MaximumActiveTasksInProjectMaximumActiveTasksInProject Foi excedido o número máximo de Tarefas que não foram concluídas no limite de um Plano. Esse limite se baseia nas propriedades planId e percentComplete no recurso plannerTask.The maximum number of Tasks that aren't completed in a Plan limit has been exceeded. This limit is based on the planId and percentComplete properties on the plannerTask resource.
MaximumBucketsInProjectMaximumBucketsInProject Foi excedido o número máximo de Buckets no limite de um Plano. Esse limite se baseia na propriedade planId no recurso plannerBucket.The maximum number of Buckets in a Plan limit has been exceeded. This limit is based on the planId property on the plannerBucket resource.
MaximumUsersSharedWithProjectMaximumUsersSharedWithProject A propriedade sharedWith no recurso plannerPlanDetails contém muitos valores.The sharedWith property on the plannerPlanDetails resource contains too many values.
MaximumReferencesOnTaskMaximumReferencesOnTask A propriedade references no recurso plannerTaskDetails contém muitos valores.The references property on the plannerTaskDetails resource contains too many values.
MaximumChecklistItemsOnTaskMaximumChecklistItemsOnTask A propriedade checklist no recurso plannerTaskDetails contém muitos valores.The checklist property on the plannerTaskDetails resource contains too many values.
MaximumAssigneesInTasksMaximumAssigneesInTasks A propriedade assignments no recurso plannerTask contém muitos valores.The assignments property on the plannerTask resource contains too many values.
MaximumPlannerPlansMaximumPlannerPlans O grupo já contém um plano.The group already contains a Plan. Atualmente, os grupos só podem conter um plano.Currently, groups can only contain one Plan. Observação: alguns aplicativos da Microsoft podem ultrapassar esse limite.Note: Some Microsoft apps can exceed this limit. Futuramente, essa funcionalidade será estendida para todos os aplicativos.In the future, we will extend this capability to all apps.

412 Falha na Pré-condição412 Precondition Failed

Todas as solicitações POST, PATCH e DELETE da API do Planner exigem que o cabeçalho If-Match seja especificado com o último valor de etag conhecido do recurso que está sujeito à solicitação.All Planer API POST, PATCH, and DELETE requests require the If-Match header to be specified with the last known etag value of the resource that is subject to the request. 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.The 412 status code can also be returned if the etag value specified in the request no longer matches a version of the resource in the service. Nesse caso, os clientes devem ler o recurso novamente e obter uma nova etag.In this case, the clients should read the resource again and get a new etag.