Solicitudes asincrónicas y por lotes

Usa las solicitudes asincrónicas para crear anuncios y enviar diversas solicitudes de anuncios sin tener que aplicar bloqueos. Especifica una URL para llamar después de completar las solicitudes o para consultar el estado de la solicitud. ConsultaAnuncio, Referencia.

La forma más eficiente de administrar anuncios es mediante solicitudes por lotes. Usala para realizar alguna de las solicitudes más comunes.

Solicitudes asincrónicas

Por ejemplo, obtén el estado del conjunto de solicitudes asincrónicas:

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

Devuelve el estado general del conjunto de solicitudes asincrónicas como un objeto JSON. No todos los campos se muestran de forma predeterminada. Si quieres que tu consulta incluya campos no predeterminados, especifícalos en fields, como fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Una vez que recibas el estado general del conjunto de solicitudes asincrónicas, obtén los detalles de cada solicitud:

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

Devuelve el estado y los detalles de cada solicitud dentro del conjunto de solicitudes asincrónicas. Para la creación de anuncios asincrónicos, realiza una solicitud para crear un anuncio. Se usa el parámetro de estado para filtrar las solicitudes según su propio estado y se puede hacer con cualquier combinación de los siguientes valores:

• initial: sin procesar aún.
• in_progress: procesando solicitud
• success: solicitud finalizada y exitosa
• error: solicitud finalizada y desaprobada
• canceled: solicitud cancelada por el usuario

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

Obtener detalles de las solicitudes

Para obtener detalles de una solicitud asincrónica específica, realiza esta llamada:

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

Se devuelve un objeto JSON con los campos que se indican anteriormente.

Publicar los conjuntos de solicitudes para una cuenta

Puedes crear varios conjuntos de solicitudes de anuncio asincrónico. Para consultar todos los conjuntos de solicitudes de anuncio asincrónico para una cuenta publicitaria:

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

Devuelve una matriz JSON de objetos de conjunto de solicitudes asincrónicas. Cada objeto es el mismo que se especifica en . Puedes filtrar los resultados con is_completed. Si is_completed=true, solo verás el conjunto de solicitudes asincrónicas completado.

Publicar las solicitudes para un conjunto de anuncios

Puedes realizar una llamada asincrónica 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 para un conjunto de anuncios:

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

Devuelve una matriz JSON de objetos de la solicitud asincrónica. El estado, el filtro de campos y los campos de la solicitud asincrónica 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 name, notification_uri y notification_mode para un conjunto de solicitudes asincrónicas.

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

Devuelve true cuando la actualización tiene éxito. Solo puedes cambiar notification_uri y notification_mode antes de enviar la notificación.

Cancelar solicitudes

Puedes cancelar una solicitud asincrónica; esto solo se puede hacer si la solicitud aún no se procesó.

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

Devuelve true cuando la cancelación se realiza correctamente. También puedes cancelar solicitudes sin procesar en el conjunto de solicitudes asincrónicas.

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

Devuelve true cuando la cancelación tiene éxito.

Ejemplos de solicitud asincrónica

Para obtener el estado de una solicitud asincrónica específica:

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

Valores devueltos:

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

Obtén los resultados de las solicitudes:

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

Devuelve:

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

Obtén una lista de los conjuntos de solicitudes de una cuenta de anuncios:

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

Devuelve:

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

Obtén una lista de solicitudes de una campaña:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.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 es posible combinar un número de llamadas de la API Graph en una solicitud HTTP. La API de marketing divide esta solicitud en sus solicitudes de electores. Esto hace que las solicitudes por lotes sean el modo más eficiente de interactuar con la API de marketing. Para que sean aún más eficientes, puedes hacer solicitudes por lotes en paralelo usando secuencias de procesamiento separadas.

Las solicitudes para anuncios, contenidos de anuncio y conjunto de anuncios son muy similares así que no las trataremos por separado. Para obtener más información, consulta las solicitudes por lotes de la API Graph y las ETags

Crear anuncios

Puedes ofrecer contenido del anuncio y otros objetos de anuncio en una solicitud por lotes. Por ejemplo, puedes crear tres anuncios usando un contenido del anuncio y tres especificaciones de segmentación diferentes. Primero define el contenido del anuncio. Luego, haz una referencia a este cuando generes un 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 los códigos de respuesta individuales de cada solicitud y la respuesta estándar de la API Graph. Para obtener información más detallada, consulta Hacer solicitudes de API por lotes.

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

Actualizar anuncios

Puedes actualizar anuncios con solicitudes por lotes. Para actualizar pujas para 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, obtendrás los detalles completos del anuncio e, incluso, el identificador del anuncio. Esto te ayuda a identificar qué anuncios actualizaste.

Para actualizar el contenido del anuncio, especifica todo el contenido o proporciona un identificador de contenido nuevo. Esto se debe a que los contenidos del anuncio no se pueden editar una vez creados, excepto en lo que se refiere al nombre y el estado de circulación.

Leer anuncios

Si tienes un gran número de anuncios, divide la solicitud en varias solicitudes dentro de 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.

Estadísticas de anuncios

Si tienes un gran número de estadísticas de anuncios, divide la solicitud en varias solicitudes dentro de 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 el siguiente ejemplo, 6003356308839 y 6004164369439 son identificadores de anuncios, y 6003356307839 y 6004164259439 son identificadores de conjuntos de anuncios.

No se recomienda para las cuentas de anuncio con un gran número de anuncios que usan act_<account_ID>/adgroupstats porque puede que la solicitud exceda los tiempos de espera.

Solicitudes por lotes para la estimación de alcance

Puedes solicitar hasta 50 alcances estimados en una sola solicitud por lotes. En el siguiente ejemplo, se muestra el alcance estimado que se solicitó para 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 del lote te permite agrupar las solicitudes por lotes y enviarlas de forma asincrónica. Agrupa varias llamadas a la API Graph en una solicitud HTTP y ejecútalas de forma asincrónica sin necesidad de aplicar bloqueos. También puedes especificar dependencias entre operaciones relacionadas.

Facebook procesa cada operación independiente en procesos paralelos y tus operaciones dependientes de forma secuencial. Cada llamada de API puede tener un máximo de 1000 solicitudes.

Realizar una llamada de la API del lote

Para realizar una llamada por lotes a la API:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v21.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 después de graph.facebook.com
• body

La API devuelve un identificador que se usa 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 previas:

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 un estado del conjunto de solicitudes:

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

Devuelve el estado general de los conjuntos de solicitudes asincrónicas como objetos JSON. No se muestran todos los campos de forma predeterminada. Para incluirlos, especifica los 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/v21.0/<REQUEST_SET_ID>/requests"

Devuelve detalles como una matriz JSON. Para incluir campos no predeterminados, especifícalo en fields, como fields=id,scope_object_id,status,result,input,async_request_set.

Publicar las solicitudes de la API de lotes para una cuenta publicitaria

Puedes crear varios conjuntos de solicitudes de la API de lotes. Para hacer una consulta sobre todos los conjuntos de solicitudes en una cuenta publicitaria:

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

ETags

La API de marketing admite ETags. Esto te permite determinar si los datos que consultaste cambiaron desde tu última consulta. Cómo funciona:

1. Cuando haces una llamada, el encabezado de la respuesta incluye un ETag con un valor que es el cifrado de los datos devueltos en la llamada de la API. Guarda este valor de ETag para usarlo en el siguiente paso.
2. La próxima vez que realices la misma llamada de API, incluye el encabezado de solicitud If-None-Match con el valor ETag que guardaste.
3. Si no se han cambiado los datos, el código de estado de respuesta es 304 – Not Modified y no se devuelve ningún dato.
4. Si se cambiaron los datos desde la última consulta, se devuelven los datos de la forma habitual con un nuevo ETag. Guarda el valor nuevo de ETag y úsalo para llamadas posteriores.

Mientras que los ETags ayudan a reducir el tráfico de datos, If-None-Match GET mantiene el recuento contra los límites de frecuencia para tu app.

El ETag se calcula usando la respuesta completa desde la llamada de API, incluido su formato. El formato de la respuesta se puede ver afectada por la cadena de agente de usuario. Por lo tanto, debes mantener la uniformidad de tu agente de usuario entre las llamadas que realizas desde el mismo cliente.

Ejemplos de ETags

Para comprobar si las cuentas publicitarias del usuario han cambiado.

Paso 1: determina la ETag para los datos actuales.

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

La respuesta será como la que se muestra a continuación:

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, el ETag es "7776cdb01f44354af8bfa4db0c56eebcb1378975". Ten en cuenta que el ETag incluye las comillas (").

Paso 2: determina si hubo algún cambio en los datos

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

Si nada cambió, la respuesta será la 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

Ten en cuenta la respuesta 304 Not Modified. Si los datos han cambiado, se devuelve una respuesta habitual de la API.

Un ejemplo de lote para comprobar si los anuncios del usuario han cambiado.

Paso 1: determina la ETag para 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 contendrá los valores de ETags como los que se muestran a continuación:

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

En este ejemplo, los ETags son "21d371640127490b2ed0387e8af3f0f8c9eff012" y "410e53bb257f116e8716e4ebcc76df1c567b87f4". Ten en cuenta que el ETag tiene comillas (").

Paso 2: determina si hubo 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 nada cambió, la respuesta es la siguiente:

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

Ten en cuenta la respuesta 304 Not Modified. Si los datos han cambiado, devolveremos una respuesta habitual de la API.