Słownik

Nagłówek x-app-usage od Meta to trzy procenty i żadnego zegara

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •9 min czytania
Nagłówek x-app-usage i jego trzy pola procentowe w Facebook Graph APINagłówek x-app-usage i jego trzy pola procentowe w Facebook Graph API

TL;DR, szybka odpowiedź

9 min czytania

Meta dołącza x-app-usage do odpowiedzi Graph API, gdy aplikacja wykona wystarczająco dużo wywołań danego endpointu. Nagłówek zawiera trzy liczby całkowite, call_count, total_time i total_cputime, z których każda jest procentem limitu, którego Meta nigdy nie podaje jako konkretnej liczby. Limit na poziomie aplikacji stojący za call_count to 200 razy liczba użytkowników na ruchomą godzinę. Jego osiągnięcie zwraca kod błędu 4, a w przeciwieństwie do nagłówka business use case x-app-usage nie ma pola mówiącego, kiedy dostęp wróci.

Czym jest nagłówek x-app-usage?

Meta zwraca nagłówek x-app-usage w odpowiedziach Graph API, aby poinformować aplikację, jaką część jej limitu żądań już wykorzystano. Dokumentacja limitów przedstawia go jednym zdaniem: "Endpoints that receive enough requests from your app will include a X-App-Usage or X-Ad-Account-Usage (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage."

W tym zdaniu kryją się dwa warunki. Nagłówek należy do aplikacji, a nie do konta czy użytkownika, którego token wykonał wywołanie. Pojawia się też tylko na endpointach, które obsłużyły wystarczający ruch, co Meta powtarza gdzie indziej jako nagłówki "included with most API responses once enough calls have been made to an endpoint." Odpowiedź bez x-app-usage oznacza, że Meta nie zgłosiła użycia, a nie że wynosi ono zero.

Wartość to obiekt JSON z trzema kluczami i niczym więcej. Przykład od Meta:

x-app-usage: {
  "call_count": 28,         // Percentage of calls made
  "total_time": 25,         // Percentage of total time
  "total_cputime": 25       // Percentage of total CPU time
}

To, które żądania dostają ten nagłówek, a które inny, zależy od API i tokenu. Meta rozdziela to jasno: "Graph API requests are subject to Platform Rate Limits, while Marketing API and Instagram Platform requests are subject to Business Use Case (BUC) Rate Limits." Wywołania Pages API trafiają po jednej lub drugiej stronie zależnie od poświadczeń: tokeny aplikacji i użytkownika podlegają limitom Platform, a tokeny użytkownika systemowego lub strony limitom business use case.

Co oznaczają trzy pola w x-app-usage?

Wszystkie trzy to procenty limitu, a nie liczniki czegokolwiek.

PoleCo według Meta zawiera
call_count"A whole number expressing the percentage of calls made by your app over a rolling one hour period"
total_cputime"A whole number expressing the percentage of CPU time allotted for query processing"
total_time"A whole number expressing the percentage of total time allotted for query processing"

Słowo "whole" ma tu znaczenie. Każda wartość w x-app-usage jest liczbą całkowitą, więc najdokładniejszy odczyt to jeden procent budżetu. Inny nagłówek Meta na poziomie aplikacji jest w tej kwestii precyzyjniejszy: pole acc_id_util_pct w X-Ad-Account-Usage pojawia się w przykładzie jako 9.67, z częścią dziesiętną. x-app-usage zaokrągla.

Te trzy pola ograniczają też ruch niezależnie od siebie. Meta przypisuje obu polom czasu te same zdania: "When total_cputime reaches 100, calls may be throttled" oraz "When total_time reaches 100, calls may be throttled." Kilka kosztownych zapytań może zbliżyć total_cputime do limitu, gdy call_count wciąż jest jednocyfrowe, więc aplikacja śledząca wyłącznie liczbę wywołań przeoczy dwa z trzech sposobów, w jakie może zostać zablokowana.

Zwróć uwagę, czego Meta tam nie publikuje. Dokumentacja podaje próg dla total_cputime i dla total_time, ale w sekcji o nagłówkach Platform nigdy nie zapisuje analogicznego zdania dla call_count. Zamiast tego mówi ogólnie: "Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit." Mimo to traktuj 100 w call_count jako limit, bo nic w dokumencie nie wskazuje innej liczby.

Osoba przegląda wykresy użycia na laptopie, co symbolizuje godzinny limit, względem którego mierzone są wywołania aplikacji.

Względem jakiego limitu liczone są te procenty?

Względem formuły na poziomie aplikacji, którą Meta publikuje w całości: Calls within one hour = 200 * Number of Users.

Mnożnik jest stały, a drugi czynnik to zaangażowanie. Meta definiuje go jako "the number of unique daily active users an app has", z wariantem dla nierównego ruchu: "In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and monthly active Users are used to calculate the number of Users for your app." Liczba instalacji nie ma znaczenia. Meta mówi to wprost: aplikacje z wysokim dziennym zaangażowaniem dostają wyższe limity "regardless of the actual number of app installs."

Pula jest wspólna, a nie dzielona. Meta sama pokazuje rachunek: "if your app has 100 Users, your app can make 20,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls." Jedno hałaśliwe konto może w tej samej godzinie pozbawić zasobów pozostałych użytkowników aplikacji, a limit Platform niczemu temu nie zapobiega.

Tokeny użytkowników mają drugi, oddzielny licznik, którego nie zgłasza żaden nagłówek. Własny licznik wywołań użytkownika działa w jego własnej ruchomej godzinie i obejmuje wszystkie używane przez niego aplikacje, dlatego Meta ostrzega, że użytkownik "could make X calls through App1 and Y calls through App2" i zostać ograniczony na podstawie sumy. Następnie zamyka temat pomiaru: "Due to privacy concerns, we do not reveal actual call count values for users." Nagłówka x-user-usage nie ma. Strona użytkownika w limitach Platform z założenia pozostaje niewidoczna.

Jedna zasada liczenia zaskakuje osoby używające zapytań zbiorczych. FAQ Meta stwierdza, że "each ID counts as one API call", i pokazuje to na przykładzie: trzy osobne żądania o jeden identyfikator liczą się jako trzy wywołania, a jedno żądanie z ids=4,5,6 również jako trzy. Łączenie poprawia wydajność odpowiedzi, ale nie oszczędza limitu. To inny model rozliczania niż limity żądań na endpoint publikowane przez Bluesky i niż podział Pinteresta na limity aplikacji i użytkownika.

Czym x-app-usage różni się od nagłówka business use case?

Innym zakresem, inną strukturą, a jeden z nich mówi, kiedy odzyskasz dostęp.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

X-App-UsageX-Business-Use-Case-Usage
DotyczyGraph API, Platform Rate LimitsMarketing API, Instagram Platform, Pages z tokenem strony lub użytkownika systemowego
StrukturaJeden płaski obiekt JSONKlucze według identyfikatora firmy, do 32 obiektów na wywołanie
Pola użyciacall_count, total_cputime, total_timecall_count, total_cputime, total_time
Wskazuje typ limituNieTak, przez type
Podaje czas oczekiwaniaNieTak, przez estimated_time_to_regain_access w minutach

Nagłówek business use case jest bogatszy i to on ma znaczenie przy publikowaniu na Instagramie. Formułę Meta 4800 razy odsłony i pola X-Business-Use-Case-Usage omawiamy szczegółowo osobno, wraz z wartościami type i przypisanymi do nich kodami błędów.

W miejscu, gdzie oba nagłówki się stykają, dokument Meta sam sobie zaprzecza. Sekcja Platform dodaje dopisek "(for v3.3 and older Ads API calls)" do X-Ad-Account-Usage, i to właśnie opisuje. Sekcja business use case powtarza następnie ten sam dopisek przy innym nagłówku: "All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage (for v3.3 and older Ads API calls) HTTP header." Nagłówek business use case nie ogranicza się do wywołań v3.3 i starszych, a reszta tej samej sekcji dokumentuje go jako aktualny mechanizm dla ruchu Instagrama i Marketing API. Traktuj ten dopisek jako pozostałość po kopiowaniu.

Zasada pierwszeństwa między nimi to jedyne zdanie warte zapamiętania: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

Czerwone światło na sygnalizatorze jako symbol sygnału stop, na który aplikacja powinna zareagować, gdy limit osiągnie 100.

Co się dzieje, gdy x-app-usage pokazuje 100?

Wywołania zaczynają zawodzić z numerowanym błędem, a numer zależy od tego, czyj limit został przekroczony.

KodCo według Meta oznacza
4"The app whose token is being used in the request has reached its rate limit". Dokumentacja błędów Meta nazywa go API Too Many Calls
17"The User whose token is being used in the request has reached their rate limit", nazwany API User Too Many Calls
32"The User or app whose token is being used in the Pages API request has reached its rate limit". Komunikat brzmi "(#32) Page request limit reached"
613"A custom rate limit has been reached", a obowiązującą liczbę dokumentuje poszczególne API, nie ta strona
613 podkod 1996"We have noticed inconsistent behavior in the API request volume of your app"

Zalecenie Meta dla wszystkich jest takie samo i nie jest polityką stopniowego wycofywania: "When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again."

Właśnie tego zdania nie uwzględnia większość pętli ponawiania. Wykładnicze wycofywanie nadal wysyła żądania, a według Meta każde z nich odsuwa moment odblokowania. Poprawną reakcją na kod błędu 4 jest wstrzymanie kolejki, a nie jej spowolnienie.

Potem pojawia się luka. Dobra praktyka Meta dotycząca powrotu do działania brzmi: "Check the X-App-Usage HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached." Nagłówek ma trzy pola, wszystkie procentowe, i żadne z nich nie jest czasem. estimated_time_to_regain_access istnieje w nagłówku business use case. reset_time_duration istnieje w X-Ad-Account-Usage. W x-app-usage nie ma żadnego z nich. Meta każe odczytać czas wznowienia z nagłówka, który go nie zawiera.

W zamian dostajesz App Dashboard, gdzie Meta pokazuje "the app's current Application Rate Limits usage percentage" oraz średnią aktywność z ostatnich siedmiu dni. To wykres dla ludzi, a nie pole, które odczyta logika ponawiania. W praktyce warto obserwować wzrost call_count, zatrzymać się wyraźnie przed 100 i równomiernie rozkładać ruch, co zresztą zaleca sama Meta: "Spread out queries evenly to avoid traffic spikes." Harmonogramy publikacji natrafiają też na osobne, nieopisane liczbami limity, a dzienne limity postów na Facebooku to odrębny system z własnymi zasadami.

Dwie reakcje na kod błędu 4
Wstrzymanie kolejki
  • Przestajesz wykonywać wywołania
  • Licznik wywołań przestaje rosnąć
  • Dostęp wraca szybciej
Wykładnicze wycofywanie
  • Nadal wysyła żądania
  • Licznik wywołań dalej rośnie
  • Odsuwa moment odblokowania
Zalecenia Meta dla kodu błędu 4 wykluczają typowy wzorzec ponawiania.

Najczęściej zadawane pytania

Jakie trzy pola zawiera nagłówek x-app-usage?

call_count, total_cputime i total_time. Meta definiuje każde z nich jako liczbę całkowitą wyrażającą procent: wywołań wykonanych w ruchomej godzinie oraz czasu CPU i całkowitego czasu przydzielonego na przetwarzanie zapytań.

Jaki limit Graph API na poziomie aplikacji stoi za call_count?

Calls within one hour = 200 * Number of Users, gdzie liczba użytkowników to liczona przez Meta liczba unikalnych aktywnych użytkowników dziennych aplikacji, a przy nierównym ruchu dziennym używane są dane tygodniowe i miesięczne.

Który kod błędu oznacza przekroczenie limitu x-app-usage?

Kod 4, nazwany przez Meta "API Too Many Calls". Kod 17 dotyczy własnego limitu użytkownika, a kod 32 wywołań Pages API wykonanych tokenem użytkownika lub aplikacji.

Czy x-app-usage mówi, kiedy kończy się blokada?

Nie. Zawiera trzy procenty i żadnego pola czasu, choć dobre praktyki Meta każą sprawdzać w nim, kiedy można wznowić wywołania. estimated_time_to_regain_access należy do nagłówka business use case, a nie do tego.

Czy nagłówek x-app-usage pojawia się w każdej odpowiedzi?

Nie. Meta zwraca go na endpointach "that receive enough requests from your app", więc brak nagłówka nie niesie żadnej informacji i nigdy nie należy go odczytywać jako zerowego użycia.

Które żądania dostają x-app-usage zamiast X-Business-Use-Case-Usage?

Żądania Graph API objęte Platform Rate Limits. Żądania Marketing API i Instagram Platform dostają nagłówek business use case, a gdy mogą mieć zastosowanie oba, według Meta wygrywają limity business use case.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Kto liczy się jako użytkownik w formule 200 razy liczba użytkowników?

Meta definiuje to jako liczbę unikalnych aktywnych użytkowników dziennych aplikacji. Gdy ruch dzienny waha się między dniami roboczymi a weekendami, używani są aktywni użytkownicy tygodniowi i miesięczni. Instalacje nie mają znaczenia, ponieważ aplikacje o wysokim zaangażowaniu dostają wyższe limity niezależnie od ich faktycznej liczby.

Czy jeden użytkownik może wyczerpać cały limit aplikacji?

Jeden intensywnie działający użytkownik może. Rachunek Meta pokazuje, że aplikacja ze 100 użytkownikami ma godzinną pulę 20 000 wywołań, a dziesięciu najbardziej zaangażowanych może odpowiadać za 19 000 z nich. Pula jest wspólna, a nie dzielona, więc limit Platform nie powstrzyma jednego konta przed wyczerpaniem zasobów pozostałych użytkowników aplikacji w tej samej godzinie.

Czy łączenie wielu identyfikatorów w jednym żądaniu oszczędza limit?

Nie zmniejsza to tego, co obciąża limit. FAQ Meta stwierdza, że każdy identyfikator liczy się jako jedno wywołanie API, więc trzy osobne żądania o jeden identyfikator i jedno żądanie z ids=4,5,6 to w obu przypadkach trzy wywołania. Łączenie poprawia wydajność odpowiedzi, a nie budżet.

Czym x-app-usage różni się od X-Ad-Account-Usage?

X-Ad-Account-Usage podaje pole acc_id_util_pct z częścią dziesiętną, w przykładzie Meta jako 9.67, a każde pole x-app-usage jest zaokrąglane do pełnego procenta. X-Ad-Account-Usage zawiera też reset_time_duration, którego x-app-usage nie ma, a sam nagłówek jest powiązany z wywołaniami Ads API v3.3 i starszymi.

Czy ten artykuł był pomocny?

Chętnie poznamy opinię!

Więcej naszych treści w Google

Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.

Jeszcze chwila...

AdaptlyPost

AdaptlyPost

Planowanie treści na wszystkich platformach

Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Powiązane hasła ze słownika

Powiązane artykuły