Obtener los cambios incrementales de grupos

Consulta de delta permite consultar las adiciones, eliminaciones o actualizaciones a grupos, por medio de una serie de llamadas a función delta. La consulta de delta le permite descubrir cambios en grupos sin tener que acceder a todo el conjunto de grupos de Microsoft Graph para comparar los cambios.

Los clientes que utilizan grupos de sincronización con un almacén de perfil local pueden utilizar la consulta delta para su sincronización completa inicial y sus sincronizaciones incrementales futuras. Normalmente, el cliente debería realizar una sincronización completa inicial de todos los grupos de inquilino y, después, obtener los cambios incrementales en los grupos de forma periódica.

Seguimiento de los cambios de grupos

El seguimiento de los cambios de grupos normalmente es una ronda de una o varias solicitudes GET con la función delta. Realiza una solicitud GET de una forma muy similar a cómo lista grupos, excepto que incluye lo siguiente:

  • La función delta
  • Un token de estado (deltaToken o skipToken) de la anterior llamada a función delta GET.

Ejemplo

El ejemplo siguiente muestra una serie de solicitudes para seguir cambios en grupos:

  1. Solicitud inicial y respuesta
  2. Solicitud nextLink y respuesta
  3. Solicitud nextLink final y respuesta
  4. Solicitud de deltaLink y respuesta deltaLink

Solicitud inicial

Para comenzar los cambios de seguimiento en el recurso grupo, debe realizar una solicitud incluyendo la función delta en el recurso grupo.

Tenga en cuenta lo siguiente:

  • El parámetro de consulta $select opcional se incluye en la solicitud para demostrar cómo los parámetros de consulta se incluyen automáticamente en futuras solicitudes.
  • El parámetro de consulta$select opcional también se utiliza para mostrar cómo se pueden recuperar los miembros del grupo junto con los objetos del grupo. Esto permite realizar un seguimiento de los cambios de la suscripción, como cuando se agregan o se quitan de grupos de usuarios.
  • La solicitud inicial no incluye un token del estado. Los tokens de estado se utilizarán en solicitudes posteriores.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

Respuesta inicial

Si se ejecuta correctamente, este método devuelve el código de respuesta 200 OK y el objeto de colección grupo en el cuerpo de la respuesta. Si todo el conjunto de grupos es demasiado grande para que quepa en una respuesta, también se incluirá un nextLink que contiene un token de estado.

En este ejemplo, se incluyó un nextLink; los parámetros de consulta $select original que están codificados en el token de estado.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"TestGroup1",
      "description":"Employees in test group 1",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"TestGroup2",
      "description":"Employees in test group 2",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

Nota: la propiedad members@delta se incluye en el primer objeto de grupo, TestGroup1, y contiene los dos miembros actuales del grupo. TestGroup2 no contiene esta propiedad porque el grupo no tiene ningún miembro.

La segunda petición usa el nextLink de la respuesta anterior, que contiene el skipToken. Tenga en cuenta que los parámetros $select no están presentes explícitamente, ya que se codifican en el token.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ

La respuesta contiene otro nextLink con un nuevo valor de skipToken, que indica que hay más grupos disponibles. Debe seguir realizando solicitudes con la URL de nextLink hasta que se devuelva una dirección URL de deltaLink en la respuesta final, incluso si el valor es una matriz vacía (esto puede ocurrir en determinadas circunstancias).

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"TestGroup3",
      "description":"Employees in test group 3",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"TestGroup4",
      "description":"Employees in test group 4",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

La tercera solicitud vuelve a usar la última nextLink.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

Por último, se devuelve la dirección URL deltaLink, lo que significa que no hay ningún dato más para el estado de los grupos existente. Para las solicitudes futuras, la aplicación usa los valores deltaLink y deltaToken que contiene para obtener información sobre los cambios a los grupos.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"TestGroup5",
      "description":"Employees in test group 5",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"TestGroup6",
      "description":"Employees in test group 6",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

Con el deltaLink de la última respuesta, podrá obtener nuevos cambios a los grupos desde la última solicitud. Los cambios incluyen:

  • Nuevos objetos de grupo creados.
  • Objetos de grupo eliminados.
  • Agrupar objetos para los que se ha cambiado una propiedad (por ejemplo, se ha modificado displayName).
  • Agrupar objetos a los que se han agregado o quitado objetos de miembro.
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

Si no ha habido cambios, se devuelve un deltaLink sin resultados, la propiedad value está vacía. Asegúrese de que reemplaza el vínculo anterior en la aplicación con el nuevo para usar en futuras llamadas.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

Si se han producido cambios, se incluye una colección de grupos cambiados. La respuesta también contiene un nextLink, en caso de que haya varias páginas de cambios para recuperar, o un deltaLink. Debe implementar el mismo modelo de procedimientos siguiendo el nextLinks como antes y conservar el último deltaLink para llamadas futuras.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

Algunas cosas que debe tener en cuenta sobre la respuesta del ejemplo anterior:

  • Los objetos se devuelven con el mismo conjunto de propiedades especificadas originalmente a través de los $selectparámetros de consulta.

  • Se incluyen tanto las propiedades modificadas como las no modificadas. En el ejemplo anterior, la propiedad description tiene un nuevo valor, mientras que la propiedad displayName no ha cambiado.

  • members@delta contiene los cambios a la suscripción.

    • El primer usuario en la lista se quitó del grupo, quitando la pertenencia o eliminando el propio objeto de usuario. La propiedad @removed lo describe. Solo los usuarios que se han eliminado definitivamente se eliminan de los grupos. Los usuarios que se han eliminado de forma temporal mantienen la pertenencia a los grupos y no aparecerán en el resultado diferencial hasta que se eliminen definitivamente. Para obtener más información, vea directorio (elementos eliminados).

    • Se ha agregado al grupo el segundo usuario.

Navegar por los miembros en un grupo grande

La propiedad members@delta se incluye en los objetos de grupo de forma predeterminada, cuando no se ha especificado el parámetro de consulta $select, o cuando el parámetro $select=members se especifica explícitamente. Es posible que en los grupos con muchos miembros no quepan todos los miembros en una sola respuesta; en esta sección se explica el patrón que debe implementar para tratar estos casos.

Nota: este patrón se aplica tanto a la recuperación de estado de grupo inicial como a las llamadas posteriores para obtener los cambios delta.

Supongamos que ejecuta la siguiente consulta delta, ya sea para capturar el estado completo de los grupos inicial o más adelante para obtener cambios delta:

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members
  1. Microsoft Graph puede devolver una respuesta que contenga solo un objeto de grupo, con una gran lista de miembros de la propiedad members@delta:

Primera Página

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Cuando siga el nextLink, es posible que reciba una respuesta de nuevo con el mismo objeto de grupo. Los mismos valores se devolverán, pero la propiedad members@delta expandida ahora contiene una lista de usuarios diferente.

Segunda página

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Finalmente, se devolverá la lista completa de miembros de este modo y otros grupos empezarán a mostrarse en la respuesta.

Le recomendamos los siguientes procedimientos para administrar correctamente este patrón:

  • Siga siempre nextLink y combine de forma local cada estado de grupo: a medida que reciba respuestas relacionadas con el mismo grupo, puede usarlas para crear la lista de pertenencia completa en la aplicación.
  • Es mejor que no suponga una secuencia específica de las respuestas. Suponga que el mismo grupo podría mostrarse en cualquier lugar en la secuencia nextLink y téngalo en cuenta en la lógica de combinación.

Vea también

Información general sobre Consulta de delta de Microsoft Graph.