Usar la API de REST de Planner

Artículo
03/26/2023

Puede usar la API de Planner en Microsoft Graph para crear tareas y asignarlas a los usuarios de un grupo de Microsoft 365.

Antes de empezar a probar la API de Planner, conviene que entienda cómo se relacionan los objetos principales de la API de Planner entre sí y con los grupos de Microsoft 365.

Contenedores de Plan

En Microsoft Planner, los planes siempre están dentro de otro recurso. El recurso contenedor determina las reglas de autorización del plan y de todas las tareas que contiene, así como el ciclo de vida del plan. Por ejemplo, para los planes incluidos en Grupos de Microsoft 365, los miembros del grupo podrán crear, editar, resolver y eliminar tareas en el plan, así como también cambiar algunas propiedades a nivel del plan, como el nombre del plan o los nombres de las etiquetas. Además, cuando se elimina el grupo, todos los planes del grupo se eliminarán automáticamente o, si se restaura un grupo, todos los planes se restaurarán automáticamente.

El tipo de contenedor más común es un grupo de Microsoft 365.

Tipo de contenedor: Grupos de Microsoft 365

Los planes suelen estar contenidos en Grupos de Microsoft 365 en la API de Planner. Para obtener los planes que pertenecen a un grupo, realice la siguiente solicitud HTTP.

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

Cuando cree un nuevo plan, establezca la propiedad contenedor en un objeto de plan para convertir un grupo en su contenedor. Los planes deben estar contenidos en un recurso compatible.

Nota: el usuario que cree el plan debe ser miembro del grupo que contendrá el plan. Al crear un nuevo grupo usando Crear grupo, no se le agrega al grupo como miembro. Después de crear el grupo, puede agregarse como miembro usando miembros del publicación del grupo.

Planes

Los planes son los contenedores de las tareas. Para crear una tarea en un plan, establezca la propiedad planId del objeto de tarea en el identificador del plan al crear la tarea. Actualmente no es posible crear tareas sin planes. Para recuperar las tareas de un plan, realice la siguiente solicitud HTTP.

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

Tareas

Cada tarea se puede asignar a un usuario agregando una asignación en la propiedad assignments en el objeto de tarea. El identificador del usuario para asignar la tarea es el nombre de la propiedad open en las asignaciones y se debe especificar la propiedad orderHint en la asignación.

Detalles de la tarea y del plan

Planner recursos se organizan en objetos básicos y objetos de detalle. Los objetos básicos proporcionan acceso a las propiedades comunes de los recursos, adecuados para las vistas de lista, mientras que los objetos de detalle proporcionan acceso a las propiedades grandes de los recursos adecuados para las vistas de exploración en profundidad.

Visualización

Además de datos de la tarea y del plan, la API de Planner también ofrece recursos para crear una visualización común de datos de los clientes. Hay varios tipos de datos de visualización disponibles para las tareas, como se indica en la tabla siguiente.

Las tareas se muestran como	Las tareas se ordenan con información de
Lista plana (tareas de un plan)	Propiedad orderHint en las tareas
Lista plana (tareas asignadas a un usuario)	Propiedad assigneePriority en las tareas
Vista de panel con columnas para los usuarios asignados (asignados a un panel de tareas)	El objeto assignedToTaskBoardTaskFormat
Vista de panel con columnas con el progreso de la tarea hacia su finalización (panel de tareas en curso)	El objeto progressTaskBoardTaskFormat
Vista de panel con columnas personalizadas de tareas (panel de tareas de depósito):	El objeto bucketTaskBoardTaskFormat

Las columnas personalizadas del panel de tareas de depósito se representan mediante objetos bucket y su orden mediante la propiedad orderHint en el objeto.

El orden se controla mediante los principios indicados en Sugerencias sobre el orden de Planner.

Control de versiones de los recursos de Planner

Planner controla las versiones de todos los recursos mediante etags. Estas etags se devuelven con la propiedad @odata.etag de cada recurso. Las solicitudes PATCH y DELETE requieren que se especifique la última etag conocida por el cliente con el encabezado If-Match. Planner permite realizar cambios en las versiones anteriores de los recursos, siempre y cuando el cambio deseado no entre en conflicto con los cambios más recientes aceptados por el servicio de Planner en el mismo recurso. Los clientes pueden identificar qué etag del recurso es más reciente si calculan qué valor de etag es mayor en una comparación de cadenas ordinal. Cada recurso tiene una etag independiente. No se pueden comparar valores de ETag de recursos diferentes, incluidos los que tienen relaciones de contención. Se espera que las aplicaciones cliente controlen los códigos409 de error relacionados con el control de versiones y 412 que lean la versión más reciente del elemento y resuelvan los cambios en conflicto.

Condiciones de error comunes de Planner

Además de los errores generales que se aplican a Microsoft Graph, hay algunas condiciones de error específicas de la API de Planner.

400 Solicitud incorrecta

En algunos escenarios comunes, las solicitudesPOST y PATCH pueden devolver un código de estado 400. Las siguientes son algunas de las causas comunes:

Las propiedades De tipo abiertas no son de tipos correctos o no se especifica el tipo, o no contienen ninguna propiedad. Por ejemplo, las propiedades plannerAssignments con valores complejos deben declarar la propiedad @odata.type con el valor microsoft.graph.plannerAssignment.
Los valores de sugerencias de pedido no tienen el formato correcto. Por ejemplo, un valor de sugerencia de pedido se establece directamente en el valor devuelto al cliente.
Los datos son lógicamente incoherentes. Por ejemplo, la fecha de inicio de la tarea es posterior a la fecha de vencimiento de la tarea.

403 Prohibido

Además de los errores generales, la API de Planner también devuelve el código de estado 403 cuando se ha excedido un límite definido por el servicio. Si este es el caso, la propiedad code del tipo de recurso de error indicará el tipo del límite superado por la solicitud. Para obtener más información sobre los límites, consulte límites de Planner . Los valores posibles para los tipos de límite son los siguientes:

Valor	Descripción
MaximumProjectsOwnedByUser	Se ha superado el límite máximo de planes contenidos en un grupo. Este límite se aplica a los planes contenidos por un grupo en función de la propiedad container del recurso plannerPlan.
MaximumProjectsSharedWithUser	Se ha superado el número máximo de planes compartidos con un límite de usuario. Este límite se basa en la propiedad sharedWith del recurso plannerPlanDetails .
MaximumTasksCreatedByUser	Se ha superado el número máximo de tareas creadas por un límite de usuario. Este límite se basa en la propiedad createdBy del recurso plannerTask .
MaximumTasksAssignedToUser	Se ha superado el número máximo de tareas asignadas a un límite de usuario. Este límite se basa en la propiedad assignments del recurso plannerTask .
MaximumTasksInProject	Se ha superado el número máximo de tareas de un límite de plan. Este límite se basa en la propiedad planId del recurso plannerTask .
MaximumActiveTasksInProject	Se ha superado el número máximo de tareas que no se completan en un límite de plan. Este límite se basa en las propiedades planId y percentComplete del recurso plannerTask .
MaximumBucketsInProject	Se ha superado el número máximo de cubos de un límite de plan. Este límite se basa en la propiedad planId del recurso plannerBucket .
MaximumUsersSharedWithProject	La propiedad sharedWith del recurso plannerPlanDetails contiene demasiados valores.
MaximumReferencesOnTask	La propiedad references del recurso plannerTaskDetails contiene demasiados valores.
MaximumChecklistItemsOnTask	La propiedad checklist del recurso plannerTaskDetails contiene demasiados valores.
MaximumAssigneesInTasks	La propiedad assignments del recurso plannerTask contiene demasiados valores.
MaximumPlannerPlans	El grupo ya contiene el número máximo de planes propiedad de un usuario, que actualmente es 200. Para obtener más información sobre los límites, consulte límites de Planner.

412 Error de condición previa

Todas las solicitudes POST, PATCH y DELETE de la API de Planner requieren que se especifique un encabezado If-Match con el último valor de etag conocido del recurso que está sujeto a la solicitud. También se puede devolver el código de estado 412 si el valor de eTag especificado en la solicitud ya no coincide con una versión del recurso del servicio. En este caso, los clientes deben volver a leer el recurso y obtener una nueva ETag.