Wskazówki dotyczące zgodności wstecznej

Każde żądanie YouTube Data API może określić wersję API, która powinna być używana przez YouTube do obsługi tego żądania. Jeśli żądanie nie określa wersji interfejsu API, do obsługi żądania YouTube użyje najstarszej obsługiwanej wersji tego interfejsu. Najstarsza obsługiwana wersja to obecnie 1. Zwróć uwagę na następujące cechy wersji interfejsu API:

• YouTube może aktualizować aktualizacje określonej wersji interfejsu API, do której nie został przypisany nowy numer. Aktualizacje zgodne wstecznie mogą obejmować opcjonalne funkcje interfejsu API lub poprawki błędów.

• Wzrost numeru wersji interfejsu API oznacza wersję, która zawiera zmiany niezgodne z poprzednimi wersjami interfejsu API.

Ten dokument definiuje wskazówki dotyczące zgodności wstecznej w przypadku aktualizacji określonej wersji interfejsu API – pierwszego elementu wymienionego powyżej. Wytyczne służą do odróżniania tych typów funkcji interfejsu API:

• Wytyczne określają funkcje interfejsu API, które mogą ulec zmianie nawet w przypadku braku modyfikacji wersji interfejsu API. Kod powinien obsługiwać te zmiany bez awarii. Jeśli na przykład YouTube dodaje nowe tagi XML do odpowiedzi interfejsu API, kod powinien ignorować te tagi.

• Wytyczne określają też funkcje interfejsu API, których YouTube nie zamierza zmieniać przy aktualizowaniu konkretnej wersji interfejsu API. Innymi słowy, możesz spodziewać się, że ta funkcja się zmieni tylko wtedy, gdy YouTube opublikuje nową wersję interfejsu API, a Twój kod nie powinien podejmować prób obsługi takich zmian.

Informacje o tym dokumencie

Niniejszy dokument obejmuje następujące sekcje:

• Sekcja Żądania API definiuje wytyczne dotyczące zgodności wstecznej związane z nagłówkami żądań HTTP, parametrami żądań interfejsu API, nazwami elementów XML (wyświetlanymi w żądaniach interfejsu API) i nieprawidłowo sformułowanymi żądaniami do interfejsu API.

• Sekcja Odpowiedzi API definiuje wytyczne dotyczące zgodności wstecznej związane z nazwami elementów XML (w takiej postaci, w jakiej występują w odpowiedziach interfejsu API), oraz kolejność, w jakiej tagi i atrybuty XML są widoczne w odpowiedziach interfejsu API.

• W sekcji Sprawdzone metody znajdziesz zalecenia dotyczące integracji interfejsu YouTube API z aplikacją kliencką.

Żądania do interfejsu API

Funkcje, których nie zamierzam zmieniać

• Istniejące parametry żądania.

• Istniejące wartości parametrów, które mają wartości wyliczane lub ich znaczenie.

• Nazwy elementów XML używane w żądaniach POST (wstawienie) lub PUT (aktualizacji) interfejsu API.

• Zbiór nagłówków żądań HTTP, które są wymagane w przypadku każdego typu żądania interfejsu API. Wytyczne te oznaczają, że YouTube nie zamierza dodawać wymaganych nagłówków żądań HTTP ani zmieniać wymaganych opcjonalnych nagłówków żądania.

• Działanie ignorowania nieobsługiwanych parametrów w żądaniu do interfejsu API, chyba że żądanie używa parametru strict, który nakazuje YouTube odrzucenie żądania interfejsu API zawierającego nieprawidłowe parametry.

Funkcje, które mogą ulec zmianie

• YouTube może dodać opcjonalne parametry żądania.

• YouTube może dodać nowe wartości do istniejących parametrów z wyliczonymi zestawami wartości.

• YouTube może odrzucić każde żądanie, w którym prawidłowe parametry zawierają nieprawidłowe wartości. W efekcie nieprawidłowo sformułowane żądania, które zostały zaakceptowane ze względu na nadmiernie łagodną analizę, mogą zostać odrzucone, jeśli logika analizy analizy zostanie poprawiona.

• YouTube może dodać opcjonalne nagłówki żądań HTTP.

• YouTube może zmieniać informacje, które przechowuje (magazyny) podczas wstawiania lub aktualizowania zasobu. Taka decyzja nie będzie jednak miała wpływu na składnię odpowiednich żądań interfejsu API ani nie będzie wymagać ich zmiany.

• YouTube może zmienić zestaw możliwych do przeglądania kategorii lub zestaw kategorii, do których można przypisać nowo przesłane filmy.

• Nieudokumentowana funkcja może zostać w każdej chwili usunięta lub zmieniona.

Odpowiedzi interfejsu API

Funkcje, których nie zamierzam zmieniać

• Istniejące nazwy tagów XML.

• Postępując zgodnie ze specyfikacją Media RSS, możesz określić kolejność elementów, które są zdefiniowane w tej specyfikacji i które pojawiają się wiele razy we wpisie w kanale. Jeśli na przykład wpis zawiera wiele tagów <media:thumbnail>, są one uporządkowane według wagi.

• Wartość atrybutu term tagu <category>, która identyfikuje typ elementu opisanego w pliku danych lub wpisie w pliku danych. W tagu <feed> lub <entry> tag <id> określa unikalny zasób wskazany we wpisie, a tag <category> określa rodzaj zasobu opisanego we wpisie. W przypadku tego tagu <category> wartość schematu schematu wynosi http://schemas.google.com/g/2005#kind, a wartość atrybutu hasło wskazuje, czy wpisy kanału opisują filmy, linki do playlist, subskrypcje, kontakty lub inny typ elementu.

Funkcje, które mogą ulec zmianie

• YouTube może dodawać nowe tagi XML do odpowiedzi interfejsu API.

• YouTube może dodawać nowe atrybuty do istniejących tagów XML.

• Istniejące tagi interfejsu API mogą się powtarzać z różnymi wartościami. Możemy na przykład dodać nowy tag <media:restriction> o innej wartości type lub nowy tag <media:credit> o różnych wartościach scheme i role.

• Kolejność tagów i atrybutów XML w odpowiedzi interfejsu API może ulec zmianie.

• Opcjonalne tagi podrzędne mogą zostać usunięte z odpowiedzi interfejsu API.

• Nieudokumentowana funkcja może zostać w każdej chwili usunięta lub zmieniona.

Sprawdzone metody

• Użyj wartości tagu <id>, aby zidentyfikować wpis.

• Aby pobrać wpis, użyj linku self.

• Aby edytować lub zaktualizować wpis, użyj linku edit.

• Użyj wartości tagu <yt:videoid> dla wpisu filmu, aby uzyskać wartość, dzięki której YouTube może jednoznacznie zidentyfikować ten film. Nie analizuj identyfikatora filmu z linku.

• Aby przechodzić między plikami danych, używaj adresów URL zidentyfikowanych w tagach <link>, <content> i <gd:feedLink>. YouTube obsługuje ograniczoną liczbę adresów URL, które możesz pewnie tworzyć, aby pobierać określone kanały. Poza adresami URL kanału podanymi poniżej nie należy tworzyć własnych adresów URL kanałów, ponieważ mogą one niespodziewanie przestać działać.

  • /feeds/api/videos/<videoid>
  • /feeds/api/users/default
  • /feeds/api/users/default/uploads
  • /feeds/api/users/default/favorites
  • /feeds/api/users/default/contacts
  • /feeds/api/users/default/inbox
  • /feeds/api/users/default/playlists
  • /feeds/api/users/default/subscriptions
  • /feeds/api/users/default/newsubscriptionvideos
  • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (więcej informacji znajdziesz w przewodniku)

• Nie próbuj analizować liczbowych ani alfanumerycznych identyfikatorów z adresów URL w odpowiedzi interfejsu API. Odpowiedzi interfejsu API zawierają konkretne tagi dla linków do zasobów w witrynie YouTube, np. identyfikatory filmów (<yt:videoid>) i nazwy użytkowników (<name> oraz <media:credit>).).

• Jeśli prześlesz żądanie interfejsu API dotyczące wstawiania (POST) lub aktualizacji (PUT), użyj odpowiedzi XML na to żądanie, aby ustalić, które wartości tagów w żądaniu zostały faktycznie zapisane przez YouTube. Jak wspomniano w wytycznych dotyczących zgodności wstecznej w przypadku żądań interfejsu API, YouTube może zmienić informacje, które przechowuje (przechowuje) podczas wstawiania lub aktualizowania zasobu, co oznacza, że niektóre tagi w żądaniu mogą zostać zignorowane.

• Po pobraniu kanału XML zapisz nierozpoznane tagi XML i atrybuty związane z wpisami w kanale, jeśli aplikacja umożliwia aktualizowanie tego wpisu. Jeśli użytkownik zaktualizuje zasób, Twoja aplikacja powinna zawierać wszystkie nierozpoznane tagi i atrybuty w żądaniu aktualizacji. W ramach tego rozwiązania aplikacja nieumyślnie nie usunie informacji związanych z nowymi funkcjami interfejsu API w trakcie aktualizowania zasobu.

  Ten przykład pokazuje tę sprawdzoną metodę:

  1. Aplikacja umożliwia aktualizowanie opisu filmu.
  2. Aplikacja pobiera wpis wideo przez interfejs API, ale nie rozpoznaje jednego z wpisów we wpisie.
  3. Użytkownik modyfikuje opis filmu.
  4. Aplikacja musi wysłać pełny wpis wideo z powrotem do interfejsu API. Wpis musi zawierać nierozpoznany tag z kroku 2. W przeciwnym razie ta wartość może zostać usunięta.

• Zanim spróbujesz wyświetlić wartość tagu, upewnij się, że tag istnieje i zawiera wartość null.

• Jak już wspomnieliśmy, YouTube może dodać nowe wartości dla istniejących tagów lub atrybutów, które mają wyliczone zbiory wartości. Reguła powinna być przetwarzana przez wartości elementów XML z wyliczonymi zestawami wartości, a następnie zdefiniować działania odpowiednie dla tych wartości. Zalecamy takie rozwiązanie, nawet gdy dla elementu jest przypisana tylko jedna możliwa wartość.

  Na przykład tag <media:credit> określa właściciela filmu. Jedyną udokumentowaną wartością atrybutu role tagu jest uploader, co oznacza, że film został przesłany przez partnera YouTube. Zgodnie ze sprawdzonymi metodami przed zgłoszeniem odpowiedniego użytkownika jako właściciela filmu aplikacja powinna potwierdzić, że wartość atrybutu role to faktycznie uploader. Dzięki temu kodowi nie będzie można nieprawidłowo zidentyfikować właściciela filmu, jeśli YouTube doda do niego inne typy napisów, np. reżysera.

  • Jeśli tag zawiera wyliczony zestaw wartości i nie rozpoznajesz jego wartości, zignoruj cały <entry>, w którym występuje.

  • Jeśli nie rozpoznajesz wartości atrybutu term dla tagu <category>, który ma wartość scheme w http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat, zignoruj ten wpis. Ten konkretny tag określa typ subskrypcji identyfikowany przez wpis. Jeśli aplikacja nie rozpoznaje typu subskrypcji, nie powinna wyświetlać informacji o tym wpisie.

  • Jeśli inny atrybut ma wyliczony zestaw wartości i nie rozpoznajesz jego wartości, zignoruj ten tag, w którym występuje.

• Twój kod aplikacji powinien w każdej chwili wyświetlić się na ekranie yt:error. W przypadku niepowodzenia operacji interfejsu API aplikacja powinna zidentyfikować błąd i wyświetlić użytkownikowi zrozumiały komunikat.

• YouTube może w każdej chwili dodać nowe kategorie do klasyfikowania filmów. YouTube może też aktualizować lub wycofywać istniejące kategorie. Możesz pobrać obecny plik kategorii z http://gdata.youtube.com/schemas/2007/category.cat.

  • Jeśli aplikacja umożliwia użytkownikom przeglądanie filmów według kategorii lub przesyłanie filmów wideo, co tydzień pobieraj zaktualizowany plik.

  • Jeśli Twoja aplikacja umożliwia użytkownikom przeglądanie filmów według kategorii, pobierz także zaktualizowany plik kategorii, gdy interfejs API zwróci pusty plik danych w odpowiedzi na wyszukiwanie kategorii.

  • Jeśli Twoja aplikacja umożliwia użytkownikom przesyłanie filmów, przed przesłaniem filmu pobierz też zaktualizowany plik kategorii, aby potwierdzić, że kategorię powiązaną z przesłanym filmem nadal można przypisać. Więcej informacji znajdziesz w przewodniku. (Pamiętaj, że jeśli spróbujesz przypisać film do kategorii, której nie można przypisać, interfejs API zwróci komunikat o błędzie, dla którego wartość tagu <code> to deprecated).

• Tagi <link> w odpowiedzi interfejsu API służą do identyfikowania linków do strony dla poprzedniej lub następnej strony w pliku danych. Więcej informacji znajdziesz w sekcji przewodnika po sekcjach wyników.