Usar la API de REST de Planner

Artículo
04/05/2024

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

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 trabajar con la API de Planner, es útil comprender cómo se relacionan los objetos principales entre sí y con los grupos de Microsoft 365.

Contenedores de Plan

En Microsoft Planner, los planes siempre están contenidos en otro recurso. El recurso contenedor, plannerPlanContainer, determina las reglas de autorización del plan y todas las tareas del mismo, así como el ciclo de vida del plan. Puede crear un plan en un contenedor de uno de los tipos siguientes: driveItem, grupo de Microsoft 365, Planner proyecto, lista o usuario.

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

Tipo de contenedor: Grupos de Microsoft 365

Los planes suelen estar contenidos en grupos de la API de Planner.

Los miembros del grupo pueden crear, editar, resolver y eliminar tareas en el plan. Los miembros del grupo también pueden cambiar algunas propiedades de nivel de plan, como el nombre de los nombres del plan o de la etiqueta. Además, cuando se elimina el grupo, todos los planes del grupo se eliminan automáticamente. Por el contrario, si se restaura un grupo, todos los planes se restauran automáticamente.

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.

Tipo de contenedor: Usuario

El tipo de contenedor de usuario admite planes personales, donde el usuario es el único usuario que realiza el seguimiento de sus tareas individuales. Esto proporciona la flexibilidad para que los usuarios compartan o colaboren en sus planes personales. Los planes creados para un solo usuario se eliminan automáticamente cuando se elimina el usuario.

Para crear un nuevo plan en el contenedor de un usuario, establezca la propiedad container en un objeto plan con el tipo .user

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

Como alternativa, puede especificar la dirección URL de un usuario.

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

Los usuarios pueden actualizar sus planes personales a planes basados en grupos moviendo el plan del contenedor de usuarios a un contenedor de grupo, cambiando el tipo del contenedor para el plan de user a group.

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. Las tareas actualmente no se pueden crear 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.

Los principios de ordenación se describen en Planner sugerencias de orden.

Control de cambios con consulta delta

La consulta delta de Planner admite consultar objetos a los que el usuario se ha suscrito.

Los usuarios están suscritos a los siguientes objetos.

Tipo de recurso planner	Instancias suscritas
Tasks	Creadas por el usuario Asignadas al usuario Pertenecen a un plan del que el usuario es propietario Contenidas en un plan que se comparte con el usuario a través la colección SharedWith del plan
Planes	Compartidas con el usuario a través la colección SharedWith del plan
Depósitos	Contenidas en un plan que se comparte con el usuario a través la colección SharedWith del plan

Rellenar la caché de objetos para las consultas delta

Si desea usar la API de consulta delta de Planner, mantenga una caché local de objetos en que el usuario está interesado en observar para aplicar los cambios de la fuente de respuesta delta.

Los objetos de carga delta que la consulta delta de Planner puede devolver actualmente son de los siguientes tipos:

Usar los métodos GET correspondientes en el recurso para obtener el estado inicial de los objetos para rellenar la caché local.

Diferenciar entre la creación y la modificación de objetos

En ciertos escenarios, puede que se quiera distinguir entre la creación de objetos y la modificación de objetos en la fuente de la consulta delta de Planner.

Puede usar estas instrucciones para deducir la creación de objetos:

La propiedad createdBy aparece en los objetos recién creados.
Un objeto plannerTask recién creado va seguido de su objeto plannerTaskDetails correspondiente.
Un objeto plannerPlan recién creado va seguido de su objeto plannerPlanDetails correspondiente.

Uso

Se espera que el autor de la llamada tenga una caché con los objetos suscritos. Para obtener más información sobre cómo rellenar la caché local de objetos suscritos, consulte Rellenar la caché de objetos para las consultas delta.

El flujo de llamadas de la consulta delta de Planner es el siguiente:

El autor de la llamada inicia una consulta de sincronización delta y obtener un nextLink y una colección vacía de cambios.
El autor de llamada debe rellenar la caché de objetos de las consultas delta con objetos a los que el usuario está suscrito, actualizando la caché.
El autor de la llamada sigue el nextLink proporcionado en la consulta de sincronización delta inicial para obtener un nuevo deltaLink a los cambios que haya desde el paso anterior.
El autor de la llamada aplica los cambios en la respuesta delta devuelta a los objetos en la caché.
El autor de la llamada sigue el nuevo deltaLink para obtener el siguiente deltaLink y los cambios desde que se generó el deltaLink actual.
El autor de la llamada aplica los cambios (si corresponde) y espera un poco antes de volver a ejecutar el anterior paso y este paso.

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 versiones anteriores de los recursos, si el cambio previsto no entra en conflicto con los cambios más recientes aceptados por el servicio 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 los valores de Etag para distintos recursos, incluidos los recursos con 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 tenían el tipo incorrecto especificado o no se especificó ningún tipo, o no contenían 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 tenían el formato correcto. Por ejemplo, un valor de sugerencia de pedido se estableció 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 403 estado cuando se supera un límite definido por el servicio. Si es así, la propiedad code del tipo de recurso error indica el tipo del límite superado por la solicitud. Los valores posibles para los tipos de límite son los siguientes:

Valor	Descripción
MaximumProjectsOwnedByUser	Se superó el número máximo de planes contenidos en un límite de grupo. La propiedad container del recurso plannerPlan determina este límite.
MaximumProjectsSharedWithUser	Se superó el número máximo de planes compartidos con un límite de usuario. La propiedad sharedWith del recurso plannerPlanDetails determina este límite.
MaximumTasksCreatedByUser	Se superó el número máximo de tareas creadas por un límite de usuario. La propiedad createdBy del recurso plannerTask determina este límite.
MaximumTasksAssignedToUser	Se superó el número máximo de tareas asignadas a un límite de usuario. La propiedad assignments del recurso plannerTask determina este límite.
MaximumTasksInProject	Se superó el número máximo de tareas de un límite de plan. La propiedad planId del recurso plannerTask determina este límite.
MaximumActiveTasksInProject	Se superó el número máximo de tareas que no se completan en un límite de plan. Las propiedades planId y percentComplete del recurso plannerTask determinan este límite.
MaximumBucketsInProject	Se superó el número máximo de cubos de un límite de plan. La propiedad planId del recurso plannerBucket determina este límite.
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.
MaximumFavoritePlansForUser	La propiedad favoritePlanReferences del recurso plannerUser contiene demasiados valores.
MaximumRecentPlansForUser	La propiedad recentPlanReferences del recurso plannerUser contiene demasiados valores.
MaximumContextsOnPlan	La propiedad contexts del recurso plannerPlan contiene demasiados valores.

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.