Compartir a través de


site: delta

Obtenga sitios recién creados, actualizados o eliminados sin tener que realizar una lectura completa de toda la colección de sitios.

Una llamada de función delta para sitios es similar a una solicitud GET, salvo que al aplicar correctamente tokens de estado en una o varias de estas llamadas, puede consultar los cambios incrementales en los sitios. Permite mantener y sincronizar un almacén local de los sitios de un usuario sin tener que capturar todos los sitios del servidor cada vez. La aplicación llama a la API sin especificar ningún parámetro. El servicio comienza a enumerar sitios y devuelve páginas de cambios en estos sitios, acompañadas de un @odata.nextLink o un @odata.deltaLink. La aplicación debe seguir realizando llamadas mediante @odata.nextLink hasta que haya un @odata.deltaLink en la respuesta.

Después de recibir todos los cambios, puede aplicarlos a su estado local. Para supervisar los cambios futuros, llame a la API delta mediante @odata.deltaLink en la respuesta anterior.

Los recursos marcados como eliminados deben quitarse del estado local.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Sites.Read.All Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Sites.Read.All Sites.ReadWrite.All

Solicitud HTTP

GET /sites/delta

Parámetros de consulta

En la dirección URL de la solicitud, puede incluir el siguiente parámetro de consulta opcional.

Parámetro Tipo Descripción
token Cadena Si el valor es latest, la llamada devuelve una respuesta vacía con el token delta más reciente. Si el valor es un token delta anterior, la llamada devuelve el nuevo estado desde que se emitió ese token.

Este método también admite los $selectparámetros de consulta , $expandy $top OData para personalizar la respuesta.

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una colección de objetos de sitio en el cuerpo de la respuesta.

Además de la colección de objetos de sitio , la respuesta también incluye una de las siguientes propiedades.

Nombre Valor Descripción
@odata.nextLink URL Dirección URL para recuperar la siguiente página disponible de cambios si hay más cambios en el conjunto actual.
@odata.deltaLink URL Dirección URL devuelta en lugar de @odata.nextLink después de que se devuelvan todos los cambios actuales. Use esta propiedad para leer el siguiente conjunto de cambios en el futuro.

En algunos casos, el servicio devuelve un 410 Gone código de respuesta con una respuesta de error que contiene uno de los siguientes códigos de error y un Location encabezado que contiene un nuevo nextLink que inicia una enumeración delta nueva. Se produce cuando el servicio no puede proporcionar una lista de cambios para un token determinado; por ejemplo, si un cliente intenta reutilizar un token antiguo después de desconectarse durante mucho tiempo, o si el estado del servidor ha cambiado y se requiere un nuevo token.

Una vez completada la enumeración completa, compare los sitios devueltos con el estado local y siga las instrucciones en función del tipo de error.

Tipo de error Instrucciones
resyncChangesApplyDifferences Reemplace los sitios locales por las versiones del servidor (incluidas las eliminaciones) si está seguro de que el servicio estaba actualizado con los cambios locales cuando se sincronizó por última vez. Cargar cualquier cambio local que no conoce el servidor.
resyncChangesUploadDifferences Cargue los sitios locales que el servicio no devolviera y cargue los sitios que difieren de las versiones del servidor. Mantenga ambas copias si no está seguro de cuál está más actualizada.

Para obtener más información, consulte Respuestas de error y tipos de recursos de Microsoft Graph.

Ejemplos

Ejemplo 1: Solicitud inicial

En el ejemplo siguiente se muestra la solicitud inicial y cómo llamar a esta API para establecer el estado local.

Solicitud

En el ejemplo siguiente se muestra la solicitud inicial.

GET https://graph.microsoft.com/v1.0/sites/delta

Respuesta

En el ejemplo siguiente se muestra la respuesta que incluye la primera página de cambios y la propiedad @odata.nextLink que indica que no hay más sitios disponibles en el conjunto actual de sitios. La aplicación debe seguir solicitando el valor de dirección URL de @odata.nextLink hasta que se recuperen todas las páginas de los sitios.

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

{
  "value": [
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,712a596e-90a1-49e3-9b48-bfa80bee8740",
      "name": "teamSiteA"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteB"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteC"
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}

Ejemplo 2: Última solicitud de página

En el ejemplo siguiente se muestra una solicitud que accede a la última página de un conjunto y cómo llamar a esta API para actualizar el estado local.

Solicitud

En el ejemplo siguiente se muestra una solicitud después de la solicitud inicial.

GET https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka

Respuesta

En el ejemplo siguiente se muestra la respuesta que indica que el sitio denominado All Company se eliminó entre la solicitud inicial y esta solicitud para actualizar el estado local.

La página final de los sitios incluye la propiedad @odata.deltaLink que proporciona la dirección URL que se puede usar más adelante para recuperar los cambios desde el conjunto actual de sitios.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?$deltatoken=b2vm2fSuZ-V_1Gdq4ublGPD4lReifRNHYMGxkFf0yz2fTqr9U6jMyWv8hihThODJCO_5I7JbpAFLQAIOUzYXhCPl0jlQdjTC1o24iBe81xQyAWJOiP3q1xyMKjlfZUawWok3Njc_LIrrSgrdSydhsVCL6XYpRkYGJ9JDYxFMiJw2vUs1QC_S0cW6hqYQnOimeA918dQZwD8pJI9oUJryV2Ow-7Dj9p18p1I6pFg044k.xipVdgMKlOFIlXzPipsKzlFJbYUTD1sGiFiPe7uZA7Q",
    "value": [
        {
            "createdDateTime": "2024-03-11T02:36:04Z",
            "name": "All Company",
            "displayName": "All Company",
            "isPersonalSite": false,
            "id": "bd565af7-7963-4658-9a77-26e11ac73186",
            "root": {}
        }
    ]
}

En algunos escenarios, es posible que desee solicitar el valor actual deltaLink sin enumerar primero todos los sitios, listas y webs. Puede ser útil si la aplicación solo quiere saber sobre los cambios y no necesita saber sobre los sitios existentes. Para recuperar la versión más reciente deltaLink, llame a delta con el parámetro ?token=latestde cadena de consulta .

Nota: Si desea mantener una representación local completa de los recursos, debe usar delta para la enumeración inicial. Usar delta es la única manera de garantizar que ha leído todos los datos que necesita.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/sites/delta?token=latest

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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

{
  "value": [ ],
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}

Vea también