Usar la API de REST de Planner

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 usar 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 se incluyen en otro recurso. El recurso que lo contiene, plannerPlanContainer, determina las reglas de autorización del plan y todas las tareas que contiene, así como el ciclo de vida del plan. Puede crear un plan en un contenedor de uno de los siguientes tipos: driveItem, grupo Microsoft 365, plannerTask, proyecto de Planner, roster, teamsChannel o usuario.

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

Tipo de contenedor: Grupos de Microsoft 365

Normalmente, los planes se incluyen en grupos en 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 del plan o los nombres de etiquetas. 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 crea el plan debe ser miembro del grupo que contiene el plan. Si crea un grupo nuevo mediante Crear grupo, no se le agregará como miembro. Después de crear el grupo, puede agregarse como miembro usando miembros del publicación del grupo.

Tipo de contenedor: tarea de Planner

El plannerTask tipo de contenedor admite planes para ser contenidos por una tarea de Planner. Los planes contenidos por una tarea de Planner se eliminan cuando se elimina la tarea.

Para crear un nuevo plan en el contenedor de una tarea de Planner, establezca la propiedad de contenedor en un objeto de plan con tipo establecido en plannerTask, y set id en el ID de la tarea de Planner.

{
    "container": {
        "id": "{task-id}",
        "type": "plannerTask"
    }
}

Como alternativa, puede especificar la dirección URL de una tarea de Planner.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/planner/tasks/{task-id}"
    }
}

Tipo de contenedor: canal de Teams

El teamsChannel tipo de contenedor admite planes creados en canales compartidos en Teams, donde el canal es el contenedor del plan. Los planes anclados en canales compartidos se eliminan cuando se elimina el canal.

Para crear un nuevo plan en el contenedor de un canal de Teams, establezca la propiedad de contenedor en un objeto de plan con tipo como teamsChannel, y el identificador debe tener el formato "{team-id}/channels/{channel-id}".

{
    "container": {
        "id": "{team-id}/channels/{channel-id}",
        "type": "teamsChannel"
    }
}

Como alternativa, puede especificar la dirección URL de un canal compartido en Teams.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}"
    }
}

Tipo de contenedor: Usuario

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

Para crear un nuevo plan en el contenedor de un usuario, establezca la propiedad del contenedor en un objeto de 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/{id}"
    }
}

Los usuarios pueden actualizar sus planes personales a planes basados en grupo moviendo el plan del contenedor de usuarios a un contenedor de grupo, cambiando el tipo de contenedor del 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. Actualmente, las tareas no se pueden crear sin planes. Para recuperar las tareas de un plan, realice la siguiente solicitud HTTP.

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

Objetivos

Los objetivos expresan los resultados de alto nivel que un conjunto de tareas de un plan pretende lograr. Un plan puede tener varios objetivos y una tarea se puede asociar a varios objetivos.

Para recuperar los objetivos de un plan, realice la siguiente solicitud HTTP.

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

Usa la propiedad goalIds de solo lectura en un objeto plannerTask para identificar los objetivos asociados a la tarea.

Tareas

Cada tarea se puede asignar a un usuario agregando una asignación en la propiedad de asignaciones del 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 tarea.

Detalles de la tarea y del plan

Los recursos de Planner se organizan en objetos básicos y objetos de detalle. Los objetos básicos proporcionan acceso a propiedades comunes de los recursos, adecuadas para vistas de lista, mientras que los objetos de detalle proporcionan acceso a propiedades grandes de los recursos adecuadas para vistas exploradas 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 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 sugerencias de ordenación de Planner.

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.

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 puede devolver actualmente la consulta delta de Planner son de los siguientes tipos:

• plannerTask
• plannerTaskDetails
• plannerPlan
• plannerPlanDetails
• plannerBucket
• plannerAssignedToTaskBoardTaskFormat
• plannerBucketTaskBoardTaskFormat
• plannerAssignedToTaskBoardTaskFormat

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

Mirando el historial del plan

Planner admite una API para obtener el historial de cambios realizados en las tareas de un plan.

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 correspondiente objeto plannerTaskDetails .
• Un objeto plannerPlan recién creado va seguido de su correspondiente objeto plannerPlanDetails .

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:

1. El autor de la llamada inicia una consulta de sincronización delta y obtener un nextLink y una colección vacía de cambios.
2. 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é.
3. 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.
4. El autor de la llamada aplica los cambios en la respuesta delta devuelta a los objetos en la caché.
5. El autor de la llamada sigue el nuevo deltaLink para obtener el siguiente deltaLink y los cambios desde que se generó el deltaLink actual.
6. 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 cambios en versiones anteriores de recursos, siempre que el cambio previsto 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 ETag de diferentes 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 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 abierto tenían el tipo incorrecto especificado o ningún tipo especificado, 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 sugerencia 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 estado cuando se supera un límite definido por el 403 servicio. Si es así, la propiedad code del tipo de recurso de error indica el tipo de límite superado por la solicitud. Los valores posibles para los tipos de límite son los siguientes:

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.