Uso de la API Graph

En la información general sobre la API Graph tratamos los aspectos básicos relacionados con la terminología y la estructura de esta interfaz. En este documento se explican las diferentes operaciones que puedes realizar con la API Graph.

HTTP/1.1

Todas las transferencias de datos se ajustan al protocolo HTTP/1.1 y todos los extremos requieren el protocolo HTTPS. También hemos habilitado la directiva HSTS includeSubdomains en facebook.com, pero no debería afectar de forma negativa a las llamadas que realices a la API Graph.

URL del host

Casi todas las solicitudes se pasan a la URL graph.facebook.com del host. A excepción de las cargas de vídeos, en las que se usa graph-video.facebook.com.

Identificadores de acceso

Tu aplicación puede acceder a la API Graph gracias a los identificadores de acceso. Estos realizan normalmente dos funciones:

  • Permiten que tu aplicación acceda a la información del usuario sin necesidad de usar su contraseña.
  • Nos permiten identificar tu aplicación, saber qué usuario la está utilizando y conocer a qué tipo de información tiene acceso esta persona.

Todos los extremos de la API Graph requieren un identificador de acceso de algún tipo, por lo que cada vez que accedas a un extremo deberás incluir uno en la solicitud.

Funcionamiento de los identificadores

Los identificadores de acceso siguen el protocolo OAuth 2.0, que permite a entidades como un usuario o una página autorizar estos identificadores. Normalmente, este proceso se lleva a cabo a través de una interfaz web y, una vez autorizados, las aplicaciones pueden usarlos para acceder a información específica.

Por ejemplo, esta aplicación está solicitando a un usuario que le conceda permiso para acceder a sus fotos, sus vídeos y su dirección de correo electrónico:

Como puedes ver, se trata de una interfaz de Facebook, y el usuario acaba de usarla para entrar en su cuenta, lo que nos ha permitido autenticarlo. Si el usuario procede, cambiaremos el antiguo identificador (un identificador de la aplicación) por uno nuevo (un identificador de usuario). Así, la aplicación podrá usar el nuevo identificador para realizar solicitudes a la API Graph, pero solo tendrá acceso a las fotos, los vídeos y la dirección de correo electrónico del usuario en cuestión.

Esta es una de las principales funciones de los identificadores de acceso. La aplicación y los identificadores de usuario están codificados en el propio identificador (junto con otras cosas) y usamos estos identificadores para hacer un seguimiento de los datos para los que el usuario concede permiso de acceso a la aplicación. Por ejemplo, si compruebas el identificador después de que el usuario haya concedido el permiso, verás la siguiente información:

Estos identificadores son extremadamente valiosos porque permiten acceder a la información del usuario, pero cualquier persona puede usarlos, por lo que te recomendamos que tomes precauciones a la hora de incluirlos en tus consultas. La manera más sencilla es administrarlos mediante el inicio de sesión con Facebook.

Inicio de sesión con Facebook

El protocolo OAuth 2.0 se compone de una gran variedad de redireccionamientos, solicitudes de inicio de sesión e intercambio de identificadores. Para facilitarte su uso, hemos creado el producto Inicio de sesión con Facebook. Este producto cuenta con funciones y métodos fáciles de usar y aplicables a todos nuestros SDK, gracias a los cuales te resultará más sencillo trabajar con identificadores de acceso que desarrollar tu propia solución.

Consulta la documentación del inicio de sesión con Facebook para obtener más información sobre los identificadores de acceso o para saber cómo desarrollar tu propia solución.

Leer

Nodos

Las operaciones de lectura casi siempre comienzan con un nodo. Un nodo no es más que un objeto individual con un identificador único. Por ejemplo, existen muchos objetos de nodo “Page”, cada uno con su propio identificador (por ejemplo, la página de Coca-Cola es la única con el identificador 820882001277849). Para leer un nodo, las consultas deben realizarse con el identificador de un objeto determinado. Por tanto, si quisieras leer el nodo de la página Coca-Cola, deberías realizar la consulta usando su identificador:

GET https://graph.facebook.com/820882001277849

De forma predeterminada, esta solicitud devolvería los siguientes campos (las propiedades del nodo) en formato JSON:

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

Perímetros

Los nodos tienen perímetros, que normalmente devuelven colecciones de otros nodos que se encuentran conectados a ellos. Para leer un perímetro, debes incluir tanto su nombre como el identificador del nodo en la ruta. Por ejemplo, los nodos /page tienen un perímetro /feed que puede devolver todos los nodos “Post” de una página. A continuación te mostramos cómo podrías usar este perímetro para obtener todas las publicaciones de la página de Coca-Cola:

GET https://graph.facebook.com/820882001277849/feed

La respuesta JSON sería similar a esta:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

Ten en cuenta que en la respuesta se incluyen los identificadores de los nodos “Post” de la colección y también los campos created_time y message. Esto es normal, ya que la mayoría de los perímetros contienen uno o más campos de forma predeterminada.

Campos

Los campos son las propiedades del nodo. Al realizar una consulta a un nodo, este devuelve un conjunto de campos de forma predeterminada, tal y como se muestra en los ejemplos anteriores. No obstante, puedes especificar los campos que quieres obtener usando el parámetro fields e incluyéndolos. De esta manera, se remplazarán los valores predeterminados y se devolverán solo aquellos campos que hayas especificado, así como el identificador del objeto (que siempre se devuelve).

Por ejemplo, en la referencia del nodo “Page” se indican los campos que puedes solicitar para su lectura. Si quisieras obtener los campos about, fan_count y website de la página de Coca-Cola, podrías realizar la siguiente operación:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

Se devolvería esta respuesta:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

Los perímetros, que normalmente devuelven colecciones de objetos, también pueden devolver campos relativos a todos los objetos de la colección. Supongamos que has obtenido todos los nodos “Photo” de la página de Coca-Cola mediante el perímetro /photos:

GET https://graph.facebook.com/820882001277849/photos

Se generaría una respuesta similar a esta:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

Como puedes ver, el perímetro /photos devuelve, de forma predeterminada, una colección de identificadores correspondientes al nodo “Photo” y la propiedad created_time de cada foto. Puedes usar el parámetro fields de la misma manera que los nodos para especificar los campos que quieres que se devuelvan de cada objeto de la colección.

Supongamos que quieres obtener los campos height, width y link (URL) de los nodos “Photo” que devuelve el perímetro /photos:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

La respuesta tendría este aspecto:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

Ten en cuenta que también puedes especificar un perímetro mediante el parámetro fields, que resulta muy útil si usas la expansión de campos.

Expansión de campos

Si has probado la solicitud GET /page/photos mencionada con anterioridad en el explorador de la API Graph, probablemente habrás observado que devuelve más de tres objetos y pagina los resultados. Esto es algo habitual en la mayoría de los perímetros. En breve trataremos el desplazamiento por los resultados, pero de momento nos centraremos en la expansión de campos. Con esta función, aparte de realizar solicitudes anidadas, puedes limitar y ordenar los resultados.

Limitar los resultados

La limitación de resultados te permite controlar el número de objetos que se devuelven en cada conjunto de resultados paginados. Si quieres aplicar esta medida, debes añadir el argumento .limit() a cualquier campo o perímetro.

Por ejemplo, si realizas una solicitud GET al perímetro /feed de la página de Coca-Cola, se devolverán cientos de publicaciones. En este caso, puedes limitar el número de publicaciones que se devuelven en cada página de resultados realizando la siguiente operación:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

Esto devuelve todas las publicaciones de dicha página, pero se limita a tres el número de objetos que aparecen en cada página de resultados. Ten en cuenta que, para poder añadir el argumento .limit(3), en lugar de especificar el perímetro “Feed” en la URL (/page/feed), debes especificarlo en el parámetro fields (?fields=feed).

Estos son los resultados de la consulta:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

Como puedes observar, solo aparecen tres objetos en esta página de resultados. Sin embargo, en la respuesta se incluye un campo next y una URL que puedes usar para recuperar la siguiente página.

Ordenar los resultados

Existe la posibilidad de ordenar los resultados según la hora de creación de los objetos. Para hacerlo, usa un argumento .order() e incluye uno de los siguientes valores en un campo o un perímetro.

  • chronological: ordena los resultados empezando por el objeto más antiguo.
  • reverse_chronological: ordena los resultados empezando por el objeto más reciente.

A continuación te mostramos cómo obtener los comentarios de una publicación con vídeo de la página de Cola-Cola (1809938745705498), ordenar los resultados cronológicamente (empezando por el más antiguo) y limitar a tres los objetos que aparecerán en cada página de resultados:

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

De nuevo, recuerda que, para poder usar un argumento en un perímetro, debes especificar dicho perímetro en el parámetro fields. Como puedes observar, existe la posibilidad de combinar los argumentos .limit() y .order() en un único campo o perímetro.

Estos son los resultados:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

Publicar

Con la mayoría de los perímetros puedes publicar objetos en una colección o en un nodo. Puedes hacerlo mediante una solicitud POST en el perímetro del nodo. Por ejemplo, puedes publicar un comentario en una foto usando el perímetro /comments del nodo “Photo”:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

Si se realiza correctamente, la mayoría de los perímetros devuelven el identificador del objeto que acabas de publicar, que a menudo es una combinación del identificador en el que se ha publicado dicho objeto y una nueva cadena de identificador.

{
  "id": "1809938745705498_1810399758992730"
}

La publicación de objetos suele requerir permisos adicionales, por lo que te recomendamos que consultes la documentación de referencia de cada perímetro para determinar los que necesitas.

La apariencia del objeto puede verse afectada por el identificador de acceso que se ha empleado para publicarlo. Si se usa uno de acceso a la página, parecerá que esta ha publicado el objeto, mientras que si se usa uno de usuario, parecerá que lo ha publicado una persona.

Muchos perímetros también admiten funciones avanzadas, como la lectura después de escritura, con la que puedes leer de inmediato un objeto recién publicado, y la publicación por lotes, que permite encadenar varias operaciones de publicación.

Actualizar

Existe la posibilidad de realizar actualizaciones en un nodo existente mediante solicitudes POST. Por ejemplo, para actualizar el campo message de un comentario existente, puedes hacer lo siguiente:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

Si la operación se realiza correctamente, el nodo devolverá un campo success y el valor true.

{
  "success": true
}

Como sucede con las operaciones de publicación, las de actualización requieren permisos adicionales, que encontrarás en la documentación de referencia de cada nodo. Además, como la mayoría de los perímetros, muchos nodos admiten la lectura después de escritura.

Eliminar

Por lo general, es posible eliminar un nodo mediante una operación DELETE:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

Si la operación se realiza correctamente, el nodo devolverá un campo success y el valor true.

{
  "success": true
}

Normalmente puedes eliminar los nodos que has creado, pero es recomendable consultar la guía de referencia de cada uno para conocer los requisitos para eliminarlos.

Para ofrecer compatibilidad a los clientes que no admiten todos los métodos HTTP, puedes enviar una solicitud POST al nodo e incluir el parámetro method=delete y su valor para remplazar el método HTTP:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

Desplazarse por resultados paginados

Cuando realizas una solicitud de API para un nodo o perímetro, normalmente no recibes todos los resultados de la solicitud en una sola respuesta. Esto se debe a que algunas respuestas podrían contener miles de objetos y, por ello, la mayoría de las respuestas se paginan de forma predeterminada.

Paginación basada en cursores

El método de paginación basada en cursores es el más eficiente y debería utilizarse en todos los casos posibles. Un cursor se refiere a una cadena de caracteres aleatoria que marca un elemento específico en una lista de datos. A menos que se elimine este elemento, el cursor siempre apuntará a la misma parte de la lista, pero dejará de ser válido si se elimina el elemento. Por lo tanto, tu aplicación no debería almacenar cursores y presuponer que seguirán siendo válidos en el futuro.

Cuando leas un perímetro que admita la paginación basada en cursores, aparecerá la siguiente respuesta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/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 pueden devolverse. Debido a posibles filtros, una consulta puede devolver un número de objetos menor al máximo indicado en limit. 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 objetos y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que se haya eliminado un elemento debido a un filtro de privacidad. Algunos perímetros también pueden aplicar un límite máximo al valor de limit por motivos de rendimiento. En todos los casos la API devuelve los enlaces de paginación correctos.
  • next: extremo de API Graph que devolverá la página de datos siguiente. Si no se incluye, la página de datos actual será la última. Debido al funcionamiento de la paginación en cuanto a visibilidad y privacidad, es posible que haya una página vacía con un enlace de paginación "next". Deja 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, la página de datos actual será la primera.

No almacenes cursores. Los cursores pueden dejar de ser válidos rápidamente al añadirse o eliminarse elementos.

Paginación basada en tiempo

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

Cuando utilices un extremo con paginación basada en tiempo, aparecerá la siguiente respuesta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/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 tiempo.
  • since: marca de tiempo UNIX o valor de datos strtotime que apunta al inicio del intervalo de datos basados en tiempo.
  • limit: número máximo de objetos que pueden devolverse. Debido a posibles filtros, una consulta puede devolver un número de objetos menor al máximo indicado en limit. 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 objetos y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que se haya eliminado un elemento debido a un filtro de privacidad. Algunos perímetros también pueden aplicar un límite máximo al valor de limit por motivos de rendimiento. En todos los casos la API devuelve los enlaces de paginación correctos.
  • next: extremo de API Graph que devolverá la página de datos siguiente.
  • previous: extremo de API Graph que devolverá la página de datos anterior.

Para obtener resultados coherentes, especifica los parámetros since y until. Se recomienda que el período de tiempo no supere los seis meses.

Paginación basada en desplazamientos

Utiliza la paginación basada en desplazamientos si no te importa la cronología y solo esperas que se devuelva un número concreto de objetos. Este tipo de paginación debe utilizarse únicamente si el perímetro no admite la paginación basada en cursores ni en tiempo.

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

  • offset: desplaza el inicio de cada página según el número especificado.
  • limit: número máximo de objetos que pueden devolverse. Debido a posibles filtros, una consulta puede devolver un número de objetos menor al máximo indicado en limit. 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 objetos y se devuelven nueve resultados, es posible que haya más datos disponibles, pero que se haya eliminado un elemento debido a un filtro de privacidad. Algunos perímetros también pueden aplicar un límite máximo al valor de limit por motivos de rendimiento. En todos los casos la API devuelve los enlaces de paginación correctos.
  • next: extremo de API Graph que devolverá la página de datos siguiente. Si no se incluye, la página de datos actual será la última. Debido al funcionamiento de la paginación en cuanto a visibilidad y privacidad, es posible que haya una página vacía con un enlace de paginación "next". Deja 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, la página de datos actual será la primera.

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

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

Para objetos con un gran número de artículos devueltos, como [comments](/docs/graph-api/reference/object/comments), que se pueden contar por decenas de miles, es posible que existan límites de paginación. La API devolverá un error cuando la 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
  }
}