Słownik

Dlaczego scheduled_at w API Mastodona wymaga 5 minut wyprzedzenia

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •7 min czytania
Dlaczego scheduled_at w API Mastodona wymaga 5 minut wyprzedzeniaDlaczego scheduled_at w API Mastodona wymaga 5 minut wyprzedzenia

TL;DR, szybka odpowiedź

7 min czytania

Mastodon dokumentuje, że scheduled_at musi wskazywać czas co najmniej 5 minut w przyszłości, a kod źródłowy potwierdza to stałą MINIMUM_OFFSET = 5.minutes w ScheduledStatus. Bliższy termin zwraca HTTP 422 z błędem walidacji. Znacznik czasu z przeszłości działa inaczej: PostStatusService go pomija i publikuje status natychmiast. Dwa kolejne limity, 300 zaplanowanych statusów łącznie i 25 dziennie, występują tylko w kodzie źródłowym.

Jakie jest minimalne wyprzedzenie scheduled_at w API Mastodona?

Każda wartość scheduled_at w API Mastodona musi wypadać ponad 5 minut po bieżącym czasie zegara serwera, inaczej POST /api/v1/statuses odrzuca żądanie z kodem HTTP 422. Dokumentacja danych formularza tego endpointu mówi o tym w jednym zdaniu: "Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future."

Endpoint aktualizacji powtarza tę zasadę nieco innymi słowami. PUT /api/v1/scheduled_statuses/:id dokumentuje własne scheduled_at jako "Datetime at which the status will be published. Must be at least 5 minutes into the future", więc przesunięcie istniejącego zaplanowanego posta na termin bliższy niż pięć minut kończy się takim samym błędem jak jego utworzenie.

Ta liczba nie jest konwencją z dokumentacji. To stała w modelu, MINIMUM_OFFSET = 5.minutes.freeze w app/models/scheduled_status.rb, a korzystająca z niej walidacja wygląda tak:

def validate_future_date
  errors.add(:scheduled_at, I18n.t('scheduled_statuses.too_soon')) if scheduled_at.present? && scheduled_at <= Time.now.utc + MINIMUM_OFFSET
end

Porównanie używa <=, więc znacznik czasu dokładnie 5 minut do przodu nie przechodzi. „Co najmniej 5 minut” z dokumentacji oznacza w kodzie ściśle więcej niż 5 minut.

Co zwraca API, gdy czas jest zbyt bliski?

Kod 422 z komunikatem walidacji w polu error. Obsługa błędów API Mastodona zamienia wyjątek Rails bezpośrednio na JSON:

rescue_from ActiveRecord::RecordInvalid, Mastodon::ValidationError do |e|
  render json: { error: e.to_s }, status: 422
end

Ten moduł znajduje się w app/controllers/concerns/api/error_handling.rb i dołącza go Api::BaseController, więc treścią odpowiedzi jest tekst samego wyjątku, a nie kod czytelny dla maszyny. Nie ma kodu błędu, listy pól ani wskazówki retry-after, a parsowanie oznacza dopasowywanie angielskiego tekstu.

Dlaczego komunikat z dokumentacji różni się od tego, który wysyłają serwery?

Bo tekst w pliku językowym się zmienił, a przykład w dokumentacji nie. Strona scheduled_statuses pokazuje dla endpointu aktualizacji taką odpowiedź 422:

{
  "error": "Validation failed: Scheduled at The scheduled date must be in the future"
}

Aktualny plik config/locales/en.yml w gałęzi main repozytorium mastodon/mastodon zawiera krótsze sformułowanie:

scheduled_statuses:
  over_daily_limit: You have exceeded the limit of %{limit} scheduled posts for today
  over_total_limit: You have exceeded the limit of %{limit} scheduled posts
  too_soon: date must be in the future

Rails dodaje na początku czytelną nazwę atrybutu, więc aktualny serwer zwraca "Validation failed: Scheduled at date must be in the future". Przykład w dokumentacji wciąż zawiera starsze sformułowanie "The scheduled date must be in the future".

ŹródłoTekst
docs.joinmastodon.org, przykład 422 w scheduled_statuses"Validation failed: Scheduled at The scheduled date must be in the future"
config/locales/en.yml, gałąź main"Validation failed: Scheduled at date must be in the future"

Klient dopasowujący dokładnie zdanie z dokumentacji nie rozpozna błędu na aktualnym serwerze. Zamiast zdania sprawdzaj status 422 i to, czy twoje żądanie zawierało scheduled_at.

Osoba sprawdza godzinę na telefonie, co przypomina, że los zaplanowanego posta zależy od jednego odczytu zegara.

Co się dzieje, gdy scheduled_at jest w przeszłości?

Post wychodzi natychmiast i nie pojawia się żaden błąd. Dokumentacja nigdy nie wspomina o tym zachowaniu, a odpowiada za nie PostStatusService:

@scheduled_at = @options[:scheduled_at]&.to_datetime
@scheduled_at = nil if scheduled_in_the_past?

wraz z

def scheduled_in_the_past?
  @scheduled_at.present? && @scheduled_at <= Time.now.utc
end

Ustawienie @scheduled_at na nil sprawia, że scheduled? daje fałsz, więc żądanie trafia do process_status! zamiast do schedule_status!. Odpowiedź to encja Status, a nie ScheduledStatus, więc klient zakładający, że scheduled_at zawsze daje ScheduledStatus, odczyta niewłaściwe id posta, który jest już publiczny.

Trzy wyniki, jeden parametr:

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Wartość scheduled_atWynikOdpowiedź
W przeszłości lub dokładnie terazNatychmiastowa publikacjaStatus
W ciągu 5 minut od terazOdrzucenie422, błąd walidacji
Ponad 5 minut do przoduDodanie do kolejkiScheduledStatus

Pułapką jest środkowy przedział. Pętla ponawiania, która przesuwa nieudaną wysyłkę „o kilka minut”, trafia w 422, a ta, która w razie błędu „publikuje od razu” przez wysłanie czasu z przeszłości, dostaje opublikowany post zamiast oczekiwanego błędu.

Pułapka ponawiania
Ponowienie kilka minut później
  • Trafia w przedział 5 minut
  • Serwer odpowiada kodem 422
Awaryjne „opublikuj teraz”
  • Wysyła znacznik czasu z przeszłości
  • PostStatusService pomija scheduled_at
  • Status zostaje opublikowany od razu
Dwie typowe reakcje na nieudaną wysyłkę i żadna nie daje wyniku, jakiego oczekiwał wywołujący.

Ile zaplanowanych statusów może mieć jedno konto?

Obok tego przesunięcia, w tym samym modelu, są jeszcze dwa limity i żadnego z nich nie ma w dokumentacji API:

TOTAL_LIMIT = 300
DAILY_LIMIT = 25
MINIMUM_OFFSET = 5.minutes.freeze

TOTAL_LIMIT ogranicza liczbę statusów, które konto może mieć jednocześnie w kolejce, a komunikat brzmi "You have exceeded the limit of 300 scheduled posts". DAILY_LIMIT ogranicza liczbę statusów przypadających na jedną datę kalendarzową, sprawdzaną w bazie przez scheduled_at::date = ?::date, a komunikat brzmi "You have exceeded the limit of 25 scheduled posts for today".

Oba przychodzą w tej samej postaci 422, z komunikatem przy base, a nie przy scheduled_at. Kolejka ładująca posty na cały miesiąc w jednym przebiegu uderzy w limit 25 dziennie dużo wcześniej niż w łączne 300, a docs.joinmastodon.org nie ostrzega przed żadnym z nich.

Jaki format przyjmuje scheduled_at?

Datę i godzinę w formacie RFC 3339, który Mastodon dokumentuje osobno jako swój format daty: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD], gdzie oznaczenie strefy czasowej to Z dla UTC albo przesunięcie w rodzaju +02:00. Dokumentacja wyraźnie mówi, że separatorem jest wielkie T, a Z zawsze pisze się wielką literą.

Walidacja porównuje czas z Time.now.utc na serwerze, a nie na kliencie. Rozjechanie zegara klienta zjada więc bezpośrednio pięciominutowy margines, co jest dobrym powodem, by planować z wyprzedzeniem sześciu lub siedmiu minut, a nie pięciu minut i jednej sekundy. Ten sam problem pojawia się wszędzie tam, gdzie kolejka ufa czasowi lokalnemu, także na Mastodonie i Bluesky oraz w każdym innym API sprawdzającym czas według własnego zegara.

Ścienny kalendarz na biurku symbolizuje kolejkę zaplanowanych postów, którą konto prowadzi w czasie.

Jak zmienić lub anulować zaplanowany status?

Po utworzeniu kolejką zarządzają trzy endpointy. GET /api/v1/scheduled_statuses zwraca listę, domyślnie 20 wyników, maksymalnie 40. PUT /api/v1/scheduled_statuses/:id przyjmuje nowe scheduled_at i podlega tej samej zasadzie 5 minut. DELETE /api/v1/scheduled_statuses/:id anuluje status i zwraca pusty obiekt.

Zmiana tekstu to inna operacja. Mastodon zaznacza, że PUT /api/v1/statuses/:id edytuje opublikowany status oraz że "To edit the scheduled_at attribute of a ScheduledStatus to change the publication date, use the scheduled status endpoint." Treść posta w kolejce znajduje się w obiekcie params encji ScheduledStatus, a endpoint aktualizacji przyjmuje tylko datę, więc zmiana treści oznacza usunięcie i ponowne utworzenie posta.

Status, którego już nie ma w kolejce, zwraca 404 z {"error": "Record not found"}, i tak samo odpowiada zaplanowany status należący do innego konta.

Co dolna granica 5 minut oznacza dla kolejki publikacji?

Wyznacza najkrótszy sensowny odstęp między decyzją o publikacji a samą publikacją. Wszystko poniżej pięciu minut trzeba wysłać jako status natychmiastowy, a nie zaplanowany, więc narzędzie do planowania potrzebuje rozgałęzienia, a nie jednej ścieżki kodu: poniżej progu pomiń scheduled_at i opublikuj, powyżej dodaj do kolejki i zapisz zwrócony identyfikator ScheduledStatus.

W tym samym planowaniu warto uwzględnić dwie inne liczby. Domyślna długość posta na Mastodonie to 500 znaków, co opisuje artykuł o limicie znaków na Mastodonie, a ponad tym wszystkim działają limity zapytań poszczególnych serwerów, podobnie jak Bluesky publikuje własne limity API niezależnie od zasad dotyczących postów. Budowanie kalendarza wokół ograniczeń platformy, a nie preferencji narzędzia, to ogólny nawyk stojący za niezawodnym planowaniem postów w mediach społecznościowych.

Jedno zastrzeżenie dotyczy wszystkich powyższych liczb. Stałe pochodzą z gałęzi main repozytorium mastodon/mastodon, a serwer działający na forku lub starszej wersji może mieć inne wartości, więc czytaj treść odpowiedzi 422, zamiast zakładać, że 5, 25 i 300 obowiązują wszędzie.

Najczęściej zadawane pytania

Czy scheduled_at przyjmuje czas dokładnie 5 minut od teraz?

Nie. Walidacja porównuje za pomocą <=, więc scheduled_at <= Time.now.utc + 5.minutes nie przechodzi. Sformułowanie z dokumentacji "at least 5 minutes in the future" po lekturze kodu oznacza ściśle więcej niż pięć minut.

Jaki status HTTP zwraca Mastodon, gdy scheduled_at jest zbyt bliskie?

  1. Mastodon przechwytuje ActiveRecord::RecordInvalid i zwraca { error: e.to_s } ze statusem 422, więc treścią odpowiedzi jest zwykłe angielskie zdanie walidacji, a nie ustrukturyzowany obiekt błędu.

W której wersji Mastodona dodano scheduled_at?

W 2.7.0. Historia wersji w dokumentacji POST /api/v1/statuses podaje "2.7.0 - scheduled_at added", a trzy endpointy scheduled_statuses dodano w tym samym wydaniu.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Czy zaplanowany post zwraca Status, czy ScheduledStatus?

ScheduledStatus, o ile scheduled_at zostanie przyjęte. Mastodon podaje, że endpoint "Returns: Status. When scheduled_at is present, ScheduledStatus is returned instead." Wyjątkiem jest znacznik czasu z przeszłości, bo serwer pomija wtedy parametr, publikuje natychmiast i zwraca Status.

Czy można zaplanować ponad 25 postów na Mastodonie na ten sam dzień?

Nie na serwerze z domyślnymi ustawieniami. DAILY_LIMIT = 25 w app/models/scheduled_status.rb liczy istniejące zaplanowane statusy z tą samą datą i odrzuca dwudziesty szósty komunikatem "You have exceeded the limit of 25 scheduled posts for today". Osobny TOTAL_LIMIT = 300 ogranicza całą kolejkę. Żadnej z tych liczb nie ma w dokumentacji API.

Gdzie udokumentowano minimum 5 minut?

Na stronie metod API statuses pod adresem docs.joinmastodon.org/methods/statuses/, w parametrze formularza scheduled_at, oraz na docs.joinmastodon.org/methods/scheduled_statuses/ dla endpointu aktualizacji. Odpowiada za to stała MINIMUM_OFFSET = 5.minutes.freeze w app/models/scheduled_status.rb w repozytorium mastodon/mastodon.

Ile wyników domyślnie zwraca GET /api/v1/scheduled_statuses?

Dwadzieścia. Endpoint domyślnie zwraca 20 zaplanowanych statusów na stronę, a maksymalnie 40, więc konto zbliżające się do łącznego limitu 300 potrzebuje kilku żądań, aby przejrzeć całą kolejkę.

Co się stanie przy próbie pobrania anulowanego zaplanowanego posta?

Serwer zwraca 404 z {"error": "Record not found"}. Tak samo odpowiada zaplanowany status należący do innego konta, więc 404 nie mówi, czy post nigdy nie istniał, został już anulowany, czy po prostu nie jest twój.

Czy można edytować tekst zaplanowanego posta na Mastodonie?

Edycja tekstu oznacza usunięcie zaplanowanego posta i utworzenie nowego, a nie zmianę na miejscu. Endpoint aktualizacji przyjmuje tylko nowe scheduled_at, a treść posta w kolejce znajduje się w obiekcie params encji ScheduledStatus.

Z jakim wyprzedzeniem naprawdę warto planować post na Mastodonie?

Z ponad pięciominutowym, ale sześć lub siedem minut to bezpieczniejszy wybór niż pięć minut i jedna sekunda. Walidacja działa według zegara serwera, a nie klienta, więc każde odchylenie czasu lokalnego zjada ten margines.

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