API Graph

Información general

La API Graph es la principal forma de ingresar datos en la plataforma de Facebook y extraerlos de esta. Se trata de una API basada en HTTP que las apps pueden usar de manera programática para consultar datos, publicar nuevas historias, administrar anuncios, subir fotos y llevar a cabo una gran variedad de tareas.

El nombre de la Graph API proviene del concepto de "gráfica social", una representación de la información en Facebook. Se compone de nodos, perímetros y campos. Normalmente, los nodos se usan para obtener datos sobre un objeto específico; los perímetros, para obtener colecciones de objetos a partir de un objeto único; y los campos, para obtener datos sobre un objeto único o todos los objetos en una colección. Es posible que en este documento nos refiramos a los nodos y a los perímetros como "puntos de conexión". Por ejemplo, "enviar una solicitud GET al punto de conexión 'Usuario'".

HTTP

Todas las transferencias de datos cumplen con el protocolo HTTP/1.1 y los puntos de conexión deben usar HTTPS. Dado que la API Graph se basa en HTTP, funciona con cualquier lenguaje que tenga una biblioteca HTTP, como cURL y urllib. Esto significa que la API Graph se puede usar directamente en el navegador. Por ejemplo, solicitar esta URL en el navegador…

https://graph.facebook.com/facebook/picture?redirect=false

... equivale a realizar esta solicitud cURL:

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

Además, activamos la directiva HSTS includeSubdomains en facebook.com, aunque esto no debería perjudicar las llamadas a la API Graph.

URL del host

Casi todas las solicitudes se pasan a la URL del host graph.facebook.com. Salvo en el caso de las subidas de videos, que usan graph-video.facebook.com.

Tokens de acceso

Los tokens de acceso permiten que la app acceda a la API Graph. Casi todos los puntos de conexión de la API Graph requieren algún tipo de token de acceso, por lo que todas las solicitudes de acceso pueden requerir uno. Normalmente, realizan dos funciones:

  • Permiten que la app acceda a la información de un usuario sin necesidad de proporcionar su contraseña. Por ejemplo, la app requiere que el correo electrónico de un usuario realice una función. Si el usuario acepta que la app recupere su dirección de correo electrónico de Facebook, no tendrá que introducir su contraseña de Facebook para que lo haga.
  • Nos permiten identificar la app, el usuario que la utiliza y los tipos de datos a los que este le permitió acceder.

Consulta nuestra documentación del token de acceso para obtener más información.

Nodos

Un nodo es un objeto individual con un identificador único. Por ejemplo, existen muchos objetos de nodo Usuario, cada uno con un identificador único que representa a una persona en Facebook. Las páginas, los grupos, las publicaciones, las fotos y los comentarios son solo algunos de los nodos de la gráfica social de Facebook.

El siguiente ejemplo de cURL representa una llamada al nodo Usuario.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Esta solicitud devolvería los siguientes datos de manera predeterminada, con un formato JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Metadatos del nodo

Se puede obtener una lista de todos los campos, incluidos el nombre del campo, la descripción y el tipo de datos, de un objeto de nodo, como un Usuario, una Página o una Foto. Envía una solicitud GET a un identificador de objeto e incluye el parámetro metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

La respuesta JSON resultante incluirá la propiedad metadata que enumera todos los campos admitidos para el nodo dado:

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

El nodo /me es un punto de conexión especial que se traduce en el identificador del objeto de la persona o la página cuyo token de acceso se está usando actualmente para realizar las llamadas a la API. Si tuvieras un token de acceso de usuario, podrías recuperar el nombre y el identificador de un usuario a mediante el uso de:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Perímetros

Un perímetro es una conexión entre dos nodos. Por ejemplo, un nodo de Usuario puede tener fotos conectadas a él, y un nodo de Foto puede tener comentarios conectados a él. El siguiente ejemplo de cURL devolverá una lista de fotos que una persona publicó en Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Cada identificador devuelto representa un nodo Foto y cuándo se subió a Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Campos

Los campos son propiedades de nodos. Al consultar un nodo, o un perímetro, este devuelve un conjunto de campos de manera predeterminada, como muestran los ejemplos anteriores. Sin embargo, puedes especificar los campos que quieres que se devuelvan usando el parámetro fields y enumerando cada uno. Esto anula los campos predeterminados y devuelve solo los que especifiques, así como el identificador del objeto, que se devuelve siempre.

La siguiente solicitud cURL incluye el parámetro fields y el nombre, el correo electrónico y la foto de perfil del Usuario.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Datos devueltos

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Parámetros complejos

La mayoría de los tipos de parámetros son directamente primitivos como bool, string y int, pero también hay tipos list y object que se pueden especificar en la solicitud.

El tipo list se especifica en sintaxis JSON, por ejemplo: ["firstitem", "seconditem", "thirditem"]

El tipo object también se especifica en sintaxis JSON, por ejemplo: {"firstkey": "firstvalue", "secondKey": 123}

Publicación, actualización y eliminación

Visita nuestra Guía para compartir en Facebook si quieres saber cómo publicar en el Facebook de un usuario o nuestra Documentación sobre la API de Páginas para publicar en el feed de Facebook de una página.

En algunos nodos, se pueden actualizar los campos con operaciones POST. Por ejemplo, podrías actualizar tu campo email de la siguiente manera:

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Lectura después de escritura

Para crear y actualizar puntos de conexión, la API Graph puede leer de inmediato un objeto correctamente publicado o actualizado y devolver los campos compatibles con el correspondiente punto de conexión de lectura.

De manera predeterminada, se devolverá un identificador del objeto que se creó o se actualizó. Para incluir más información en la respuesta, incluye el parámetro fields en tu solicitud y enumera los campos que quieres que se devuelvan. Por ejemplo, para publicar el mensaje "Hola" en la sección de noticias de una página, se puede hacer la siguiente solicitud:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
Se modificó el formato del ejemplo anterior de código para facilitar su lectura.

Esto devolvería los campos especificados como una respuesta con formato JSON de la siguiente manera:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

Consulta la documentación de referencia de cada punto de conexión para comprobar que sea compatible con la lectura después de escritura y cuáles campos están disponibles.

Errores

Si la lectura falla por algún motivo (por ejemplo, al solicitar un campo inexistente), la API Graph dará una respuesta de error estándar. Consulta nuestra Guía de manejo de errores para obtener más información.

Generalmente, se puede eliminar un nodo, como un nodo de Publicación o de Foto, mediante una operación “DELETE” en el identificador del objeto:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

Por lo general, solo puedes eliminar los nodos que creaste, pero consulta la guía de referencia de cada uno para conocer los requisitos de las operaciones de eliminación.

Webhooks

Puedes recibir notificaciones de los cambios en los nodos o en las interacciones con los nodos. Para ello, debes suscribirte a los webhooks. Consulta Webhooks.

Versiones

La API Graph tiene múltiples versiones con actualizaciones trimestrales. Se puede especificar la versión en las llamadas si se agrega "v" y el número de la versión al principio de la ruta de la solicitud. Por ejemplo, esta es una llamada a la versión 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Es mejor que incluyas el número de la versión en las solicitudes, ya que, de lo contrario, usaremos de manera predeterminada la versión más antigua que esté disponible.

Puedes obtener más información sobre las versiones en nuestra Guía de versiones e informarte sobre todas las versiones disponibles en el registro de cambios de la API Graph.

API, SDK y plataformas de Facebook

Conecta interfaces y desarrolla en diferentes plataformas usando API, SDK y plataformas de Facebook.

Próximos pasos

Primeros pasos con la API Graph: exploremos la gráfica social de Facebook usando la herramienta de exploración de la API Graph y ejecutemos algunas solicitudes para obtener datos.