Obtener los cambios incrementales de gruposGet incremental changes for groups

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.Delta query lets you query for additions, deletions, or updates to groups, by way of a series of delta function calls. Delta query enables you discover changes to groups without having to fetch the entire set of groups from Microsoft Graph and compare changes.

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.Clients using synchronizing groups with a local profile store can use Delta Query for both their initial full synchronization along with incremental synchronizations in the future. Typically, a client would do an initial full synchronization of all the groups in a tenant, and subsequently, get incremental changes to groups periodically.

Seguimiento de los cambios de gruposTracking group changes

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:Tracking group changes is a round of one or more GET requests with the delta function. You make a GET request much like the way you list groups, except that you include the following:

  • La función deltaThe delta function.
  • Un token de estado (deltaToken o skipToken) de la anterior llamada a función delta GET.A state token (deltaToken or skipToken) from the previous GET delta function call.

EjemploExample

El ejemplo siguiente muestra una serie de solicitudes para seguir cambios en grupos:The following example shows a series requests to track changes to groups:

  1. Solicitud inicial y respuestaInitial request and response
  2. Solicitud nextLink y respuestanextLink request and response
  3. Solicitud nextLink final y respuestaFinal nextLink request and response
  4. Solicitud de deltaLink y respuesta deltaLinkdeltaLink request and deltaLink response

Solicitud inicialInitial request

Para comenzar los cambios de seguimiento en el recurso grupo, debe realizar una solicitud incluyendo la función delta en el recurso grupo.To begin tracking changes in the group resource, you make a request including the delta function on the group resource.

Tenga en cuenta lo siguiente:Note the following:

  • 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.The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests.
  • 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.The optional $select query parameter is also used to show how group members can be retrieved together with group objects. Esto permite realizar un seguimiento de los cambios de la suscripción, como cuando se agregan o se quitan de grupos de usuarios.This allows tracking of membership changes, such as when users are added or removed from groups.
  • La solicitud inicial no incluye un token del estado. Los tokens de estado se utilizarán en solicitudes posteriores.The initial request does not include a state token. State tokens will be used in subsequent requests.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

Respuesta inicialInitial response

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.If successful, this method returns 200 OK response code and group collection object in the response body. 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.If the entire set of groups is too large to fit in one response, a nextLink containing a state token will also be included.

En este ejemplo, se incluyó un nextLink; los parámetros de consulta $select original que están codificados en el token de estado.In this example, a nextLink was included; the original $select query parameter is encoded in the state token.

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.Note: The members@delta property is included in the first group object - TestGroup1 - and contains the two current members of the group. TestGroup2 no contiene esta propiedad porque el grupo no tiene ningún miembro.TestGroup2 does not contain that property because the group does not have any members.

La segunda petición usa el nextLink de la respuesta anterior, que contiene el skipToken.The second request uses the nextLink from the previous response, which contains the skipToken. Tenga en cuenta que los parámetros $select no están presentes explícitamente, ya que se codifican en el token.Notice the $select parameter is not explicitly present as it is encoded in the 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.The response contains another nextLink with a new skipToken value, which indicates that more groups are available. 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).You should continue making requests using the nextLink URL until a deltaLink URL is returned in the final response, even if the value is an empty array (this can happen under certain circumstances).

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.The third request again uses the latest 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.Finally, the deltaLink URL is returned, which means there is no more data for the existing state of groups. 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.For future requests, the application uses the deltaLink and the deltaToken value it contains to learn about new changes to groups.

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.Using the deltaLink from the last response, you will be able to get net new changes to groups since the last request. Los cambios incluyen:Changes include:

  • Nuevos objetos de grupo creados.Newly created group objects.
  • Objetos de grupo eliminados.Deleted group objects.
  • Agrupar objetos para los que se ha cambiado una propiedad (por ejemplo, se ha modificado displayName).Group objects for which a property has changed (e.g. displayName has been modified).
  • Agrupar objetos a los que se han agregado o quitado objetos de miembro.Group objects for which member objects have been added or removed.
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.If no changes have occurred, a deltaLink is returned with no results - the value property is empty. Asegúrese de que reemplaza el vínculo anterior en la aplicación con el nuevo para usar en futuras llamadas.Make sure to replace the previous link in the application with the new one for use in future calls.

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.If changes have occurred, a collection of changed groups is included. La respuesta también contiene un nextLink, en caso de que haya varias páginas de cambios para recuperar, o un deltaLink.The response also contains either a nextLink - in case there are multiple pages of changes to retrieve - or a deltaLink. Debe implementar el mismo modelo de procedimientos siguiendo el nextLinks como antes y conservar el último deltaLink para llamadas futuras.You should implement the same pattern of following the nextLinks as before and persist the final deltaLink for future calls.

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:Some things to note about the example response above:

  • Los objetos se devuelven con el mismo conjunto de propiedades especificadas originalmente a través de los $selectparámetros de consulta.The objects are returned with the same set of properties originally specified via the $select query parameter.

  • Se incluyen propiedades cambiadas y sin cambios.Both changed and unchanged properties are included. En el ejemplo anterior, la propiedad description tiene un nuevo valor, mientras que la propiedad displayName no ha cambiado.In the example above, the description property has a new value, while the displayName property has not changed.

  • members@delta contiene los cambios a la suscripción.members@delta contains any changes to membership.

    • El primer usuario en la lista se quitó del grupo, quitando la pertenencia o eliminando el propio objeto de usuario.The first user in the list has been removed from the group - either by removing the membership or by deleting the user object itself. La propiedad @removed lo describe.The @removed property describes that. Solo los usuarios que se han eliminado definitivamente se eliminan de los grupos.Only users that have been permanently deleted are removed from groups. 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.Users that have been temporary deleted keep their group memberships and will not appear in the delta result until they are permanently deleted. Para obtener más información, vea directorio (elementos eliminados).For details, see directory (deleted items).

    • Se ha agregado al grupo el segundo usuario.The second user has been added to the group.

Navegar por los miembros en un grupo grandePaging through members in a large group

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.The members@delta property is included in group objects by default, when the $select query parameter has not been specified, or when the $select=members parameter is explicitly specified. 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.For groups with many members it is possible that all members cannot fit into a single response; in this section we describe the pattern you should implement to handle such cases.

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.Note: This pattern applies to both the initial retrieval of group state as well as to subsequent calls to get delta changes.

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:Let's assume you are executing the following delta query - either to capture the initial full state of groups, or later on to get delta changes:

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:Microsoft Graph may return a response that contains just one group object, with a large list of members in the members@delta property:

Primera PáginaFirst page

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.When you follow the nextLink you may receive a response again containing the same group object. Los mismos valores se devolverán, pero la propiedad members@delta expandida ahora contiene una lista de usuarios diferente.The same property values will be returned but the members@delta property now contains a different list of users.

Segunda páginaSecond page

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.Eventually, the entire member list will be returned in this fashion, and other groups will start showing up in the response.

Le recomendamos los siguientes procedimientos para administrar correctamente este patrón:We recommend the following best practices to correctly handle this pattern:

  • 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.Always follow nextLink and locally merge each group's state: as you receive responses related to the same group, use them to build the full membership list in your application.
  • Es mejor que no suponga una secuencia específica de las respuestas.It is best not to assume a specific sequence of the responses. 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.Assume that the same group could show up anywhere in the nextLink sequence and handle that in your merge logic.

Vea tambiénSee also

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