Resultados paginados

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

Recorrer resultados paginados

Cuando haces una solicitud de API a un nodo o perímetro, por lo general, no recibes todos los resultados de la solicitud en una sola respuesta. Esto se debe a que algunas respuestas contienen miles de objetos, por lo que la mayoría están paginadas de forma predeterminada.

Paginación basada en el cursor

El método de paginación basado en el cursor es el más eficiente 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 apunta al elemento, pero se invalida si dicho elemento se elimina. Por lo tanto, tu app no debe almacenar cursores ni suponer que seguirán siendo válidos en el futuro.

Al leer un perímetro que admita la paginación basada en el cursor, 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 con paginación basada en el cursor admite los siguientes parámetros:

before: este es el cursor que apunta al inicio de la página de datos que se devolvió.
after: este es el cursor que apunta al final de la página de datos que se devolvió.
limit: este es el 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 los filtros. Que el número de resultados sea menor que el número limit no indica necesariamente que tu consulta haya llegado al final de la lista de datos; básate en la ausencia del valor next, como se describe a continuación. 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 al filtro de privacidad. Por motivos de rendimiento, algunos perímetros imponen un máximo para el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: el punto de conexión de la API Graph que devolverá la siguiente página de datos. Si no se incluye, esta es la última página de datos. Debido a la forma en que funciona la paginación con visibilidad y privacidad, es posible que una página parezca vacía, pero incluya un enlace de paginación next. Debes dejar de paginar cuando el enlace next no aparezca más.
previous: el punto de conexión de la API Graph que devolverá la página de datos anterior. Si no se incluye, esta es la primera página de datos.

No almacenes los cursores. Los cursores pueden perder su validez muy rápidamente si se agregan 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 de UNIX que apuntan a horas específicas en una lista de datos.

Al utilizar un punto de conexión 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 por tiempo admite los siguientes parámetros:

until: una marca de tiempo de Unix o un valor de datos strtotime que apunta al final del intervalo de datos basados en el tiempo.
since: una marca de tiempo de Unix o un valor de datos de strtotime que apunta al inicio del intervalo de datos basados en el tiempo.
limit: este es el 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 los filtros. Que el número de resultados sea menor que el número limit no indica necesariamente que tu consulta haya llegado al final de la lista de datos. Básate en la ausencia de next, como se describe a continuación. 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 al filtro de privacidad. Por motivos de rendimiento, algunos perímetros imponen un máximo para el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: el punto de conexión de la API Graph que devolverá la siguiente página de datos.
previous: el punto de conexión de la API Graph que devolverá la página de datos anterior.

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

Paginación basada en intervalos

Puedes utilizar la paginación de intervalo cuando no te importe la cronología y solo quieras que se devuelva un número específico de objetos. Solo debe utilizarse si el perímetro no admite la paginación basada en el cursor o en el tiempo.

Un perímetro paginado de intervalo admite los siguientes parámetros:

offset: desplaza el inicio de cada página en el número especificado de elementos.
limit: este es el 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 los filtros. Que el número de resultados sea menor que el número limit no indica necesariamente que tu consulta haya llegado al final de la lista de datos; básate en la ausencia del valor next, como se describe a continuación. 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 al filtro de privacidad. Por motivos de rendimiento, algunos perímetros imponen un máximo para el valor de limit. En todos los casos, la API devuelve los enlaces de paginación correctos.
next: el punto de conexión de la API Graph que devolverá la siguiente página de datos. Si no se incluye, esta es la última página de datos. Debido a la forma en que funciona la paginación con visibilidad y privacidad, es posible que una página parezca vacía, pero incluya un enlace de paginación next. Debes dejar de paginar cuando el enlace next no aparezca más.
previous: el punto de conexión de la API Graph que devolverá la página de datos anterior. Si no se incluye, esta es la primera página de datos.

Ten en cuenta que, si se agregan nuevos objetos a la lista de elementos que se está paginando, el contenido de cada página basada en intervalo cambiará.

La paginación basada en intervalos no es compatible con las llamadas a la API. Para obtener resultados coherentes, te recomendamos paginar mediante los enlaces a elementos anteriores o siguientes que devolvemos en la respuesta.

En el caso de objetos para los que se devuelven muchos artículos, como los comentarios (que pueden totalizar decenas de miles), es posible que encuentres límites al realizar la paginación. La API devolverá un error cuando tu app haya alcanzado el límite del cursor:

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

Próximos pasos

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