Solicitudes asíncronas y por lotes

Utiliza las solicitudes asíncronas para crear anuncios y enviar múltiples solicitudes de anuncios sin necesidad de bloquear. Especifica una URL a la que llamar cuando las solicitudes se completen o comprueba el estado de la solicitud. Consulta Anuncio, Referencia.

La forma más eficiente de administrar los anuncios consiste en usar las solicitudes por lotes. Utilízalas para realizar algunas de las solicitudes más habituales.

Solicitudes asíncronas

Por ejemplo, obtén el estado del conjunto de solicitudes asíncronas:

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_SET_ID>

Se devuelve el estado general del conjunto de solicitudes asíncronas como un objeto JSON. No aparecen todos los campos de forma predeterminada. Si quieres que la consulta incluya los campos que no son predeterminados, especifícalos en fields, como fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Una vez que obtienes el estado general del conjunto de solicitudes asíncronas, obtén los detalles de cada solicitud:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_SET_ID>/requests   

Se devuelven el estado y los detalles de cada solicitud del conjunto de solicitudes asíncronas. En el caso de la creación de anuncios asíncrona, realiza una solicitud para crear un anuncio. El parámetro de estado se usa para filtrar las solicitudes por su propio estado y puede ser cualquier combinación de los siguientes valores:

• initial: todavía no se ha procesado.
• in_progress: la solicitud se está procesando.
• success: la solicitud ha finalizado y se ha realizado correctamente.
• error: la solicitud ha finalizado y no se ha realizado correctamente.
• canceled: el usuario ha cancelado la solicitud.

La respuesta es una matriz JSON con campos predeterminados. Para incluir los campos que no son predeterminados, especifícalos en fields, como fields=id,scope_object_id,status,result,input,async_request_set.

Obtener los detalles de una solicitud

Para obtener los detalles de una solicitud asíncrona concreta, realiza esta llamada:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_SET_ID>/requests   

Se devuelve un objeto JSON con los campos indicados anteriormente.

Enumerar los conjuntos de solicitudes de una cuenta

Puedes crear varios conjuntos de solicitudes de anuncios asíncronas. Para consultar todos los conjuntos de solicitudes de anuncios asíncronas de una cuenta publicitaria:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Se devuelve una matriz JSON de objetos de conjuntos de solicitudes asíncronas. Los objetos son los mismos que los que se indican en la sección sobre conjuntos de solicitudes asíncronas. Puedes filtrar los resultados con is_completed. Si is_completed=true, solo ves el conjunto de solicitudes asíncronas completadas.

Enumerar las solicitudes de un conjunto de anuncios

Puedes realizar una llamada asíncrona para crear anuncios en diferentes conjuntos de anuncios. Para obtener el estado de cada conjunto de anuncios, obtén todas las solicitudes de creación de anuncios de un conjunto de anuncios:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<AD_SET_ID>/asyncadrequests

Se devuelve una matriz JSON de objetos de solicitudes asíncronas. Los campos de estado, filtro de campos y solicitud asíncrona son los mismos que los de la API https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests.

Actualizar los conjuntos de solicitudes

Puedes cambiar los valores de name, notification_uri y notification_mode de un conjunto de solicitudes asíncronas.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_SET_ID>

Si la actualización se completa correctamente, se devuelve true. Solo puedes cambiar los valores de notification_uri y notification_mode antes de enviar la notificación.

Cancelar una solicitud

Puedes cancelar una solicitud asíncrona, pero solo si todavía no se ha procesado.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_ID>

Si la cancelación se completa correctamente, se devuelve true. También puedes cancelar las solicitudes sin procesar del conjunto de solicitudes asíncronas:

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/<REQUEST_SET_ID>

Si la cancelación se completa correctamente, se devuelve true.

Ejemplos de solicitudes asíncronas

Obtener el estado de una solicitud asíncrona determinada:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v20.0/"

Valores devueltos:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Obtener los resultados de las solicitudes:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v20.0/requests"

Devuelve:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Obtener la lista de conjuntos de solicitudes de una cuenta publicitaria:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v20.0/act_71597454/asyncadrequestsets"

Devuelve:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Obtener una lista de las solicitudes de una campaña:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v20.0/6008248529789/asyncadrequests"
    

Valores devueltos:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Solicitudes por lotes

Con las solicitudes por lotes, combinas diversas llamadas a la API Graph en una solicitud HTTP. La API de marketing divide esta solicitud en las solicitudes que la forman. Esto hace que las solicitudes por lotes sean la forma más eficiente de interactuar con la API de marketing. Si quieres que la eficiencia sea todavía mayor, puedes realizar solicitudes por lotes en paralelo con subprocesos de procesamiento independientes.

Las solicitudes por lotes de anuncios, contenido de anuncios y conjuntos de anuncios son muy similares, por lo que no se abordan de forma independiente. Para obtener más información, consulta Solicitudes por lotes de la API Graph e ETags.

Crear anuncios

Puedes proporcionar el contenido del anuncio y otros objetos de anuncios en una solicitud por lotes. Por ejemplo, puedes crear tres anuncios con un contenido de anuncio y tres especificaciones de segmentación diferentes. Define primero el contenido del anuncio y, a continuación, haz referencia a él al crear cada anuncio:

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

La respuesta incluye códigos de respuesta individuales para cada solicitud y la respuesta estándar de la API Graph. Para obtener más información, consulta Realizar varias solicitudes a la API.

El proceso de las solicitudes por lotes usa el formato de expresión JSONPath para hacer referencia a las solicitudes anteriores.

Actualizar anuncios

Puedes actualizar los anuncios con solicitudes por lotes. Para actualizar las pujas de tres anuncios:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Si incluyes redownload=1 en la URL relativa, obtienes todos los detalles del anuncio, incluido el identificador del anuncio correspondiente. Esto te ayuda a identificar los anuncios que has actualizado.

Para actualizar el contenido de un anuncio, especifica todo el contenido o proporciona el identificador de un nuevo contenido. Debe seguirse este proceso porque el contenido de los anuncios no se puede editar una vez creado (excepto el nombre y el estado de la ejecución).

Leer anuncios

Si tienes un gran número de anuncios, divide la solicitud en varias solicitudes en una solicitud por lotes:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839 y 6004164369439 son identificadores de anuncios y 6003356307839 y 6004164259439 son identificadores de conjuntos de anuncios.

Insights de anuncios

Si tienes un gran número de insights de anuncios, divide la solicitud en varias solicitudes en una solicitud por lotes:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

En este ejemplo, 6003356308839 y 6004164369439 son identificadores de anuncios y 6003356307839 y 6004164259439 son identificadores de conjuntos de anuncios.

En el caso de las cuentas publicitarias con un gran número de anuncios, no se recomienda utilizar act_<account_ID>/adgroupstats, ya que puede provocar que se agote el tiempo de espera de la solicitud.

Solicitudes por lotes para estimar el alcance

Puedes solicitar un máximo de 50 estimaciones de alcance en una sola solicitud por lotes. En el siguiente ejemplo se muestra la solicitud de la estimación de alcance de dos especificaciones de segmentación diferentes:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

API de lotes

La API de lotes te permite agrupar las solicitudes y enviarlas de forma asíncrona. Agrupa varias llamadas a la API Graph en una solicitud HTTP y ejecútalas de forma asíncrona sin necesidad de bloquear. También puedes especificar dependencias entre operaciones relacionadas.

Facebook procesa las operaciones independientes en procesos paralelos y las operaciones dependientes de forma secuencial. Cada llamada a la API puede tener un máximo de 1000 solicitudes.

Realizar una llamada a la API de lotes

Para realizar una llamada a la API de lotes:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Proporciona una matriz de solicitudes HTTP POST como matrices JSON. Cada solicitud tiene:

• name
• relative_url: parte de la URL que aparece después de graph.facebook.com.
• body

La API devuelve un identificador que utilizarás para consultar el progreso de las solicitudes.

Por ejemplo, crea una campaña con un conjunto de anuncios con el formato JSONPath para hacer referencia a las solicitudes anteriores:

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Para obtener el estado de un conjunto de solicitudes:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v20.0/<REQUEST_SET_ID>"

Se devuelve el estado general de los conjuntos de solicitudes asíncronas como objetos JSON. No se devuelven todos los campos de forma predeterminada. Para incluirlos, especifica fields, como fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Una vez que obtienes el estado general, puedes obtener los detalles de cada solicitud:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v20.0/<REQUEST_SET_ID>/requests"

Los detalles se devuelven como una matriz JSON. Para incluir los campos que no son predeterminados, especifícalos en fields, como fields=id,scope_object_id,status,result,input,async_request_set.

Enumerar las solicitudes de la API de lotes de una cuenta publicitaria

Puedes crear varios conjuntos de solicitudes de la API de lotes. Para consultar todos los conjuntos de solicitudes de una cuenta publicitaria:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/async_requests"

ETags

La API de marketing admite las ETags, que te ayudan a indicar si los datos que consultas han cambiado desde la última vez que los has comprobado. Funcionamiento:

1. Al realizar una llamada, el encabezado de la respuesta incluye una ETag con un valor que es el hash de los datos que se devuelven en la llamada a la API. Guarda el valor de esta ETag para usarlo en el siguiente paso.
2. La próxima vez que realices la misma llamada a la API, incluye el encabezado If-None-Match de la solicitud con el valor de la ETag que has guardado.
3. Si los datos no han cambiado, el código de estado de la respuesta es 304 – Not Modified y no se devuelven datos.
4. Si los datos han cambiado desde la última consulta, los datos se devuelven como de costumbre con una nueva ETag. Guarda el valor de la nueva ETag y úsalo para las llamadas posteriores.

Aunque las ETags ayudan a reducir el tráfico de datos, If-None-Match GET se sigue teniendo en cuenta para los límites de frecuencia de la aplicación.

La ETag se calcula con la respuesta completa de la llamada a la API, incluido el formato. El formato de la respuesta se puede ver afectado por la cadena de agente de usuario. Por lo tanto, el agente de usuario debe ser coherente entre las llamadas que se realizan desde el mismo cliente.

Ejemplos de ETags

Para comprobar si las cuentas publicitarias de un usuario han cambiado.

Paso 1: Determinar la ETag de los datos actuales

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

La respuesta tendrá un aspecto similar al siguiente:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

En este ejemplo, la ETag es "7776cdb01f44354af8bfa4db0c56eebcb1378975". Ten en cuenta que la ETag incluye las comillas (").

Paso 2: Determinar si se ha producido algún cambio en los datos

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Si no ha habido ningún cambio, la respuesta tendrá un aspecto similar al siguiente:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Observa la respuesta 304 Not Modified. Si los datos han cambiado, se devolverá una respuesta normal de la API.

Un ejemplo de lotes para comprobar si los anuncios de un usuario han cambiado.

Paso 1: Determinar la ETag de los datos actuales

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

La respuesta incluirá los valores de la ETag como en el siguiente ejemplo:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

En este ejemplo, las ETags son "21d371640127490b2ed0387e8af3f0f8c9eff012" y "410e53bb257f116e8716e4ebcc76df1c567b87f4". Ten en cuenta que la ETag incluye las comillas (").

Paso 2: Determinar si se ha producido algún cambio en los datos

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

Si no ha habido ningún cambio, la respuesta es la siguiente:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Observa la respuesta 304 Not Modified. Si los datos han cambiado, devolvemos una respuesta normal de la API.