Youtube Data API

V tomto článku si ukážeme jednoduchou PHP aplikaci, která bude vypisovat videa ze soukromého playlistu vašeho kanálu. Pro akce jako je tato, kde je potřeba autorizaci uživatele, API používá protokol OAuth 2.0. Ten funguje tak, že uživatel musí aplikaci dát ručně práva k přístupu na jeho účet.

Pokud chcete přes API přistupovat k veřejně dostupným datům, jako je např. vyhledávání videí, autorizaci provádět nemusíte. V takovém případě stačí získat z vývojářské konzole API klíč. Obecně by se dalo říct, že co můžete na Youtube provádět bez účtu, k tomu by měl v API stačit klíč. K čemu musíte účet mít, tam musí mít aplikace povolený přístup přes OAuth.

Žádat po uživateli pokaždé udělení přístupu může být docela otravné. V případě aplikace běžící na pozadí, nebo komunikace server - server, je to i nemožné. Prvotní žádosti o udělení přístupu se sice nevyhneme, ale ukážeme si, jak povolení uložit natrvalo a automaticky jej obnovovat bez nutnosti dalšího zásahu uživatele.

Autorizace

Pro ověření uživatele používá Google u všech svých API protokol OAuth 2.0. V dokumentaci uvádějí určité druhy ověření, mezi nimi i OAuth pro tzv. service účty. Ty by pro naší aplikaci byly ideální, protože nepotřebují uživatelský zásah. Narozdíl od Calendar API a Drive API, bohužel Youtube Data API přístup ze service účtů nepodporuje. Proto provedeme běžné uživatelské ověření.

Oveření přes OAuth pro Google API má 3 základní kroky:

1. Vytvoření OAuth přístupů přes console.google.com
2. Získání přístupového tokenu z autorizačního serveru
3. Odeslání tokenu na požadované API

První krok je poměrně přímočarý. Ve vývojářské konzoli Google je třeba mít založený projekt, aktivované Youtube Data API a pro něj vytvořeny OAuth přístupy. Ty se vytvářejí v sekci Credentials. Pro nás jsou důležité Client ID, Client secret a Authorized redirect URI - URL na které může být uživatel po autorizaci přesměrován.

Tady je třeba dát pozor, aby bylo Auth. redirect URI na chlup stejné jako je Redirect URL, které budete posílat do API z aplikace! V opačném případě autorizace selže. Může být problém s adresami z localhost, proto doporučuji pro lokální vývoj vytvořit tunel s veřejným URL, třeba pomocí ngrok.

Další kroky, tedy zpracování přístupového tokenu, probíhají pomocí knihovny.

Knihovna pro Google API

Instalaci knihovny Google API PHP Client, se kterou budeme pracovat, doporučuji provést přes Composer. Pokud nemáte s tímto nástrojem zkušenosti, doporučuji Pavlův článek. Stažení knihovny pak provedeme příkazem v adresáři s projektem:

composer require google/apiclient:^2.0

Composer knihovnu stáhne pod adresář vendor, ve kterém je i autoload skript, který se postará o načtení potřebných závislostí. Vložíme ho hned na začátek naší aplikace.

<?php
require_once __DIR__ . '/vendor/autoload.php';

Klient a offline přístup

Před zavoláním Youtube API je nutné vytvořit instanci třídy Google_Client. Ta bude obstarávat autorizaci a proto je jí třeba předat údaje nastavené v konzoli Google.

$client = new Google_Client();
$client->setClientId('EXAMPLE CLIENT ID');
$client->setClientSecret('EXAMPLE CLIENT SECRET');
$client->setScopes(Google_Service_YouTube::YOUTUBE);
$client->setRedirectUri('https://www.example.com/');
$client->setAccessType('offline');
$client->setApprovalPrompt('force');

Nastavení "offline" přístupu je podle názvu trochu zavádějící, ale dáme tím pouze autorizačnímu serveru najevo, že chceme rovnou obdržet refresh token pro pozdější obnovení přístupu. Bohužel při způsobu, jakým autorizační server vyhodnocuje obnovení přístupu, je v našem případě ještě potřeba vynutit refresh token nastavením approval prompt na "force".

Autorizační token

Dalším krokem je získání autorizačního/přístupového tokenu. Protože chceme jednou získaný přístup udržet a automaticky ho obnovovat, získaný token uložíme do souboru a ten budeme dále používat pro autorizaci.

Pokud zatím není k dispozici žádný uložený token, tak uživatele přesměrujeme na autorizační URL Googlu. Tam uživatel udělí aplikaci přístup a bude přesměrován zpátky do aplikace s URL parametrem "code". Tento kód slouží k vygenerování nového tokenu, který pak uložíme. Nakonec je ještě potřeba zkontrolovat platnost tokenu a případně jej obnovit. Nový nebo obnovený token pak můžeme nastavit klientovi pro autorizaci.

const TOKEN_FILE = __DIR__ . '/token.json';
$token = null;

if (file_exists(TOKEN_FILE)) {
  // Soubor s tokenem existuje a je načten
  $token = json_decode(file_get_contents(TOKEN_FILE));
}
elseif (isset($_GET['code'])) {
  // Uživatel se vrátil z Google aut. stránky, získá nový token,
  // který uloží a přesměruje uživatele na hlavní stránku aplikace
  // bez "code" parametru.
  $client->authenticate($_GET['code']);
  $token = $client->getAccessToken();
  file_put_contents(TOKEN_FILE, json_encode($token));
  header('Location: https://www.example.com/');
  exit();
}
else {
  // Nemá token, přesměruje uživatele na Google aut. stránku
  header('Location: ' . $client->createAuthUrl());
  exit();
}

// Obnoví a uloží vypršený token
if ($client->isAccessTokenExpired()) {
  $client->refreshToken($client->getRefreshToken());
  $token = $client->getAccessToken();
  file_put_contents(TOKEN_FILE, json_encode($token));
}

// Nastaví klientovi přístupový token
$client->setAccessToken($token);

Se získaným a nastaveným přístupovým tokenem v klientovi můžeme konečně vytvořit instanci Google_Service_Youtube pro práci s Youtube Data API. Třída je vázána na OAuth klienta Google_Client, který jí řeší autorizaci na pozadí.

Youtube Data API

Youtube Data API je rozdělena na části, kde každá řeší určitou funkcionalitu. Výpis všech najdete v dokumentaci API. Pro výpis položek v playlistu nás zajímá PlaylistItems.

$youtube = new Google_Service_Youtube($client);
// Povinný parametr je ID playlistu
// a výchozí max. počet výsledků je 5!
$options = [
  'playlistId' => 'EXAMPLE PLAYLIST ID',
  'maxResults' => 40,
];
$videos = $youtube
  ->playlistItems
  ->listPlaylistItems('snippet, contentDetails', $options)
  ->getItems();

foreach ($videos as $video) {
  $title = $video->getSnippet()->getTitle();
  $videoId = $video->getContentDetails()->getVideoId();
  $videoLink = "https://youtube.com/watch?v=$videoId";

  echo "<a href='$videoLink'>$title</a><br>";
}

První parametr metody listPlaylistItems je řetězec udávající názvy typů dat, které chcete o jednotlivých videích získat (např.: snippet a contentDetails). Typy jsou od sebe vždy odděleny čárkou. V JSON odpovědi z API jsou pak tyto jednotlivé položky reprezentovány jako samostatný atribut.

Pro získání obsahu playlistu je nutné uvést ID playlistu. Podobně jako u videí na Youtube je ID playlistů uvedeno v URL. Taky je dobré specifikovat maximální počet výsledků, protože výchozí hodnota je pouhých 5. Dokumentace doporučuje nepoužívat větší hodnoty, než 40-50.

Stránkování položek playlistu

Pro větší playlisty je lepší využít stránkování, které API pro položky playlistů obsahuje. Odpověď API obsahuje atribut pageInfo, kde jsou informace o celkovém počtu výsledků a počtu výsledků na stránce. Pomocí atributů prevPageToken a nextPageToken jsou k dispozici i ukazatele na předchozí a následující stránku. Parametrem pageToken pak lze při volání API specifikovat, kterou stránku výpisu má vrátit. Jednoduchý příklad stažení všech videí z delšího playlistu:

$youtube = new Google_Service_Youtube($client);
$videos = [];

// Volá API stránku po stránce a ukládá výsledky do pole,
// dokud nedojde na konec výpisu
do {

  $options = [
    'playlistId' => $playlistId,
    'maxResults' => 20,
  ];

  if (isset($result) && isset($result->nextPageToken)) {
    $options['pageToken'] = $result->nextPageToken;
  }

  $result = $youtube
    ->playlistItems
    ->listPlaylistItems('snippet, contentDetails', $options);
  $videos = array_merge($videos, $result->getItems());

}
while (isset($result) && isset($result->nextPageToken));

---

Využíváte ve své aplikaci Youtube Data API? Napadá vás, jakým způsobem by se dala využít? Podělte se s námi v komentářích!