Rate limiting nell'API Graph

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. L'app riceverà il codice di errore 4 nel caso di raggiungimento di tali limiti.

Dashboard per il rate limiting

Visualizza i grafici correlati all'attività di rate limiting della tua app nella relativa Dashboard gestione app.

Limiti

Il rate limiting viene imposto a ciascuna app. Lo strumento per il rate limiting ti offre informazioni relative a quanto l'app si avvicina al throttling. Clicca su un esempio per maggiori dettagli sui tipi di uso.

La tua app può effettuare 200 chiamate all'ora, per utente in forma aggregata. Ad esempio, se la tua app ha 100 utenti, può effettuare 20 000 chiamate. Non si tratta di un limite per utente, di conseguenza un utente potrebbe effettuare 19 000 chiamate e un altro solo 1000. Il limite viene calcolato in base al numero di chiamate effettuate nell'ora precedente.

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 come la media degli utenti attivi al giorno a cui si sommano i nuovi accessi della giornata odierna come valore stimato. Le app con un numero di utenti maggiore potrebbero avere un rate limiting più preciso rispetto a quelle con un numero di utenti inferiore. Le app con un numero molto limitato di utenti 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. Raggiungere questi limiti non è facile, pertanto si tratta di un'evenienza alquanto rara. Queste informazioni sono disponibili nel riquadro dei dettagli per ciascun esempio. 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 all'indirizzo https://developers.facebook.com/docs/marketing-api/api-rate-limiting.

Consigli

Il rate limiting definisce i limiti relativi al numero di chiamate API che possono essere effettuate entro un determinato periodo. Una volta superata la soglia del rate limiting, tutte le chiamate API da un'app vengono sottoposte a throttling e non hanno esito positivo per un breve periodo. Una volta che un'app viene sottoposta a throttling, chi ha effettuato la chiamata riceve un errore per chiamate consecutive con error code = 4, CodedException. L'accettazione di nuove richieste 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 l'app effettua un numero di chiamate tale da essere preso in considerazione dal sistema per il rate limiting, restituiamo un'intestazione HTTP X-App-Usage. Tale intestazione contiene la percentuale corrente dell'uso per la tua app. La percentuale è pari a quella visualizzata sul grafico 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?

La tua app supera 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.