Rate limiting nell'API Graph

Il rate limiting definisce i limiti relativi al numero di chiamate API che possono essere effettuate entro un determinato periodo. Il rate limiting viene imposto a ogni app.

Le app che superano tali limiti in modo eccessivo o costante potrebbero subire la disabilitazione.

Di norma, il rate limiting nell'API Graph di Facebook si verifica raramente. Questo documento descrive quali sono i limiti e come gestirli.

Esistono due tipi principali di rate limiting che la tua app può subire: a livello di app e a livello di Pagina.

Rate limiting a livello di app

Questi limiti valgono per le chiamate effettuate tramite un token d'accesso diverso da quello per la Pagina.

Tutte le chiamate API effettuate da un'app che ha già superato il rate limiting saranno soggette a throttling e restituiranno un errore di tipo error code = 4, CodedException. Le chiamate verranno ripristinate una volta che l'uso nel corso dell'ora precedente torna al di sotto del limite. Le chiamate vengono calcolate in base a una finestra mobile di un'ora e le attuali percentuali d'uso sono disponibili nella Dashboard gestione app.

Dashboard per il rate limiting

Lo strumento per il rate limiting ti offre informazioni relative a quanto l'app si avvicina al throttling. Puoi visualizzare le informazioni sul rate limiting che interessa le tue app tramite due grafici nella Dashboard gestione app.

  • Un grafico mostra l'uso attuale che interessa le risposte restituite dall'API Graph. Si tratta di una rappresentazione grafica del valore dell'intestazione restituito nelle richieste all'API Graph.
Grafico di un'app vicina al valore rate limiting
  • Il secondo grafico mostra i valori di rate limiting in senso cronologico. Puoi decidere di vedere i dati delle ultime 24 ore o degli ultimi 7 giorni. Puoi cliccare sugli campioni del grafico cronologico per vedere altri dettagli sull'uso, compresa una suddivisione in dettagli in base al metodo. Non tutte le app dispongono di dati cronologici, dal momento che la presenza di tali dati dipende dal volume di chiamate. Le app con maggiori volumi di chiamate potrebbero disporre di dati cronologici.
Grafico cronologico di un'app che ha superato i valori di rate limiting nelle ultime 24 ore

Limiti

Il numero totale di chiamate che la tua app può effettuare ogni ora è pari a 200 volte il numero di utenti. Non si tratta di un limite per utente: un singolo utente può effettuare più di 200 chiamate all'ora, fintanto che il totale degli utenti non superi i valori massimi per l'app. Ad esempio, se la tua app ha 100 utenti, l'app può effettuare 20 000 chiamate all'ora. Tuttavia, 19 000 di tali chiamate potrebbero provenire dai primi dieci utenti che interagiscono di più.

Se l'app è sottoposta a rate limiting, tutte le chiamate per l'app saranno limitate, non solo quelle per un dato utente.

Il numero degli utenti della tua app viene calcolato tramite il numero degli utenti attivi giornalmente e i nuovi accessi della giornata odierna. Nei casi in cui si riscontrano periodi con un calo di usi giornalieri, il calcolo del numero di utenti dell'app viene effettuato in base agli utenti attivi settimanalmente o al mese. Le app con un numero elevato di interazioni giornaliere presenterà un rate limiting maggiore rispetto a quelle con interazioni giornaliere limitate, indipendentemente dal numero effettivo di installazioni dell'app.

Precisazioni:

  • Non tutte le chiamate API sono soggette a rate limiting, pertanto il numero di chiamate effettuate potrebbe non corrispondere ai dati riportati nello strumento per il rate limiting.
  • Inoltre, sottoponiamo le chiamate a throttling in base al tempo della CPU usato e il tempo totale. Gli endpoint che richiedono un'elaborazione intensiva potrebbero far sì che l'app raggiunga tali limiti, anche se al di sotto del limite di volume delle chiamate. È raro che un'app raggiunga i limiti di tempo della CPU e di tempo totale, fatta eccezione per gli endpoint specializzati. Puoi vedere le informazioni sugli endpoint che impiegano molto tempo della CPU o totale nel grafico cronologico, se disponibile.
  • L'API Ads Insights e l'API Marketing potrebbero usare un diverso insieme di rate limiting. Per maggiori informazioni sull'API Marketing, consulta la documentazione sul rate limiting dell'API Marketing all'indirizzo https://developers.facebook.com/docs/marketing-api/api-rate-limiting.

Consigli

Per evitare il rate limiting:

  • Distribuisci equamente le query tra due intervalli di tempo, per evitare l'invio di picchi di traffico.
  • Usa i filtri per limitare le dimensioni delle risposte dei dati e per evitare chiamate che di fatto richiedono dati sovrapposti.
  • Usa l'intestazione del rate limiting per equilibrare in modo dinamico il volume delle chiamate.

Intestazione del rate limiting

Tutte le risposte alle chiamate effettuate all'API Graph includono un'intestazione HTTP X-App-Usage. Tale intestazione contiene la percentuale corrente dell'uso per la tua app. La percentuale è pari a quella visualizzata sui grafici del rate limiting. Usa questo numero per equilibrare in modo dinamico il carico delle chiamate, al fine di evitare il throttling.

L'intestazione del rate limiting è una stringa in formato JSON nella forma seguente:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

I valori di x, y e z sono numeri interi che rappresentano la percentuale dei valori in uso per ogni metrica. Quando una delle metriche supera 100, l'app subirà il rate limiting.

Rate limiting a livello di Pagina

Questi limiti valgono per le chiamate effettuate tramite un token d'accesso per la Pagina. L'app riceverà il codice di errore 32 nel caso di raggiungimento di tali limiti.

Il post sul blog all'indirizzo https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ illustra in modo dettagliato il rate limiting a livello di Pagina.

Dashboard per il rate limiting

Puoi visualizzare i grafici del rate limiting per ogni Pagina per la quale l'app usa il token d'accesso per effettuare le chiamate.

Limiti

Il rate limiting viene applicato a ogni singola Pagina e non all'intera app. Lo strumento per il rate limiting ti offre informazioni su quante volte l'app usa il token d'accesso per quella Pagina e quanto tale Pagina si avvicina al throttling. Clicca su un esempio per maggiori dettagli sui tipi di uso.

Il numero di utenti giornalieri che interagiscono con una Pagina rappresenta il numero univoco di utenti che hanno interagito con la Pagina nell'arco di 24 ore. L'interazione con una Pagina corrisponde a un clic sulla Pagina o sul relativo contenuto.

Il numero di utenti che hanno interagito nelle 24 ore precedenti viene usato per calcolare il rate limiting per la finestra delle 24 ore corrente.

È possibile effettuare per conto della Pagina un totale di 4800 chiamate per utenti giornalieri che interagiscono per 24 ore in aggregato. Ad esempio, se la Pagina ha 100 utenti giornalieri che interagiscono, è possibile effettuare 480 000 chiamate per conto della Pagina nell'arco di 24 ore. Questo periodo di 24 ore è da considerarsi una finestra mobile, aggiornata a intervalli di pochi minuti. Il limite delle chiamate è per Pagina, pertanto un'app può effettuare 400 000 chiamate e un'altra ne può effettuare 80 000. Se una Pagina viene sottoposta a rate limiting, la limitazione si applica solo alle chiamate dall'app che usano il token d'accesso per quella Pagina. Di conseguenza, l'app continuerà a funzionare normalmente per le altre chiamate.

Il numero di chiamate alla tua Pagina viene calcolato come numero stimato tramite il token d'accesso per la Pagina su base giornaliera. Le Pagine con un numero maggiore di chiamate giornaliere potrebbero presentare un rate limiting più preciso rispetto a quelle con un numero minore. Le Pagine con un numero molto limitato di chiamate giornaliere potrebbero subire problemi di rate limiting.

Precisazioni:

  • Non tutte le chiamate API sono soggette a rate limiting, pertanto il numero di chiamate effettuate potrebbe non corrispondere ai dati riportati nello strumento per il rate limiting.
  • Inoltre, Facebook sottopone le chiamate a throttling in base al tempo della CPU usato e il tempo totale. Per maggiori dettagli, clicca sul grafico nello strumento per il rate limiting sulla tua dashboard.
  • L'API Ads Insights e l'API Marketing potrebbero usare un diverso insieme di rate limiting. Per maggiori informazioni sull'API Marketing, consulta la documentazione sul rate limiting dell'API Marketing.

Consigli

Una volta che una Pagina viene sottoposta a throttling, chi ha effettuato la chiamata riceve un errore per chiamate consecutive con error code = 32, CodedException. L'accettazione di nuove richieste per la Pagina potrebbe richiedere anche un'ora.

Per evitare il rate limiting:

  • Distribuisci equamente le query tra due intervalli di tempo, per evitare l'invio di picchi di traffico.
  • Usa i filtri per limitare le dimensioni delle risposte dei dati e per evitare chiamate che di fatto richiedono dati sovrapposti.
  • Usa l'intestazione del rate limiting per equilibrare in modo dinamico il volume delle chiamate.

Intestazione del rate limiting

Se il numero di chiamate effettuate per conto di una Pagina è tale da essere preso in considerazione dal sistema per il rate limiting, restituiamo un'intestazione HTTP X-Page-Usage. Tale intestazione contiene la percentuale corrente dell'uso relativamente alla Pagina. Se effettui chiamate tramite il token d'accesso di una Pagina, ottieni il valore X-Page-Usage solo per quella Pagina. La percentuale corrisponde all'uso mostrato nel grafico del rate limiting per tale Pagina. Usa questo numero per equilibrare in modo dinamico il carico delle chiamate, al fine di evitare il throttling.

L'intestazione del rate limiting è una stringa in formato JSON nella forma seguente:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

I valori di x, y e z sono numeri interi che rappresentano la percentuale dei valori in uso per ogni metrica. Quando una delle metriche supera 100, l'app subirà il rate limiting.

Rate limiting a livello di account

Questi limiti valgono per le chiamate effettuate tramite un token d'accesso per l'utente. Al raggiungimento del limite, la tua app riceve un codice di errore 17. Ciò si verifica quando un determinato account utente effettua troppe chiamate all'API.

Nota:

possono essere incluse anche le chiamate utente effettuate relativamente a diverse app e non solo alla tua.

Quando un utente subisce il rate limiting, le sue chiamate API vengono sottoposte a throttling.

Per evitare il rate limiting:

non c'è modo per evitarlo. L'utente effettua troppe chiamate (forse attraverso altre app), di conseguenza subisce il rate limiting. Tuttavia, se questa situazione si verifica per un gran numero di utenti di un'app, è molto probabile che la causa siano le chiamate API effettuate tramite tale app. In questo caso, devi ridurre le chiamate e distribuirle in modo più equilibrato.

FAQ

Come consideriamo le chiamate API?

Il rate limiting prende in considerazione tutte le chiamate, non solo le singole richieste API HTTPS. Ad esempio, puoi effettuare una chiamata API specificando diversi ID e a ognuno sarà attribuita una chiamata, anche se la richiesta API HTTPS è una.

Per comprendere meglio questo concetto, vedi gli esempi qui sotto:

Richiesta/e di esempio Numero di chiamate API

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

Se desideri ottenere diversi oggetti tramite ID ti consigliamo di usare il secondo approccio per migliorare le prestazioni delle risposte API, sebbene non abbia effetti sulle chiamate effettuate in termini di rate limiting.

Inoltre, puoi usare l'API Batch per eseguire le richieste in batch, ma tieni presente che a ogni sottorichiesta sono attribuite una o più chiamate API, specificando diversi ID.

Se alla tua app o alla tua Pagina viene applicato il rate limiting, anche le chiamate API che restituiscono errori di rate limiting saranno considerate nel calcolo del limite.


Quali errori verranno visualizzati dalla mia app?
Tipo di throttling Almeno Codice di errore

Throttling a livello di app

200 chiamate/utente/ora

4

Throttling a livello di account

Non applicabile

17

Throttling a livello di Pagina

4800 chiamate/utente/24 ore

32

Throttling a livello personalizzato

Non applicabile

613


Riscontro il codice di errore 613, cosa posso fare?

Se la risposta dell'errore contiene error_subcode 1996, Facebook ha notato un comportamento non uniforme nel volume delle richieste API della tua app. Se hai apportato modifiche recenti che influiscono sul numero di richieste API, potresti riscontrare questo errore.

Se non visualizzi il sottocodice, la tua app sta superando un rate limiting personalizzato. Contatta il tuo partner manager per assistenza nella risoluzione del problema.


Sto creando un servizio di estrazione, devo preoccuparmi di qualcosa in particolare?

Se stai creando un servizio per estrarre dati, consulta le nostre condizioni per l'estrazione.