Compartir a través de

Trabajar con categorías de calificación

En este artículo se describe cómo usar la API de educación en Microsoft Graph para configurar y trabajar con categorías de calificación.

Los profesores usan categorías de calificación para aplicar pesos a las asignaciones de las calificaciones de los alumnos. Por ejemplo, los deberes pueden ser el 60 % de una calificación y las pruebas representan el 40 % de una calificación.

Las asignaciones contribuyen a una calificación en función de sus valores de punto y del peso asignado a la categoría de clasificación. Por ejemplo, en una clase con dos asignaciones en una categoría de calificación que representa el 50 % de la calificación, si la primera asignación tiene 10 puntos y la segunda tiene 40 puntos, las asignaciones contribuyen un 5 % y un 20 % a la calificación total.

Las categorías de calificación se definen en la configuración de una clase. Todas las asignaciones que contribuyen a la calificación media final deben tener aplicada una categoría de calificación. Los pesos de las categorías de calificación de una clase deben sumar hasta 100 durante las operaciones de creación, actualización o eliminación.

Para trabajar con categorías de calificación en la aplicación, debe obtener el identificador de la clase y la configuración de asignación de esa clase. En este artículo se describen los pasos para crear, agregar, actualizar y eliminar categorías de calificación definidas en la configuración de asignación.

Nota: La API de educación de Microsoft Graph solo admite permisos delegados (por usuario).

Obtener una clase

Una clase es un grupo de alumnos y profesores que comparten asignaciones y comentarios. Para trabajar con categorías de calificación, primero obtiene la lista de clases de su inquilino de educación y, a continuación, identifica la clase para la que desea establecer categorías de calificación en las asignaciones.

Para obtener una lista de las clases del inquilino, consulte Enumeración de clases.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/education/classes

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes",
    "@odata.nextLink": "https://graph.microsoft.com/beta/education/classes?$skiptoken=RFNwdAoAAQAAAAAAAAAAFAAAAFc2PSDBhntHjvzu16e1Nf8BAAAAAAAAAAAAAAAAAAAXMS4yLjg0MC4xMTM1NTYuMS40LjIzMzEGAAAAAAAB1vIxCWc1gUyNlbXz2-SlPQEBAQAAAQEAAAA",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET education/classes?$select=classCode,course",
    "value": [
        {
            "id": "602ac15e-695c-4095-9efc-8f5baa860e33",
            "description": "English 6",
            "displayName": "English 6",
            "mailNickname": "Section_1657",
            "externalSource": "sis",
            "externalSourceDetail": "SIS",
            "externalId": "1657",
            "externalName": "English 6",
            "classCode": "5",
            "course": {
                "courseNumber": "ENG100",
                "displayName": "English 6",
                "externalId": "111"
            },
            "term": {
                "displayName": "2014-2015",
                "endDate": "2015-05-23",
                "externalId": "1288",
                "startDate": "2014-05-26"
            }
        }
    ]
}

Obtener la configuración de asignación

Para agregar categorías de calificación, primero debe obtener la configuración de asignación de la clase e identificar qué categoría de calificación debe aplicarse para asignaciones específicas.

Para obtener la configuración de asignación de una clase, consulte Obtención de la configuración de asignación.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET education/classes('<guid>')/assignmentSettings?$select=submissionAnimationDisabled",
    "submissionAnimationDisabled": true,
    "gradingCategories@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/gradingCategories",
    "gradingCategories": [],
    "gradingSchemes@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/gradingSchemes",
    "gradingSchemes": [
        {
            "id": "69911dea-bc5c-406a-8743-81d06225a3a1",
            "displayName": "New GradingScheme name 01",
            "hidePointsDuringGrading": false,
            "grades": []
        },
        {
            "id": "696290ba-1925-490e-a5d2-026bad0dbdc1",
            "displayName": "New name for Pass/Fail Scheme",
            "hidePointsDuringGrading": false,
            "grades": [
                {
                    "displayName": "Pass",
                    "minPercentage": 60,
                    "defaultPercentage": 100
                },
                {
                    "displayName": "Fail",
                    "minPercentage": 0,
                    "defaultPercentage": 0
                }
            ]
        }
    ]
}

Create categorías de calificación

Las categorías de calificación se usan para ponderar las asignaciones en la calificación final de clase. En esta sección se muestra cómo crear categorías de calificación para la clase.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PATCH https://graph.microsoft.com/beta/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings
Content-type: application/json

{
  "gradingCategories": [
        {
            "displayName": "Lab",
            "percentageWeight": 10
        },
        {
            "displayName": "Homework",
            "percentageWeight": 80
        },
        {
            "displayName": "Test",
            "percentageWeight": 10
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/$entity",
  "submissionAnimationDisabled": false,
  "gradingCategories@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/gradingCategories",
  "gradingCategories": [
      {
          "id": "8bfb6d7f-8634-4f3b-9b6a-b6b6ff663f01",
          "displayName": "Lab",
          "percentageWeight": 10
      },
      {
          "id": "6fd19981-588f-495c-91a8-712a645c95b7",
          "displayName": "Homework",
          "percentageWeight": 80
      },
      {
          "id": "54f637a5-2cef-4e48-a88e-028854ca8089",
          "displayName": "Test",
          "percentageWeight": 10
      }
  ]
}

Adición de una categoría de calificación a una asignación

Para ponderar la contribución de una asignación a la calificación de clase final, se asigna a la asignación una categoría de calificación.

Para agregar una categoría de calificación a una asignación, vea Agregar gradingCategory.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PUT https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignments/28992cce-fac0-4950-a836-5a524ded8599/gradingCategory/$ref
Content-type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings/gradingCategories/905b49a5-1639-49ab-9fbe-6a035def5ba3"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Actualización de una categoría de calificación

Puede cambiar los detalles de una categoría de calificación, como su nombre para mostrar o su peso. También puede eliminar una categoría de calificación y reemplazar su contribución por una categoría de calificación existente o nueva. En esta sección se muestra cómo actualizar una o varias categorías de calificación.

Para actualizar una única categoría de granding, vea Update single gradingCategory.

Ejemplo 1: Actualización de una única categoría de calificación

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PATCH https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings/gradingCategories/a5ca6dda-f220-43ca-81e4-02396b99f398
Content-type: application/json

Request Body
{
    "displayName": "Test updated"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/gradingCategories/$entity",
    "id": "a5ca6dda-f220-43ca-81e4-02396b99f398",
    "displayName": "Test updated",
    "percentageWeight": 30
}

Ejemplo 2: Uso de una carga diferencial para crear, actualizar o eliminar categorías de calificación

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PATCH https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings
Content-type: application/json

Request Body
{
    "gradingCategories@delta": [
        {
            "id": "fb859cd3-943b-4cd6-9bbe-fe1c39eace0e",
            "displayName": "Changing this grading category's name"
        },
        {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#gradingCategories/$deletedEntity",
            "id": "e2a86277-24f9-4f29-8196-8c83fc69d00d",
            "reason": "Deleting this grading category"
        },
        {
            "displayName": "Adding a new grading category 01",
            "percentageWeight": 30
        },
        {
            "displayName": "Adding a new grading category 02",
            "percentageWeight": 10
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 200 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/$entity",
    "submissionAnimationDisabled": false,
    "gradingCategories@odata.context": "https://graph.microsoft.com/v1.0/$metadata#education/classes('37d99af7-cfc5-4e3b-8566-f7d40e4a2070')/assignmentSettings/gradingCategories",
    "gradingCategories": [
        {
            "id": "fb4a4009-3cc4-4dea-9991-e0a0763659e3",
            "displayName": "Homework",
            "percentageWeight": 30
        },
        {
            "id": "fb859cd3-943b-4cd6-9bbe-fe1c39eace0e",
            "displayName": "Changing this grading category's name",
            "percentageWeight": 30
        },
        {
            "id": "d47d7a3f-44a1-47e1-8aec-68b028f64b2e",
            "displayName": "Adding a new grading category 01",
            "percentageWeight": 30
        },
        {
            "id": "021db844-0f03-4483-929d-1c1dbfd4fcb4",
            "displayName": "Adding a new grading category 02",
            "percentageWeight": 10
        }
    ]
}

Eliminación de categorías de calificación

Puede eliminar una categoría de calificación cuando ya no la necesite para la asignación o si desea simplificar el proceso de evaluación. Al eliminar una categoría de calificación, se quita de la configuración de asignación y de la interfaz de calificación.

Para quitar una categoría de calificación de la configuración de asignación y la interfaz de calificación, vea Quitar gradingCategory.

Nota: Las asignaciones de la categoría de calificación eliminada conservan sus calificaciones, pero los profesores no pueden asignar la categoría de calificación eliminada a otras asignaciones.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PATCH https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings
Content-type: application/json

Request Body
{
    "gradingCategories@delta": [
        {
            "id": "fb859cd3-943b-4cd6-9bbe-fe1c39eace0e",
            "displayName": "Changing this grading category's name"
        },
        {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#gradingCategories/$deletedEntity",
            "id": "e2a86277-24f9-4f29-8196-8c83fc69d00d",
            "reason": "Deleting this grading category"
        },
        {
            "displayName": "Adding a new grading category 01",
            "percentageWeight": 30
        },
        {
            "displayName": "Adding a new grading category 02",
            "percentageWeight": 10
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Ejemplo de error: Eliminación de una categoría de clasificación mediante la carga diferencial

Al intentar eliminar una categoría de clasificación mediante la carga delta sin reemplazarla por otra categoría de calificación para mantener el total de todas las categorías en 100, la llamada produce un error, como se muestra en el ejemplo siguiente.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PATCH https://graph.microsoft.com/v1.0/education/classes/37d99af7-cfc5-4e3b-8566-f7d40e4a2070/assignmentSettings
Content-type: application/json

Request Body
{
    "gradingCategories@delta": [
        {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#gradingCategories/$deletedEntity",
            "id": "426f653d-c383-4758-8790-4a1fe53116b1",
            "reason": "Deleting this grading category"
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 400 Bad Request
Content-type: application/json
{
    "error": {
        "code": "badRequest",
        "message": "Bad request.",
        "innerError": {
            "code": "invalidRequestBody",
            "message": "GradingCategory weights must sum to 100.",
            "date": "2024-05-03T19:00:25",
            "request-id": "1d7a1230-f43e-4053-9313-f835d020772a",
            "client-request-id": "8248d438-b6b4-cee0-0121-a04cc08ba4d8"
        }
    }
}

Contenido relacionado

Use el Explorador de Graph para probar las API de educación.