Solicitud y respuesta GetListItemChangesSinceToken

Artículo
09/24/2014

Última modificación: lunes, 01 de noviembre de 2010

Hace referencia a: SharePoint Foundation 2010

La forma más eficaz de sincronizar los clientes de otros fabricantes con Microsoft SharePoint Foundation 2010 es descargar solo los elementos que han cambiado desde que se ha producido la última sincronización. Puede hacerlo en SharePoint Foundation 2010 mediante una llamada al método web GetListItemChangesSinceToken.

GetListItem devuelve todos los elementos de una lista. GetListItem no incluye ningún método para obtener sólo aquellos elementos que han cambiado. Consulte Cómo: devolver elementos de la lista para ver un ejemplo sobre cómo devolver los elementos de una lista.

El método GetListItemChangesSinceToken permite a los clientes realizar un seguimiento de los cambios en una lista. Los cambios, incluidos los elementos eliminados, se devuelven junto con un token que representa el momento en el tiempo cuando se solicitaron los cambios. Al incluir este token cuando se llama a GetListItemChangesSinceToken, el servidor busca sólo los cambios que se han producido desde que el token se ha generado. Si se envía una solicitud GetListItemChangesSinceToken sin incluir un token se devuelve el esquema de lista, el contenido completo de la lista y un token.

Nota

Si el propio esquema de lista cambió, GetListItemChangesSinceToken devuelve el esquema de toda la lista, el contenido completo de la lista y un token.

Objetos de solicitud y respuesta

Los objetos de solicitud y respuesta representan información procedente del explorador en el servidor web y e información dirigida desde el servidor al explorador. El objeto de solicitud se denomina el objeto de entrada y el objeto de respuesta se denomina el objeto de salida .

Objetos de solicitud

GetListItemChangesSinceToken toma los parámetros siguientes:

Tabla 1: parámetros de solicitud

Elemento	Descripción
changeToken	Token que se utiliza para descubrir cambios que se hayan producido desde la última llamada. Este token nunca se debe analizar ni construir, ya que su formato puede cambiar en el futuro.
contains	Filtro CAML que se aplica a los resultados de la consulta. Se trata de la cláusula "Where" en un T:Microsoft.SharePoint.SPQuery. Nota No debe utilizarse con el elemento query.
listName	Cadena que contiene el nombre para mostrar de la lista o el identificador de lista (ID), que se expresa como un GUID. Para obtener un mejor rendimiento, se recomienda que utilice el GUID, que debe ir entre llaves ({}).
query	Elemento de consulta que contiene la consulta que determina qué registros se devuelven y en qué orden. Se trata de una consulta de lenguaje de marcado de la aplicación de colaboración (CAML) similar a la consulta CAML usada en GetListItems y SPQuery. Vea GetListItems y SPQuery en el SDK de SharePoint Foundation para obtener más información. Nota Su uso no está previsto con el parámetro contains.
queryOptions	Un fragmento de XML que contiene los nodos independientes de las diversas propiedades del objeto T:Microsoft.SharePoint.SPQuery.
rowLimit	Una cadena que especifica el número de elementos o filas que se van a mostrar en una página. El valor de este parámetro invalida el límite de fila establecido en la vista y especificado por el parámetro viewName, o el límite de fila establecido en la vista predeterminada de la lista. rowLimit es el número máximo de valores que se devolverá. Esta etiqueta se usa para la paginación.
viewFields	Especifica qué campos devuelve la consulta y en qué orden. <ViewFields /> devuelve todos los campos de la lista. Un atributo Properties=TRUE separa el campo MetaInfo en sus propiedades independientes y descodificadas.
viewName	Una cadena que contiene el GUID de la vista, que determina la vista predeterminada para los atributos representados por los parámetros query, viewFields y rowLimit. Si no se proporciona este argumento, se supone que es la vista predeterminada. Si se proporciona, el valor del parámetro query, viewFields o del parámetro rowLimit invalida la configuración equivalente en la vista. Por ejemplo, si la vista especificada por el parámetro viewFields tiene un límite de 100 filas pero el parámetro rowLimit contiene 1.000, entonces se devuelven 1.000 filas en la respuesta.

Parámetro de opciones de consulta

El elemento queryOptions puede contener una gran variedad de etiquetas que modifican la consulta. Para las opciones booleanas el valor predeterminado es FALSE. Especifique un valor de TRUE (con todas las letras en mayúscula) para habilitar una opción Boolean.

En la tabla siguiente se muestran los elementos que se pueden utilizar en el fragmento del Lenguaje de marcado de la aplicación de colaboración (CAML) transferido al parámetro queryOptions.

Tabla 2: etiquetas de opciones de consultas disponibles

Elemento	Descripción
< DateInUtc>	Los campos de fecha se devuelven en formato y zona de Hora universal coordinada (UTC). UTC es el nombre reconocido internacionalmente para la hora media de Greenwich (GMT) y se expresa en un formato especificado por la Organización internacional de normalización (ISO), específicamente ISO6801, de este modo: 2006-10-04T10:00:00Z El formato estándar se expresa en la zona horaria local (servidor), como se muestra anteriormente, pero con la T y la Z reemplazadas por espacios.
<ExpandUserField>	La representación especial de los valores de campo de usuario que incluye el nombre de inicio de sesión, de correo electrónico, SipAddress y el título, cuando están presentes. Esto hace que un campo de usuario se comporte como un campo de consulta múltiple. Los campos de búsqueda utilizados en la expansión son "Name", "EMail", "SipAddress" y "Title". Los valores se separan mediante, #. Las comas en el nombre del campo de búsqueda se codifican como,,. Los siguientes valores se producen en los datos del campo normal para cada elemento. <ExpandUserField>FALSE</ExpandUserField> tiene el siguiente formato: ows_Author="1;#Admin AdminName" y <ExpandUserField>TRUE</ExpandUserField> Tiene el siguiente formato: ows_Author="1;#Admin AdminName,#login\name,#email@address,#sip@address,#Admin AdminName "
<ExtraIds>1,4,23</ExtraIds>	Se utiliza para incluir elementos adicionales en el conjunto devuelto, independientemente de si han cambiado o no. ExtraIds normalmente se utiliza para especificar los identificadores de las carpetas que esté sincronizando cuando se encuentra en una biblioteca de documentos, elige "Conectar con…" y a continuación selecciona una carpeta determinada. En lugar de devolver toda la biblioteca de documentos, obtendrá el nombre de la carpeta específica. El cliente puede detectar el momento en que cualquier carpeta en la jerarquía se ha eliminado o cuyo nombre se ha cambiado. Los nombres de las carpetas no se devuelven a menos que hayan realizado cambios en la lista y la consulta para recuperar los elementos modificados también utilice los identificadores.
<Folder>	Establece el ámbito de la carpeta raíz de la vista. Se trata de una dirección URL relativa a servidor. <Folder>Shared Documents/foldername</Folder>
<IncludeAttachmentUrls>	Cambia el valor devuelto para el campo Datos adjuntos desde un valor booleano a una lista de direcciones URL completas, separadas por ;#
<IncludeAttachmentVersion>	Esta etiqueta se utiliza junto con IncludeAttachmentUrls, devuelve el número de GUID y versión utilizados para la detección de conflictos cuando se comprueba una actualización.
<IncludeMandatoryColumns>	Garantiza que los campos definidos como necesarios se incluyen, incluso si no se especifica en viewFields. Esta opción puede resultar algo confusa porque SharePoint Foundation realmente tiene un conjunto independiente de campos obligatorios que siempre se devuelven independientemente de esta opción.
<IncludePermissions>	Un método que un cliente puede utilizar para solicitar permisos de elementos individuales. TRUE para solicitar permisos de elementos individuales.
<MeetingInstanceId>	Un valor entero donde un número positivo representa una instancia de la reunión específica. Los números negativos tienen los siguientes significados:-3 = UnSpecified, -2 = AllWithSeries, -1 = AllButSeries, 0 = Series. Este elemento es opcional y su valor predeterminado es -1. Los valores negativos corresponden a valores de la enumeración Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance .
<OptimizeFor>	Los valores admitidos son: ItemIds FolderUrls ItemIds es el valor predeterminado siempre y cuando no se solicite una orden de consulta o de repetición. Esta etiqueta optimiza la consulta de SQL Server con una orden de identificador. FolderUrls optimiza una sincronización que tiene un filtro para el contenido sin formato de una o más carpetas, al optimizar la consulta de SQL Server con una orden DirName, LeafName. <OptimizeFor>ItemIds</OptimizeFor>
<Paging ListItemCollectionPositionNext="X" />	X es un token que se utiliza para determinar la página de elementos que se deben devolver. Al igual que el valor changeToken, este token no debe nunca analizarse ni construirse.
<RecurrenceOrderBy>	Se trata de un requisito para algunos programas de calendario. Para cada serie periódica, se devuelve el elemento principal primero y, a continuación, todas las excepciones. Éste es un orden interno especial que se aplica antes que cualquier otro orden. Si la vista tiene un campo de tipo Recurrence, la lista se ordena por los campos de identificadores únicos de tipo de referencia (UID) e incluye EventType y StartDate en la definición del campo de periodicidad.
<RecurrencePatternXMLVersion>	Se usa para mantener la compatibilidad con versiones anteriores. RecurrencePatternXMLVersion cambia el valor de un campo RecurrenceData para que no devuelva <V3RecurrencePattern /> La inclusión de esta etiqueta significa que los patrones de periodicidad nuevos para SharePoint Foundation se envían correctamente.
<ViewAttributes >	Devuelve una cadena que representa todos los atributos devueltos como parte del elemento View al recuperar una vista a través del método GetView. Este elemento es opcional y su valor predeterminado está vacío. Para devolver todos los documentos en una biblioteca, el elemento ViewAttributes se usa como se indica a continuación: <ViewAttributes Scope="Recursive" />.

Opciones de consulta predeterminada

Si el elemento queryOptions no se especifica, se utilizan las siguientes opciones predeterminadas.

DateInUtc = TRUE
ExpandUserField = TRUE
IncludePermissions = TRUE
IncludeAttachmentUrls = TRUE
IncludeAttachmentVersion = TRUE
MeetingInstanceID = -1
RecurrenceOrderBy = TRUE
RecurrencePatternXMLVersion = v3
ViewAttributes Scope = 'Recursive'

Nota

Los clientes siempre deben especificar una opción de consulta; de lo contrario quedará afectado negativamente el rendimiento de escala.

Objetos de respuesta

Una respuesta GetListItemChangesSinceToken se envía en formato XML en el formulario que se muestra a continuación. Este fragmento contiene todos los cambios y puede asignarse a un objeto System.Xml.Node.

<listitems xmlns:s="uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882" 
   xmlns:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" 
   xmlns:rs="urn:schemas-microsoft-com:rowset" xmlns:z="#RowsetSchema" 
   xmlns="https://schemas.microsoft.com/sharepoint/soap/">
   <rs:data ItemCount="4">
      <z:row ows_Number_Field="6555.00000000000" 
         ows_Created="2003-06-18T03:41:09Z" 
         ows_ID="3" ows_owshiddenversion="3" />
      <z:row ows_Number_Field="78905456.0000000" 
         ows_Created="2003-06-18T17:15:58Z" 
         ows_ID="4" ows_owshiddenversion="2" />
         ...
   </rs:data>
</listitems>

Propiedades globales y de lista

La siguiente tabla describe los parámetros de devolución.

Tabla 3: parámetros de devolución

Parámetro	Definición
AlternateUrls	Las direcciones URL alternativas se muestran en el siguiente orden de zona, delimitado por comas: Intranet,Predeterminada,Extranet,Internet,Personalizada,
EffectiveBasePermissions	Los permisos en la lista devueltos por la propiedad SPList.EffectiveBasePermissions.ToString().
MaxBulkDocumentSyncSize	Tamaño total de contenido, en megabytes (MB), que debe estar sincronizado con el cliente. El valor predeterminado es de 500 MB. La dirección URL y los metadatos para cada documento se obtienen cuando se llama a GetListItemChangesSinceToken, pero entonces debe hacer un HTTP GET para recuperar el contenido real del documento.
MinTimeBetweenSyncs	Un parámetro de servidor que representa la cantidad mínima de tiempo entre la sincronización iniciada por el usuario o la automática. El valor representa un tiempo en minutos. Nota Los clientes utilizar este valor incluso si el usuario inicia una sincronización manual. Es decir, si este valor se establece en 5 minutos, los clientes envían sólo una solicitud cada 5 minutos, incluso si el usuario hace clic varias veces en "Envío y recepción".
RecommendedTimeBetweenSyncs	Tiempo mínimo recomendado entre sincronizaciones. No invalida las sincronizaciones automáticas. Los clientes no deben nunca sincronizar automáticamente con más frecuencia que la recomendada.

Eventos de cambio

Los cambios constan de una lista de eventos de cambio que debe ser controlada específicamente por el cliente.

Estos eventos de cambio se toman del registro de cambios interno cuando se suministra un token de cambio. En una sincronización completa (sin token de cambio) también se devuelve la etiqueta de cambios con el token de cambio actual.

El límite en el número de actualizaciones devuelto desde un token de cambio es 100. El atributo MoreChanges indica que el token de cambio último no es actual. Se han realizado cambios adicionales a la lista y el cliente ahora debe llamar a este método de nuevo con el token de cambio nuevo.

Tabla 4: eventos de cambio

Eventos de cambio	Descripción
<Id ChangeType="InvalidToken" />	El token no es válido o es antiguo. Debe realizar una sincronización completa.
<Id ChangeType="Restore" />	Se ha restaurado la lista desde la Papelera de reciclaje o desde una copia de seguridad. Debe realizar una sincronización completa.
<List></List>	Si el esquema de lista ha cambiado, o si no se ha proporcionado un token de cambio, se devuelve la lista completa. El formato es el mismo que el devuelto por GetList.

En los dos primeros casos anteriores, el cliente debe omitir otros cambios y hacer una conciliación completa de la lista.

Tabla 5: tipos de cambio

Tipo de cambio	Descripción
<Id ChangeType="Delete">ID</Id>	Este elemento ya no está presente. Observe que los cambios de tipo delete se envían incluso si la consulta filtra el elemento.
<Id ChangeType="MoveAway" AfterListId="ID" AfterItemId="ID">ID</Id>	Estos elementos se tratan de la misma manera que un elemento de cambio de tipo eliminación, lo que significa que se devuelven incluso si la consulta ha filtrado el elemento.
<Id ChangeType="Restore">ID</Id>	Este elemento y cualquier elemento situado debajo de él han sido restaurados.
<Id ChangeType="SystemUpdate">ID</Id>	Algunos clientes pueden utilizar la versión oculta, el historial de versiones o la fecha de modificación para determinar si se debe actualizar un elemento. Una SystemUpdate significa que Windows SharePoint Services 3.0 ha realizado cambios y que tiene que actualizar todas las propiedades de ese elemento en concreto.
<Id ChangeType="Rename">ID</Id>	Los elementos cuyo nombre ha cambiado, como SystemUpdate, pueden conservar la información de versión oculta.

Datos

El atributo ItemCount contiene el número de elementos devueltos. Cada elemento se devuelve como una etiqueta <z:row> .

Un atributo ListItemCollectionPositionNext se devuelve para una sincronización completa (sin token de cambio) sólo cuando se ha utilizado un parámetro rowLimit para limitar el número de elementos devueltos en una llamada. Este tipo de paginación se bloquea en una sincronización incremental al restringir el número de actualizaciones que se procesan desde el registro de cambios al límite de filas, si este número es menor que el límite máximo interno.

El contenido de los elementos se devuelve como atributos con un prefijo "ows_" y el nombre interno del campo. Los valores se codifican como valores de atributo XML válidos. Siempre se devuelve un conjunto de campos.

Algunos campos se marcan como obligatorios y se devuelven si se establece la opción IncludeMandatoryColumns . Si se envía <ViewFields /> se devuelven todos los campos.

Cuando se establece Properties=" TRUE" en la etiqueta ViewFields, el contenedor de propiedades (campo MetaInfo) se divide en un atributo por cada propiedad. Estos atributos tienen el prefijo "ows_MetaInfo_" .

La mayoría de los valores de columna simplemente se convierten a partir de su representación interna, mientras otros se crean específicamente para un cliente. Muchos atributos del esquema de lista no están representados por un campo.

Tabla 6: atributos que no están representados por un campo en la lista de esquema

Atributo	Descripción
MetaInfo	Contenedor de propiedades, SPListItem.Properties. Para obtener más información, consulte el contenedor de propiedades en el modelo de objetos SPListItem.
Campos del tipo de datos adjuntos ("Attachments")	Columna de bits en la base de datos que puede modificarse mediante opciones de consulta para devolver información de datos adjuntos.
RecurrenceData	La definición XML de una repetición. Consulte los detalles de este esquema de XML en https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx.

MetaInfo

Contenedor de propiedades, SPListItem.Properties. Para obtener más información, consulte el contenedor de propiedades en el modelo de objetos SPListItem.

Campos del tipo de datos adjuntos ("Attachments")

Columna de bits en la base de datos que puede modificarse mediante opciones de consulta para devolver información de datos adjuntos.

RecurrenceData

La definición XML de una repetición.

Consulte los detalles de este esquema de XML en https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx.

Vea también

Conceptos

GetListItemChangesSinceToken y sincronización de aplicaciones

Procedimiento para actualizar elementos de listas

Compartir a través de