Limiti e best practice

L'API Insights di Facebook fornisce i dati sulle prestazioni delle campagne di marketing di Facebook. Per salvaguardare le prestazioni e la stabilità del sistema, abbiamo messo in campo misure protettive per distribuire equamente le risorse di sistema tra le app. Tutte le normative descritte di seguito sono soggette a variazioni.

Limiti ai dati per chiamata

Abbiamo previsto limiti ai dati per chiamata, allo scopo di evitare che le query recuperino una quantità di dati superiore alla capacità di gestione del sistema. Esistono 2 tipi di limiti ai dati:

1. Per numero di righe nella risposta.
2. Per numero di punti dati richiesti per l'elaborazione del totale, ad esempio la riga di riepilogo.

Questi limiti valgono per le chiamate a /insights sincrone e asincrone, per cui restituiamo un errore:

error_code = 100,  CodeException (error subcode: 1487534)

Best practice, limiti ai dati per chiamata

• Limita la query intervenendo sull'intervallo di date o sul numero di ID dell'inserzione. Puoi anche limitare la query alle metriche necessarie o suddividerla in più query, ognuna delle quali richiederà diversi sottoinsiemi di metriche.
• Evita le query a livello di account che includano dettagli a cardinalità elevata, ad esempio action_target_id o product_id, e intervalli di date molto ampi come il lifetime value.
• Usa il segmento /insights direttamente con gli oggetti pubblicitari di livello inferiore per recuperare dati granulari per il livello interessato. Ad esempio, usa prima la query a livello di account per recuperare la lista di ID oggetto di livello inferiore con parametri level e filtering. In questo esempio, recuperiamo tutte le campagne che hanno registrato impression:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

• A questo punto, possiamo usare /<campaign_id>/insights con ogni valore restituito per effettuare query e raggruppare in batch le richieste di dati statistici per tali campagne in un'unica chiamata:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'

• Usa il parametro filtering solo per recuperare dati statistici per gli oggetti pubblicitari che contengono dati. Il valore del campo specificato in filtering usa la notazione DOT per denotare i campi sotto l'oggetto. L'applicazione del filtro con STARTS_WITH e CONTAIN non modifica i dati di riepilogo. In questo caso, usa l'operatore IN. Ecco un esempio di richiesta filtering:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'

• Se possibile, usa date_preset. Gli intervalli di date personalizzati vengono eseguiti con minore efficienza nel nostro sistema.
• Usa le richieste batch per più chiamate sincrone e quelle asincrone per eseguire query su grandi volumi di dati, allo scopo di evitare i timeout.
• Prova prima le chiamate sincrone e usa quelle asincrone in caso di timeout.
• I dati statistici si aggiornano ogni 15 minuti e non subiscono modifiche dopo 28 giorni dalla segnalazione.

Limite al carico delle chiamate per dati statistici

Novanta giorni dopo il rilascio della versione 3.3 e valido per tutte le versioni pubbliche, il rate limiting al livello di account pubblicitario viene modificato per riflettere meglio il volume di chiamate API necessario. Viene calcolata la quota di rate limiting sul livello di accesso dell'API Marketing e sull'azienda proprietaria dell'app. Fai riferimento ad accesso e autenticazione. Questa modifica si applica a tutti gli endpoint dell'API Ads Insights: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.

Limitiamo il carico per garantire un'esperienza ottimale in termini di report. Misuriamo le chiamate API per la frequenza e le risorse necessarie. Consentiamo un limite fisso al carico per app al secondo. Quando superi tale limite, le tue richieste non vanno a buon fine.

Controlla l'intestazione HTTP x-fb-ads-insights-throttle in ogni risposta API per sapere quanto la tua app è vicina al suo limite e stimare quanto può essere pesante una particolare query. Le chiamate per i dati statistici sono inoltre soggette ai limiti dell'account pubblicitario predefinito mostrati nell'intestazione HTTP x-ad-account-usage. Per maggiori dettagli, consulta le best practice per l'API Marketing.

Quando l'app raggiunge il limite, la chiamata riceve una risposta di errore con error_code = 4, CodedException. Dovresti rimanere ben sotto il limite. Se l'app raggiunge i limiti consentiti, solo una determinata percentuale di richieste verrà completata, in base alla query e alla frequenza.

Il rate limiting viene applicato a tutte le app che inviano chiamate /insights sincrone e asincrone combinate. I due parametri principali previsti per i limiti definiti fanno riferimento ad app e account pubblicitario.

Ecco un esempio dell'intestazione HTTP con un punteggio maturato di un'app come percentuale dei limiti:

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

L'intestazione "x-fb-ads-insights-throttle" è un valore JSON che contiene le informazioni seguenti:

• app_id_util_pct: la percentuale di capacità allocata per il campo app_id associato è stata esaurita.
• acc_id_util_pct: la percentuale di capacità allocata per il campo ad account_id associato è stata esaurita.
• ads_api_access_tier: i livelli consentono alla tua app di accedere all'API Marketing. standard_access consente un rate limiting inferiore.

Rate limiting globali

Durante i periodi di carico globale elevato sull'endpoint /insights, il sistema può eseguire il throttling delle richieste per proteggere il backend. Questo può verificarsi in rari casi in cui si ricevono contemporaneamente troppe richieste di elevata complessità (estesi intervalli temporali, metriche complesse e/o un numero elevato di ID dell'oggetto pubblicitario. Questo genererà un errore simile al seguente:

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

In questi periodi, si consiglia di ridurre le chiamate, attendere un breve periodo e ripetere la query.

Best practice sul rate limiting

• Inviando diverse query contemporaneamente, aumenta la possibilità di attivare il rate limiting. Prova a distribuire le query /insights, regolandone la distribuzione in base ai tempi di attesa del tuo processo.
• Usa le informazioni sulla frequenza nell'intestazione della risposta HTTP per moderare le chiamate. Aggiungi un meccanismo di limitazione per rallentare o mettere in pausa le query /insights quando stai per raggiungere la soglia massima utile per la tua app o l'account pubblicitario.
• I dati statistici sulle inserzioni vengono segnalati in base al fuso orario dell'account pubblicitario. Per recuperare i dati statistici per l'account pubblicitario associato su base giornaliera, considera l'ora del giorno tramite il fuso orario dell'account. Ciò consente di distribuire le query nel corso della giornata.
• Controlla l'ads_api_access_tier che ti consente di accedere all'API Marketing. Per impostazione predefinita, le app sono nel livello development_access e standard_access consente un rate limiting inferiore. Per ottenere un rate limiting più alto e arrivare al livello standard, puoi richiedere l'"accesso avanzato" alla funzione Accesso standard a Gestione inserzioni.

Processi asincroni dell'API Insights

Recupera le statistiche su diversi oggetti e applica filtri e criteri di ordinamento. Abbiamo semplificato il flusso di lavoro asincrono:

1. Invia una richiesta POST all'endpoint <AD_OBJECT>/insights, che risponde con l'id dell'esecuzione di un report pubblicitario.

{
  "report_run_id": 6023920149050,
}
    

Non memorizzare report_run_id per un uso di lunga durata, poiché scade dopo 30 giorni.

1. Le esecuzioni di report pubblicitari contengono informazioni sul processo asincrono, ad es. async_status. Esegui il polling del campo finché async_status non corrisponde a Job Completed e async_percent_completion non corrisponde a 100.

{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
    

1. In seguito, puoi eseguire una query sul segmento <AD_REPORT_RUN_ID>/insights per recuperare il risultato finale.

{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}
    

Il processo acquisisce tutte le statistiche relative all'account e restituisce un ID processo asincrono:

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

Stato del processo asincrono

Esportazione dei report

Forniamo un endpoint di comodità per l'esportazione di <AD_REPORT_RUN_ID> in un formato leggibile localizzato.

Nota: questo endpoint non fa parte della nostra API Graph con versione, pertanto non è conforme alla sua normativa sulle modifiche sostanziali. Gli script e i programmi non devono dipendere dal formato del risultato poiché può cambiare in modo imprevisto.

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'