API Graph

Solicitudes por lotes

Envía una sola solicitud HTTP que contenga varias llamadas a la API Graph de Facebook. Las operaciones independientes se procesan en paralelo, mientras que las dependientes lo hacen de forma secuencial. Una vez que se han completado todas las operaciones, 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 de la solicitud. Debes procesar las respuestas según corresponda para determinar qué operaciones han funcionado bien y cuáles tienen que volverse a intentar en una operación posterior.

Limitaciones

  • Las solicitudes por lotes están limitadas a 50 solicitudes por lote. Cada llamada de dentro del lote se cuenta por separado para calcular los límites de las llamadas a la API y los de los recursos. Por ejemplo, un lote de 10 llamadas a la API cuenta como 10 llamadas, y cada llamada de dentro del lote contribuye a los límites de recursos de la CPU de la misma forma. Consulta nuestra guía sobre la limitación de frecuencia para obtener más información.
  • Las solicitudes por lote no pueden incluir varios conjuntos de anuncios en la misma campaña. Más Información sobre las solicitudes por lotes a la API de marketing.

Solicitud por lotes

Una solicitud por lotes toma un objeto JSON que consiste en una matriz de tus solicitudes. Devuelve una matriz de respuestas HTTP lógicas que se representan como matrices JSON. Cada respuesta tiene un código de estado, una matriz de encabezados opcionales y un cuerpo opcional (que es una cadena JSON codificada).

Para realizar una solicitud por lotes, envía una solicitud POST a un extremo donde el parámetro batch sea tu objeto JSON.

POST /ENDPOINT?batch=[JSON-OBJECT]

Ejemplo de solicitud por lotes

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

Se ha aplicado formato para mejorar la legibilidad.
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 se han completado todas las operaciones, se envía una respuesta con el resultado de cada operación. Dado que los encabezados devueltos pueden ser mucho más grandes que la respuesta real de la API, es recomendable eliminarlos para mejorar la eficacia. Para incluir información del encabezado, elimina el parámetro include_headers o defínelo como true.

Ejemplo de respuesta

El campo del cuerpo contiene un objeto JSON codificado en una cadena:

[
  {
    "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

Existe la posibilidad de combinar operaciones que habitualmente usarían métodos HTTP diferentes en una única solicitud por lotes. Si bien las operaciones GET y DELETE solo pueden tener un campo relative_url y uno method, las operaciones POST y PUT pueden contener un campo body adicional. El cuerpo debe tener el formato de una cadena HTTP POST sin formato, similar a una cadena de consulta URL.

Ejemplo de solicitud

En el siguiente ejemplo se publica una publicación en una página que administramos y para la que tenemos permiso de publicación y, luego, las noticias de la página en una única 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"

La salida sería:

[
    { "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 anuncio para una campaña y, luego, se obtienen los detalles de un objeto creado recientemente. Fíjate en 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 añaden varias páginas a una cuenta de Business Manager:

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"

Donde:

  • <ACCESS_TOKEN> es un identificador de acceso con el permiso business_management.
  • <BUSINESS_ID> es el identificador de la cuenta de Business Manager para la que se deben solicitar las páginas.
  • <PAGE_ID_n> son los identificadores de las páginas que se van a solicitar.

Errores

Puede que una de las operaciones solicitadas devuelva un error. Podría ser debido, por ejemplo, a que no tienes permiso para realizar la operación solicitada. La respuesta es parecida a la de la API Graph estándar, pero está encapsulada en la sintaxis de respuesta del lote:

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

Las demás solicitudes del lote deberían completarse correctamente y devolver el código de estado normal 200, como siempre.

Tiempo de espera agotado

Puede que se agote el tiempo de espera de los lotes largos o complejos si se tarda demasiado en completar las solicitudes del lote. En dicha situación, el resultado es un lote completado parcialmente. En un lote completado parcialmente, las solicitudes que se completen correctamente devolverán la salida habitual con el código de estado 200. Las respuestas de las solicitudes que no funcionen correctamente serán null. Puedes volver a intentar cualquier solicitud incorrecta.

Llamadas por lotes con JSONP

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

Con varios identificadores de acceso

Las solicitudes individuales de una única solicitud por lotes pueden especificar sus propios identificadores de acceso como una cadena de consulta o un parámetro de publicación de formularios. En este caso, el identificador de acceso del nivel superior se considera un identificador de reserva y se utiliza si una solicitud individual no ha especificado ningún identificador de acceso explícitamente.

Puede resultar útil cuando quieres enviar una consulta a la API con varios identificadores de acceso de usuario o de página diferentes o si algunas de tus llamadas deben realizarse mediante un identificador de acceso a la aplicación.

Debes incluir un identificador de acceso como parámetro de nivel superior, incluso si todas las solicitudes individuales contienen sus propios identificadores.

Subir datos binarios

Puedes subir varios elementos binarios como parte de la llamada por lotes. Para hacerlo, necesitas añadir todos los elementos binarios como adjuntos de varias partes o mime a la solicitud y cada operación tiene que hacer referencia a sus elementos binarios con la propiedad attached_files en la operación. La propiedad attached_files admite listas separadas por comas de nombres de adjuntos en sus valores.

En el siguiente ejemplo se muestra cómo cargar 2 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
-->