API Graph

Información general

La API Graph es la opción principal para obtener datos dentro y fuera de la plataforma de Facebook. Es una API basada en HTTP que las aplicaciones pueden utilizar para consultar datos mediante programación, publicar nuevas historias, administrar anuncios, subir fotos y realizar otras muchas tareas.

La API Graph lleva el nombre de una “gráfica social”, una representación de la información en Facebook. Está compuesta por nodos, perímetros y campos. Por lo general, los nodos se utilizan para obtener datos sobre un objeto específico, los perímetros para obtener colecciones de objetos en un objeto único y los campos para obtener datos sobre un objeto único o cada uno de los objetos de una colección. A lo largo de nuestra documentación, es posible que hagamos referencia a un nodo y un perímetro como "extremo". Por ejemplo, "envía una solicitud GET al extremo de usuario".

HTTP

Todas las transferencias de datos se ajustan al protocolo HTTP/1.1, y todos los extremos requieren 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 puedes utilizar la API Graph 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"

También hemos activado la directiva HSTS includeSubdomains en facebook.com, pero esto no debe afectar de manera adversa a tus llamadas a la API Graph.

Dirección URL del host

Casi todas las solicitudes se pasan a la URL del host graph.facebook.com. La única excepción son las subidas de vídeos, que utilizan graph-video.facebook.com.

Identificadores de acceso

Los identificadores de acceso permiten que tu aplicación acceda a la API Graph. Casi todos los extremos de la API Graph requieren un identificador de acceso de algún tipo, de manera que, cada vez que accedes a un extremo, la solicitud puede requerir uno. Normalmente, realizan dos funciones:

  • Permiten que la aplicación acceda a la información del usuario sin requerir su contraseña. Por ejemplo, la aplicación necesita un correo electrónico de usuario para realizar una función. Si el usuario acepta permitir que la aplicación recupere su dirección de correo electrónico de Facebook, no hará falta que escriba su contraseña de Facebook para que la aplicación obtenga su dirección de correo electrónico.
  • Nos permiten identificar la aplicación, el usuario que la usa y el tipo de datos al que ha permitido acceso a la aplicación dicho usuario.

Visita nuestra documentación sobre identificadores 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 nodos de usuario, cada uno de los cuales tiene 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 ejemplo de cURL siguiente representa una llamada al nodo de usuario.

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

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

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

Metadatos del nodo

Puedes obtener una lista de todos los campos, incluido el nombre, 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 especificado:

{
  "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 extremo especial que se traduce en el identificador del objeto de la persona o página cuyo identificador de acceso se usa actualmente para realizar llamadas a la API. Si tuvieras un identificador de acceso de usuario, podrías recuperar el identificador y el nombre de usuario mediante el código siguiente:

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, mientras que un nodo de foto puede tener comentarios conectados. En el ejemplo de cURL siguiente se devolverá una lista de fotos que ha publicado una persona en Facebook.

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

Cada identificador devuelto representa el nodo de una 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 del nodo. Cuando consultas un nodo o un perímetro, este devuelve un conjunto de campos de manera predeterminada, tal y como lo muestran los ejemplos anteriores. Sin embargo, para especificar los campos que quieres que se devuelvan, puedes usar el parámetro fields e indicarlos uno a uno. De este modo, se sustituyen los valores predeterminados y solo se devuelven los campos que especificas, además del identificador del objeto, que se devuelve siempre.

La solicitud de cURL siguiente incluye el parámetro fields y el nombre, el correo electrónico y la foto del 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 tipos de parámetros son elementos primitivos simples, como bool, string e int, pero también existen los 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 Uso compartido de Facebook para obtener información sobre cómo publicar contenido en el perfil de Facebook de un usuario, o bien nuestra documentación sobre la API de páginas para realizar publicaciones en la sección de noticias de Facebook de una página.

Algunos nodos te permiten actualizar campos con operaciones POST. Por ejemplo, puedes actualizar el campo email de la siguiente manera:

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

Leer después de escribir

Para crear y actualizar extremos, la API Graph puede leer inmediatamente un objeto publicado o actualizado de manera correcta y devolver los campos compatibles con el extremo de lectura correspondiente.

De manera predeterminada, se devolverá un identificador del objeto creado o actualizado. Para incluir más información en la respuesta, añade 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, puedes 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 ha aplicado formato al ejemplo de código anterior para mejorar su legibilidad.

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 extremo para ver si admite la operación de lectura después de la escritura y los campos que están disponibles.

Errores

Si se produce un error en la lectura por cualquier motivo (por ejemplo, al solicitar un campo que no existe), la API Graph responderá con una respuesta de error estándar. Visita nuestra guía Administración de errores para obtener más información.

Normalmente, puedes 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 hayas creado, pero comprueba la guía de referencia de cada nodo para ver los requisitos de las operaciones de eliminación.

Webhooks

Para recibir notificaciones de los cambios realizados en los nodos o las interacciones con los nodos, puedes suscribirte a los webhooks. Consulta Webhooks.

Versiones

La API Graph tiene varias versiones con lanzamientos trimestrales. Para especificar la versión en tus llamadas, añade "v" y el número de versión al inicio de la ruta de acceso de la solicitud. Por ejemplo, la siguiente 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"

Si no incluyes un número de versión, se definirá de forma predeterminada la versión disponible más antigua, por lo que es mejor incluir el número de versión en las solicitudes.

Puedes obtener más información sobre las versiones en nuestra guía Control de versiones, así como detalles acerca de todas las versiones disponibles en el Registro de cambios de la API Graph.

SDK, API y plataformas de Facebook

Conecta interfaces y desarrolla en varias plataformas mediante los distintos SDK, API y plataformas de Facebook.

Siguientes pasos

Introducción a la API Graph: exploremos la Gráfica social de Facebook con la herramienta Explorador de la API Graph y ejecutemos un par de solicitudes para obtener datos.