Resultados paginados

En la información general sobre la API Graph se exponen los conceptos básicos de su terminología y estructura. En este documento se presentan más detalladamente los resultados de las solicitudes de la API.

Desplazamiento por los resultados paginados

Al realizar una solicitud de API a un nodo o perímetro, normalmente no recibes todos los resultados de esa solicitud en una única respuesta. Esto se debe a que algunas respuestas pueden contener miles de objetos y, por ello, la mayoría se paginan de forma predeterminada.

Paginación basada en cursores

El método de paginación más eficiente es el basado en cursores y se debe usar siempre que sea posible. Un cursor hace referencia a una cadena de caracteres aleatoria que marca un elemento específico en una lista de datos. El cursor siempre apuntará al elemento, pero dejará de ser válido si dicho elemento se elimina. Por lo tanto, tu aplicación no debe almacenar cursores ni suponer que seguirán siendo válidos en el futuro.

Al leer un perímetro que admite la paginación basada en cursores, aparece la siguiente respuesta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Un perímetro paginado mediante cursores admite los siguientes parámetros:

before: cursor que apunta al inicio de la página de datos que se ha devuelto.
after: cursor que apunta al final de la página de datos que se ha devuelto.
limit: número máximo de objetos que se pueden devolver. Es posible que una consulta devuelva un número menor que el valor de limit debido a la filtración. No te guíes por el hecho de que el número de resultados sea menor al valor de limit para saber si la consulta ha llegado al final de la lista de datos. En su lugar, básate en la ausencia del parámetro next, como se explica más adelante. Por ejemplo, si estableces el valor de limit en diez y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que un elemento se haya eliminado debido a la filtración de privacidad. Por motivos de rendimiento, algunos perímetros pueden establecer un límite máximo en el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: extremo de API Graph que devolverá la siguiente página de datos. Si no se incluye, es la última página de datos. Debido a la forma en que funciona la paginación en cuanto a visibilidad y privacidad, es posible que una página esté vacía, pero incluya un enlace de paginación next. Debes dejar de paginar cuando ya no aparezca el enlace next.
previous: extremo de API Graph que devolverá la página de datos anterior. Si no se incluye, es la primera página de datos.

No almacenes cursores. Estos pueden dejar de ser válidos rápidamente si se añaden o eliminan elementos.

Paginación basada en el tiempo

La paginación basada en el tiempo se utiliza para navegar por los datos de resultados con marcas de tiempo Unix que apuntan a horas específicas en una lista de datos.

Al utilizar un extremo que utiliza la paginación basada en el tiempo, aparece la siguiente respuesta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

Un perímetro paginado en función del tiempo admite los siguientes parámetros:

until: marca de tiempo Unix o valor de datos strtotime que apunta al final del intervalo de datos basados en el tiempo.
since: marca de tiempo Unix o valor de datos strtotime que apunta al inicio del intervalo de datos basados en el tiempo.
limit: número máximo de objetos que se pueden devolver. Es posible que una consulta devuelva un número menor que el valor de limit debido a la filtración. No te guíes por el hecho de que el número de resultados sea menor al valor de limit para saber si la consulta ha llegado al final de la lista de datos. En su lugar, básate en la ausencia del parámetro next, como se explica más adelante. Por ejemplo, si estableces el valor de limit en diez y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que un elemento se haya eliminado debido a la filtración de privacidad. Por motivos de rendimiento, algunos perímetros pueden establecer un límite máximo en el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: extremo de API Graph que devolverá la siguiente página de datos.
previous: extremo de API Graph que devolverá la página de datos anterior.

Para obtener resultados coherentes, especifica los parámetros since y until. Además, se recomienda que la diferencia de tiempo sea de seis meses como máximo.

Paginación basada en desplazamientos

Puedes usar la paginación basada en desplazamientos cuando no te importe la cronología y solo quieras que se devuelva un número específico de objetos. Utiliza este tipo de paginación únicamente si el perímetro no admite la paginación basada en cursores o en el tiempo.

Un perímetro con paginación basada en desplazamientos admite los siguientes parámetros:

offset: desplaza el inicio de cada página según el número indicado.
limit: número máximo de objetos que se pueden devolver. Es posible que una consulta devuelva un número menor que el valor de limit debido a la filtración. No te guíes por el hecho de que el número de resultados sea menor al valor de limit para saber si la consulta ha llegado al final de la lista de datos. En su lugar, básate en la ausencia del parámetro next, como se explica más adelante. Por ejemplo, si estableces el valor de limit en diez y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que un elemento se haya eliminado debido a la filtración de privacidad. Por motivos de rendimiento, algunos perímetros pueden establecer un límite máximo en el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: extremo de API Graph que devolverá la siguiente página de datos. Si no se incluye, es la última página de datos. Debido a la forma en que funciona la paginación en cuanto a visibilidad y privacidad, es posible que una página esté vacía, pero incluya un enlace de paginación next. Debes dejar de paginar cuando ya no aparezca el enlace next.
previous: extremo de API Graph que devolverá la página de datos anterior. Si no se incluye, es la primera página de datos.

Ten en cuenta que, si se añaden nuevos objetos a la lista de elementos que se está paginando, el contenido de todas las páginas basadas en desplazamientos cambiará.

La paginación basada en desplazamientos no es compatible con todas las llamadas a la API. Para obtener resultados coherentes, te recomendamos que pagines mediante los enlaces "previous" o "next" que se devuelven en la respuesta.

En el caso de objetos para los que se devuelven muchos elementos, como los comentarios (que pueden totalizar decenas de miles), es posible que existan límites de paginación. La API devolverá un error cuando tu aplicación alcance el límite del cursor:

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

Siguientes pasos

Ahora que estás más familiarizado con la API Graph, consulta la Guía del explorador de la API Graph para explorar esta API sin escribir código, los Usos habituales para ver las tareas más comunes, y los SDK disponibles.