API Graph

Solicitudes por lotes

Envía una solicitud HTTP que contenga varias llamadas a la API Graph de Facebook. Las operaciones independientes se procesan en paralelo mientras tus operaciones dependientes se procesan consecutivamente. Una vez que todas las operaciones están completas, se te devuelve una respuesta consolidada y se cierra la conexión HTTP.

El orden de las respuestas se corresponde con el orden de las operaciones en la solicitud. Por ese motivo, deberías procesar las respuestas para determinar qué operaciones resultaron satisfactorias y cuáles deberían intentarse en las operaciones posteriores.

Limitaciones

Solicitudes por lotes

Una solicitud por lotes presenta un objeto JSON que consiste en una matriz de tus solicitudes. Devuelve una matriz de respuestas HTTP lógicas representadas como matrices JSON. Cada respuesta tiene un código de estado, una matriz de encabezados opcional y un cuerpo opcional (que es una cadena con codificación JSON).

Para realizar una solicitud por lotes, envía una solicitud POST a un punto de conexión punto de conexión en el que el parámetro batch sea tu objeto JSON.

POST /ENDPOINT?batch=[JSON-OBJECT]

Ejemplo de solicitud por lotes

En este ejemplo, obtenemos información de dos páginas que nuestra app administra.

El formato se modificó para facilitar la lectura.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

Una vez que todas las operaciones estén completas, se envía una respuesta con el resultado de cada operación. Dado que los encabezados devueltos a veces pueden ser más grandes que la respuesta de la API real, tal vez prefieras eliminarlos a fin de mejorar la eficacia. Para incluir información de encabezado, elimina el parámetro include_headers o configúralo como true.

Ejemplo de respuesta

El campo del cuerpo contiene un objeto JSON de cadena codificada:

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Solicitudes por lotes complejas

Es posible combinar operaciones que normalmente utilizarían distintos métodos HTTP en una sola solicitud por lotes. Mientras que las operaciones GET y DELETE solo pueden tener una dirección relative_url y un campo method, las operaciones POST y PUT pueden tener un campo body opcional. El cuerpo debe tener el formato de una cadena POST HTTP sin procesar, similar a una cadena de consulta URL.

Ejemplo de solicitud

En el siguiente ejemplo, se muestra una publicación en una página que administramos y en la que tenemos permisos de publicación, y después las noticias de la página en una sola operación:

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

El resultado de esta llamada es:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

En el siguiente ejemplo, se crea un nuevo anuncio para una campaña y después se obtienen detalles del objeto recién creado. Ten en cuenta la operación URLEncoding para el parámetro del cuerpo:

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

En el siguiente ejemplo, se agregan varias páginas a un administrador comercial:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Dónde:

  • <ACCESS_TOKEN> es un token de acceso con el permiso business_management.
  • <BUSINESS_ID> es el identificador del administrador comercial al cual deben solicitarse las páginas.
  • <PAGE_ID_n> son los identificadores de la página que se debe solicitar.

Errores

Es posible que una de tus operaciones solicitadas genere un error. Esto podría deberse a que, por ejemplo, no tienes permiso para realizar la operación solicitada. La respuesta es similar a la API Graph estándar, pero encapsulada en la sintaxis de respuesta por lotes:

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

Las restantes solicitudes del lote deberían seguir correctamente de todas formas y se devolverán, como siempre, con un código de estado 200.

Tiempos de espera

El tiempo de espera de los lotes grandes o complejos se puede agotar si todas las solicitudes dentro del lote tardan mucho en completarse. En tal circunstancia, el resultado es un lote parcialmente completado. En un lote parcialmente completado, las solicitudes que se completan de forma satisfactoria devolverán el resultado normal con el código de estado 200. Las respuestas a las solicitudes que no sean satisfactorias serán null. Puedes volver a intentar realizar cualquier solicitud que no haya sido satisfactoria.

Llamadas por lotes con JSONP

La API por lotes admite JSONP, al igual que el resto de la API Graph (la función de devolución de llamada de JSONP se especifica con el parámetro de publicación de formulario o cadena de consulta callback).

Uso de varios tokens de acceso

Las solicitudes individuales de una misma solicitud por lotes pueden especificar sus propios tokens de acceso como cadena de consulta o formar parámetros de publicación. En ese caso, el token de acceso de nivel superior se considera un token de reserva y se utiliza si una solicitud individual no especificó explícitamente un token de acceso.

Esto puede resultar útil cuando quieres consultar la API con distintos tokens de acceso de usuario o tokens de acceso a la página, o si es necesario realizar algunas de las llamadas con un token de acceso de app.

Debes incluir un token de acceso como parámetro de nivel superior, aun cuando todas las solicitudes individuales contengan sus propios tokens.

Subir datos binarios

Puedes subir varios elementos binarios como parte de una llamada por lotes. Para ello, necesitas agregar todos los elementos binarios como archivos adjuntos MIME o de varias partes a tu solicitud y necesitas que cada operación haga referencia a sus elementos binarios con la propiedad attached_files en la operación. La propiedad attached_files admite una lista separada por comas de nombres de archivos adjuntos en su valor.

En el siguiente ejemplo, se muestra cómo subir dos fotos en una sola llamada por lotes:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->