Słownik

Wszystkie pola do planowania wideo przez API YouTube i ich pułapki

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •7 min czytania
Wszystkie pola do planowania wideo przez API YouTube i ich pułapkiWszystkie pola do planowania wideo przez API YouTube i ich pułapki

TL;DR, szybka odpowiedź

7 min czytania

Planowanie odbywa się przez status.publishAt w zasobie videos. Pole można ustawić tylko wtedy, gdy status.privacyStatus ma wartość private, a w videos.update musisz ponownie wysłać privacyStatus jako private w tym samym żądaniu, nawet jeśli wideo już jest prywatne. Znacznik czasu z przeszłości publikuje wideo od razu, zamiast zwrócić błąd. Błędne wartości dają invalidPublishAt z kodem 400. Insert kosztuje 1 jednostkę z puli 100 przesłań dziennie, a update 50 jednostek z puli głównej.

Jak zaplanować wideo przez API YouTube?

API YouTube nie ma endpointu do planowania wideo: planowanie to jedna właściwość daty i godziny, status.publishAt, ustawiana w zasobie videos przez videos.insert albo videos.update. Na liście metod nie znajdziesz czasownika schedule, osobnego zasobu do planowania ani obiektu kolejki. Ustawiasz znacznik czasu, a YouTube upublicznia wideo, gdy nadejdzie wskazany moment.

Dlatego większość błędów planowania na YouTube to w rzeczywistości błędy metadanych. Wszystko, co może się nie udać, psuje się w formacie jednego pola albo w wartości prywatności tuż obok niego. Kwestia samego terminu, czyli tego, w jaką godzinę celować, to osobny temat, który omawiamy w tekście o tym, kiedy przesłać wideo na YouTube.

Czego wymaga status.publishAt?

Dokumentacja Google dla zasobu videos podaje to ograniczenie dwa razy, innymi słowami, bo ludzie wciąż je przeoczają.

Najpierw: "The date and time when the video is scheduled to publish. It can be set only if the privacy status of the video is private."

Potem jeszcze raz, z fragmentem, przez który psują się wywołania update: "If you set this property's value when calling the videos.update method, you must also set the status.privacyStatus property value to private even if the video is already private." Samo ustawienie publishAt w wideo, które już jest prywatne, nie wystarczy. Żądanie musi ponownie zawierać private.

Jest też trzeci warunek: "This property can only be set if the video's privacy status is private and the video has never been published." Wideo, które choć raz było publiczne, nie wróci do harmonogramu przez ustawienie publishAt.

status.privacyStatus przyjmuje trzy wartości: private, public i unlisted. Tylko private można połączyć z zaplanowaną godziną publikacji.

Jaki format ma publishAt i czy to RFC 3339?

Tutaj dokumentacja i ekosystem używają innego słownictwa.

Zasób videos opisuje status.publishAt jako datetime i podaje, że "the value is specified in ISO 8601 format." Na tej stronie nie ma ani słowa o RFC 3339. Oznaczenie RFC 3339 pojawia się w dokumentacji YouTube Data API, ale przy innych polach: search.list opisuje publishedAfter i publishedBefore jako "an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z)."

W praktyce obie nazwy oznaczają dla tego pola ten sam akceptowany ciąg znaków, bo RFC 3339 jest profilem ISO 8601, a skalar datetime w API Google to właśnie RFC 3339. Liczy się kształt tego, co wysyłasz:

2026-10-01T14:30:00Z
2026-10-01T10:30:00-04:00

Data bez godziny, godzina bez przesunięcia albo lokalny znacznik czasu ze strefą domyślną zamiast podanej to typowe źródła invalidPublishAt. Wysyłaj jawne przesunięcie albo Z. Jeśli przeliczasz czas lokalny użytkownika, zrób to przed wysłaniem żądania, zamiast liczyć, że API odgadnie strefę, której nigdy nie dostało.

Osoba sprawdza nocą godzinę na telefonie, co przypomina o ryzyku ustawienia zaplanowanej publikacji w przeszłości.

Co się stanie, jeśli znacznik czasu jest w przeszłości?

Wideo zostanie opublikowane. Natychmiast. To udokumentowane zachowanie, a nie błąd.

"If your request schedules a video to be published at some time in the past, the video will be published right away. As such, the effect of setting the status.publishAt property to a past date and time is the same as of changing the video's privacyStatus from private to public."

Takie zachowanie wymaga zabezpieczenia w każdym fragmencie kodu, który wylicza godzinę publikacji. Konwersja strefy czasowej cofnięta o godzinę, kolejka ponawiająca stare zadanie czy szkic, który przeleżał weekend na etapie akceptacji, nie zgłoszą głośno problemu. Wideo po prostu trafi do sieci. Zanim wyślesz wyliczony znacznik czasu, sprawdź, czy leży w przyszłości, bo YouTube nie zrobi tego za ciebie.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Znacznik czasu w przyszłości a w przeszłości
publishAt w przyszłości
  • Wideo pozostaje prywatne do wskazanego momentu
  • YouTube sam zmienia je na publiczne
  • W chwili publikacji nic nie musisz robić
publishAt w przeszłości
  • Wideo publikuje się od razu po zapisaniu
  • Efekt jak przy ręcznej zmianie privacyStatus na public
  • Żaden błąd nie sygnalizuje pomyłki
Znacznik publishAt, który już minął, pomija harmonogram i publikuje wideo od razu.

Jakie błędy zwraca API?

videos.insert i videos.update dokumentują ten sam błąd planowania oraz zestaw pokrewnych błędów, które dotyczą metadanych wysyłanych razem z nim.

Typ błęduSzczegół błęduCo oznacza
badRequest (400)invalidPublishAt"The request metadata specifies an invalid scheduled publishing time."
badRequest (400)invalidVideoMetadata"The request metadata is invalid."
badRequest (400)invalidTitle"The request metadata specifies an invalid or empty video title."
badRequest (400)invalidDescription"The request metadata specifies an invalid video description."
badRequest (400)invalidCategoryIdsnippet.categoryId nie jest obsługiwaną kategorią.
badRequest (400)invalidTags"The request metadata specifies invalid video keywords."
badRequest (400)defaultLanguageNotSetWysłano zlokalizowane dane bez języka domyślnego.
forbidden (403)forbiddenPrivacySetting"The request attempts to set an invalid privacy setting for the video."
forbidden (403)forbiddenLicenseSetting"The request attempts to set an invalid license for the video."
notFound (404)videoNotFoundTylko update. id z treści żądania nie wskazuje żadnego wideo.

videos.insert dodaje trzy własne błędy: mediaBodyRequired, gdy żądanie nie zawiera wideo, invalidFilename, gdy nagłówek Slug jest nieprawidłowy, oraz uploadLimitExceeded, który dokumentacja objaśnia jako "the user has exceeded the number of videos they may upload."

Zwróć uwagę, że forbiddenPrivacySetting to 403, a nie 400. Jeśli przy wywołaniu planującym przechwytujesz tylko kody 400, odrzucona wartość prywatności ominie twoją obsługę błędów.

Co robi part przy aktualizacji i dlaczego coś kasuje?

To druga najdroższa pomyłka po znaczniku czasu z przeszłości i bezpośredni skutek tego, jak videos.update traktuje parametr part. To także powód, dla którego większość zespołów sięga po narzędzie do planowania wideo na YouTube, zamiast samodzielnie wywoływać endpoint.

Dokumentacja mówi o tym wprost: "this method will override the existing values for all of the mutable properties that are contained in any parts that the parameter value specifies." Następnie podaje dokładnie ten przypadek, na którym potykają się narzędzia planujące: "if your request is updating a private video, and the request's part parameter value includes the status part, the video's privacy setting will be updated to whatever value the request body specifies. If the request body does not specify a value, the existing privacy setting will be removed and the video will revert to the default privacy setting."

part=status nie działa więc jak łatka. Każda modyfikowalna właściwość w status, którą pominiesz, zostanie wyczyszczona. To samo dotyczy part=snippet, dlatego aktualizacja harmonogramu wysyłająca samo publishAt z part=snippet,status może skasować opis, nawet jeśli napisany był tuż pod limitem znaków opisu. Odczytaj bieżący zasób, zmień tylko te pola, które chcesz, i odeślij całą część.

Dwie osoby rozpisują proces pracy na tablicy, co nawiązuje do kosztów planowania i przekładania publikacji wideo.

Ile limitu zużywa planowanie?

Od zmiany pul w czerwcu 2026 te dwa wywołania korzystają z różnych limitów.

WywołanieWpływ na limit według dokumentacji
videos.insert"100 calls per day. A call to this method has a quota cost of 1 unit in the Video Uploads quota bucket."
videos.update"A call to this method has a quota cost of 50 units."
videos.list1 jednostka
thumbnails.set50 jednostek

Ta asymetria wpływa na planowanie pracy. Ustawienie publishAt już w pierwszym videos.insert nic dodatkowo nie kosztuje, bo pulę 100 przesłań dziennie zużywa samo przesłanie. Późniejsza zmiana terminu to 50 jednostek za każdą próbę z głównej puli 10 000 jednostek, i tyle samo kosztuje każda ustawiana miniatura. Proces, który przesyła wideo jako prywatne, dwa razy aktualizuje harmonogram, a potem ustawia miniaturę, zużywa 150 jednostek na jeden film, zanim ktokolwiek go obejrzy. Jeśli ten rachunek zaczyna cię ograniczać, wyjściem jest zwiększenie limitu i związany z nim audyt, a nie kolejne ponowienia.

Najczęściej zadawane pytania

Które pole planuje wideo na YouTube przez API?

status.publishAt w zasobie videos. To wartość typu datetime, którą ustawiasz przez videos.insert podczas przesyłania albo później przez videos.update. YouTube Data API nie ma osobnej metody ani zasobu do planowania.

Dlaczego moja aktualizacja publishAt jest odrzucana?

Najczęstszą przyczyną jest prywatność. Dokumentacja Google mówi, że przy ustawianiu publishAt przez videos.update "you must also set the status.privacyStatus property value to private even if the video is already private." Wysłanie publishAt bez privacyStatus w tym samym żądaniu nie zaplanuje wideo.

Czy mogę zaplanować wideo, które jest już publiczne?

Nie. Dokumentacja podaje, że publishAt "can only be set if the video's privacy status is private and the video has never been published." Gdy wideo raz stanie się publiczne, to pole jest dla niego zamknięte na stałe.

Jaki format czasu przyjmuje publishAt?

Strona zasobu videos opisuje tę wartość jako ISO 8601. Wyślij pełną datę i godzinę z jawnym przesunięciem względem UTC albo z końcowym Z, na przykład 2026-10-01T14:30:00Z. Wartości bez godziny lub przesunięcia strefy to najczęstsze źródło invalidPublishAt.

Co się stanie, jeśli publishAt jest w przeszłości?

Wideo opublikuje się natychmiast. Google opisuje to jako odpowiednik zmiany privacyStatus z prywatnego na publiczny. Nie dostaniesz żadnego błędu, więc sprawdź znacznik czasu przed wysłaniem.

Ile limitu zużywa planowanie?

videos.insert kosztuje 1 jednostkę z puli Video Uploads ograniczonej do 100 wywołań dziennie. videos.update kosztuje 50 jednostek z głównej puli dziennej. Ustawienie publishAt przy pierwszym insercie nie kosztuje więc nic poza samym przesłaniem, a każda późniejsza zmiana terminu to 50 jednostek.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Czy mogę zaplanować wideo z privacyStatus ustawionym na unlisted?

status.privacyStatus przyjmuje trzy wartości, private, public i unlisted, ale zaplanowaną godzinę publikacji akceptuje tylko private. Ustawienie publishAt przy privacyStatus równym unlisted lub public nie zaplanuje wideo. Wyślij privacyStatus jako private w tym samym żądaniu, które zawiera publishAt.

Dlaczego po aktualizacji harmonogramu zniknął opis mojego wideo?

videos.update nadpisuje wszystkie modyfikowalne właściwości we wskazanych częściach, a nie tylko pola z treści żądania. Wywołanie z part=snippet,status, które wysyła samo publishAt, czyści każde pominięte pole snippet, w tym opis. Odczytaj bieżący zasób, zachowaj potrzebne pola i odeślij całą część razem ze zmianą publishAt.

Czy forbiddenPrivacySetting to błąd 400 czy 403?

To 403, zaliczany do forbidden, a nie do badRequest. Obsługa błędów, która przy wywołaniu planującym sprawdza tylko odpowiedzi 400, przepuści odrzucone ustawienie prywatności. Przy sprawdzaniu odpowiedzi videos.insert lub videos.update przechwytuj zarówno 403, jak i 400.

Ile nowych wideo mogę zaplanować przez API w ciągu dnia?

Do 100. videos.insert korzysta z puli Video Uploads ograniczonej do 100 wywołań dziennie, a każde wywołanie zużywa 1 jednostkę tego limitu, niezależnego od głównej puli 10 000 jednostek. Późniejsza zmiana terminu istniejącego wideo idzie przez videos.update, co kosztuje 50 jednostek z głównej puli i nie narusza limitu przesłań.

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