site: delta

  • Artículo

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Obtenga un conjunto de 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.

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 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 otros 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. Puede usar 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 con un nuevo nextLink que inicia una enumeración delta nueva. Este error 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.

Después de completar la enumeración completa, puede comparar los sitios devueltos con el estado local y seguir 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.

Además de los errores de resincronización y para obtener más información, consulte Respuestas de errores 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.

GET https://graph.microsoft.com/beta/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/beta/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 la solicitud.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta que indica que el sitio denominado AllCompany 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/beta/$metadata#sites",
    "@odata.deltaLink": "https://graph.microsoft.com/beta/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. Esta sugerencia 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: Para 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/beta/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/beta/sites/delta?token=1230919asd190410jlka"
}

Vea también