Skip to content

Kaikki WordPressistä, web-kehityksestä — ja paljon muuta

🔍 Videoiden hakeminen YouTubesta Data API v3:n avulla: täydellinen opas
VerkkokehitysOhjelmat ja palvelut
6 min1,254 sanaa

🔍 Videoiden hakeminen YouTubesta Data API v3:n avulla: täydellinen opas

Sivustosi tarvitsee YouTube-videosyötteen, mutta valmista lisäosaa tehtävään ei ole, ja kuvittelet jo viikon mittaista painia OAuthin, tokenien ja kömpelöiden kirjastojen kanssa. YouTube Data API v3 hoitaa tämän homman noin tunnissa. Ei OAuthia, ei käyttäjätokeneita, ei ulkoisia riippuvuuksia. Pelkkä API-avain ja oikein koottu URL-osoite.

Hakupäätepiste palauttaa videoita, kanavia ja soittolistoja avainsanoilla. Se suodattaa päivämäärän, keston ja kanavan mukaan. Se järjestää osuvuuden tai katselukertojen mukaan. Käytännössä tämä kattaa useimmat skenaariot tietyn kanavan videosyötteestä viime kuukauden "wordpress tutorial" -koosteeseen.

Alla on vaiheittainen läpikäynti, jossa on eläviä pyyntöesimerkkejä ja PHP-koodia. Lopputuloksena sinulla on toimiva hakumoduuli: strukturoitua JSONia sisään, videogalleria ulos, ei lainkaan kolmannen osapuolen kirjastoja.

💡 Nopea yleiskatsaus:

  • Luo projekti Google Cloud -konsolissa, ota käyttöön YouTube Data API v3 ja hanki API-avain.
  • Rakenna hakupyynnön URL: päätepiste /youtube/v3/search, pakolliset parametrit part=snippet, key ja q (kesäkuusta 2025 alkaen q on pakollinen; ilman sitä API palauttaa tyhjän taulukon).
  • Lisää suodattimet: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
  • Suorita pyyntö cURL:n kautta PHP:ssä, jäsennä JSON-vastaus, näytä tulokset ja aseta välimuistitus WordPressin transienttien avulla.

Vaihe 1: API-avaimesi hankkiminen

Ilman avainta ei lähde yhtään API-pyyntöä. Avain on sidottu projektiin Google Cloud -konsolissa ja tunnistaa sovelluksesi; mitään monimutkaisempaa kuin Google-tilille kirjautuminen ei vaadita.

Toimi näin:

  • Avaa Google Cloud -konsoli ja luo uusi projekti tai valitse olemassa oleva.
  • Siirry kohtaan APIs & Services → Library, etsi "YouTube Data API v3" ja klikkaa Enable.
  • Avaa APIs & Services → Credentials, klikkaa Create Credentials → API Key.
  • Kopioi avain. Aseta välittömästi rajoitus: Restrict Key → YouTube Data API v3, jotta avainta ei voi käyttää muihin Googlen palveluihin.

Avain näyttää merkkijonolta kuten AIzaSyD-... ja se välitetään jokaisessa pyynnössä key-parametrin kautta. Julkiseen videohakuun tämä riittää; OAuthia ei tarvita. Jos kuitenkin suunnittelet pyyntöjä käyttäjän puolesta (videon lataus, soittolistojen hallinta), tarvitset OAuth 2.0:n.

Pikatesti: lähetä GET-pyyntö search-päätepisteeseen millä tahansa hakusanalla. Jos saat JSONin, jossa on items-taulukko, avain toimii.

Vaihe 2: Hakupyynnön URL ja pakolliset parametrit

Haun päätepiste:

1GET https://www.googleapis.com/youtube/v3/search

Kaksi parametria on aina pakollisia:

Parametri

Tarkoitus

part

Mitkä resurssin ominaisuudet sisällytetään vastaukseen. Hakuun tarvitset snippet-osan. Snippet sisältää otsikon, kuvauksen, pikkukuvat ja channelTitle-kentän.

key

API-avaimesi.

q

Hakukysely. Hyväksyy vapaata tekstiä, aivan kuten youtube.comin hakupalkki.

q-parametri hyväksyy vapaata tekstiä, aivan kuten youtube.comin hakupalkki. Voit välittää useita sanoja välilyönneillä tai plusmerkeillä erotettuna: q=wordpress+speed+optimization. Kirjainkoolla ei ole väliä.

Minimaalinen toimiva pyyntö:

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=YOUR_KEY

Se palauttaa 5 tulosta (oletusarvo), jonka API palauttaa, kun maxResults-arvoa ei ole ohitettu.

type-parametri rajaa haettavan resurssin tyypin:

  • video, vain videot;
  • channel, vain kanavat;
  • playlist, vain soittolistat.

Voit listata useita arvoja pilkuilla erotettuna: type=video,channel. Jos parametri jätetään pois, API hakee kaikkea. Loput parametrit ovat valinnaisia, mutta ne muuttavat raa'an kyselyn tarkaksi työkaluksi.

Vaihe 3: Videoiden hakeminen avainsanoilla

Klassinen skenaario: käyttäjä syöttää hakulausekkeen sivustollasi, lähetät sen YouTube APIin ja näytät valikoiman videoita.

Esimerkkipyyntö videoiden hakemiseen sanalla "swimming":

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=YOUR_KEY

Vastaus tulee JSON-muodossa. items[]-taulukon sisällä on joukko löydettyjä resursseja. Jokaisesta videosta saat:

  • id.videoId, yksilöllinen tunniste (liitetään osoitteeseen https://www.youtube.com/watch?v=...);
  • snippet.title, videon otsikko;
  • snippet.description, kuvaus;
  • snippet.thumbnails, esikatselukuvat useissa resoluutioissa (default, medium, high);
  • snippet.channelTitle, kanavan nimi.

PHP:ssä helpoin tapa hakea vastaus on file_get_contents. Tässä minimaalinen käsittelykoodi:

1$apiKey = 'YOUR_KEY';
2$query  = 'swimming';
3$url    = "https://www.googleapis.com/youtube/v3/search?part=snippet&q={$query}&type=video&key={$apiKey}";
4 
5$response = file_get_contents($url);
6$data     = json_decode($response, true);
7 
8foreach ($data['items'] as $item) {
9    echo '<h3>' . htmlspecialchars($item['snippet']['title']) . '</h3>';
10    echo '<p>' . htmlspecialchars($item['snippet']['description']) . '</p>';
11    echo '<img src="' . $item['snippet']['thumbnails']['medium']['url'] . '" alt="">';
12    echo '<a href="https://www.youtube.com/watch?v=' . $item['id']['videoId'] . '">Watch</a>';
13}

file_get_contents sopii testeihin ja pieniin projekteihin. Tuotannossa käytä cURLia: se antaa hallinnan aikakatkaisuihin, otsakkeisiin ja virheenkäsittelyyn. Ja kyllä, jos allow_url_fopen on poistettu käytöstä hostingissasi, file_get_contents ei toimi ulkoisille URL-osoitteille. Siinä tapauksessa cURL on ainoa vaihtoehtosi.

Vaihe 4: Videoiden hakeminen tietyltä kanavalta

Kerätäksesi kaikki videot kanavalta, välitä channelId-parametri. Kanavan tunnisteen löytäminen on helppoa: avaa kanavan sivu YouTubessa ja kopioi arvo osoiteriviltä /channel/-kohdan jälkeen (esimerkiksi UC3VyA8KN_VgCF93EurnAQXw).

Pyyntö:

1https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=YOUR_KEY

Parametri order=date järjestää julkaisupäivämäärän mukaan, uusin ensin. Ilman sitä API palauttaa osuvimmat tulokset, mutta kanavasyötteeseen kronologinen järjestys on järkevämpi.

Sama pyyntö PHP:ssä cURLilla ja perusvirheenkäsittelyllä:

1$apiKey    = 'YOUR_KEY';
2$channelId = 'UC3VyA8KN_VgCF93EurnAQXw';
3$url       = "https://www.googleapis.com/youtube/v3/search?part=snippet&channelId={$channelId}&type=video&order=date&key={$apiKey}";
4 
5$ch = curl_init();
6curl_setopt_array($ch, [
7    CURLOPT_URL            => $url,
8    CURLOPT_RETURNTRANSFER => true,
9    CURLOPT_TIMEOUT        => 15,
10    CURLOPT_SSL_VERIFYPEER => true,
11]);
12 
13$response = curl_exec($ch);
14$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
15curl_close($ch);
16 
17if ($httpCode !== 200) {
18    echo 'Request error. Code: ' . $httpCode;
19    exit;
20}
21 
22$data = json_decode($response, true);
23 
24foreach ($data['items'] as $item) {
25    printf(
26        '<div><a href="https://www.youtube.com/watch?v=%s">%s</a></div>',
27        $item['id']['videoId'],
28        htmlspecialchars($item['snippet']['title'])
29    );
30}

Kanavalla voi olla satoja videoita, mutta yksi pyyntö palauttaa enintään 50. Hakeaksesi kaiken, käytä API-vastauksen pageToken-kenttää: välitä sen arvo seuraavassa pyynnössä parametrina pageToken=<token>. Toista kunnes nextPageToken on tyhjä.

Vaihe 5: Rajaukset, järjestäminen ja kiintiöt

Oikealla sivustolla tarvitset harvoin "kaikki videot kyselylle". Useammin haluat top 10 viime kuukaudelta tai valikoiman, joka sulkee pois Shortsit. Tätä varten API tarjoaa viisi hienosäätöparametria.

maxResults: kuinka monta kohdetta palautetaan. Sallitut arvot: 1-50. Oletus on 5. Galleriaa tai syötettä varten aseta 20-30, mutta pidä kiintiöt mielessä.

order: järjestyskenttä:

Arvo

Mitä se tekee

relevance

Osuvuuden mukaan kyselyyn nähden (oletus)

date

Uusin ensin

rating

Arvostelun mukaan (tykkäykset/ei-tykkäykset)

viewCount

Katselukertojen mukaan

title

Aakkosjärjestyksessä otsikon mukaan

publishedAfter** / **publishedBefore: suodatus julkaisupäivämäärän mukaan. Muoto: ISO 8601 (RFC 3339). Esimerkki: publishedAfter=2026-01-01T00:00:00Z. Karsii arkistoidut videot, kun tarvitset vain tuoretta sisältöä.

videoDuration: suodatus pituuden mukaan:

  • short, alle 4 minuuttia;
  • medium, 4-20 minuuttia;
  • long, yli 20 minuuttia;
  • ei määritelty, kaikki.

videoEmbeddable arvolla true valitsee vain videot, jotka on sallittu upottaa kolmannen osapuolen sivustoille. Sivustolle, joka upottaa YouTube-soittimen, tämä on pakollinen parametri.

Yhdistetty pyyntö: 10 upotettavaa videota WordPressistä, ei vanhempia kuin 2026, yli 4 minuuttia pitkiä, järjestetty katselukertojen mukaan:

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress+tutorial&type=video&videoEmbeddable=true&videoDuration=medium&publishedAfter=2026-01-01T00:00:00Z&maxResults=10&order=viewCount&key=YOUR_KEY

Kiintiöt: miten vältät tyhjän ruudun

Jokainen search.list-kutsu kuluttaa 100 yksikköä päivittäisestä kiintiöstäsi. Oletuksena Google Cloud -projekti saa 10 000 yksikköä päivässä ilmaiseksi, eli noin 100 hakukutsua. Sivustolle, jolla on yli sata kävijää päivässä, se ei riitä.

Ratkaisu on API-vastausten välimuistitus. WordPressissä transientit toimivat tähän täydellisesti:

1$cache_key = 'yt_search_' . md5($query);
2$videos    = get_transient($cache_key);
3 
4if ($videos === false) {
5    $response = wp_remote_get($url);
6    $body     = json_decode(wp_remote_retrieve_body($response), true);
7    $videos   = $body['items'] ?? [];
8 
9    set_transient($cache_key, $videos, 6 * HOUR_IN_SECONDS);
10}
11 
12// Display $videos in a gallery...

Kuuden tunnin transientti tarkoittaa enintään 4 API-pyyntöä päivässä yhtä hakulauseketta kohden. Jopa kymmenellä eri kyselyllä sivuston sivuilla pysyt alle 40 kutsussa, mikä on alle puolet päivittäisestä kiintiöstä. Jos tarvitset enemmän, pyydä kiintiön korotusta Google Cloud -konsolin kautta: Quotas → YouTube Data API v3 → Edit.

Yllä oleva elävä esimerkki näyttää, miten rakennat kanavan videogallerian Data API v3:n kautta PHP:ssä 15 minuutissa.

⁉️🤔 Usein kysytyt kysymykset

Tarvitaanko OAuth videoiden etsimiseen YouTube APIn kautta?

Ei. Hakupyyntöihin osoitteeseen /youtube/v3/search riittää API-avain. OAuth vaaditaan vain käyttäjätason toiminnoissa: videoiden lataaminen, soittolistojen hallinta, tilaukset. API-avaimen saa Google Cloud -konsolista parissa minuutissa ja se on heti käyttövalmis.

Kuinka monta pyyntöä päivässä voi tehdä ilmaiseksi?

Jokainen Google Cloud -projekti saa 10 000 kiintiöyksikköä päivässä ilmaiseksi. Yksi search.list-kutsu maksaa 100 yksikköä, eli noin 100 hakupyyntöä päivässä. WordPressin transienttien avulla tapahtuvalla välimuistituksella tämä riittää keskivertosivustolle. Jos tarvitset enemmän, pyydä kiintiön korotusta Google Cloud -konsolin kautta (Quotas-osio).

Miten saan yli 50 tulosta yhdestä kyselystä?

Sivutuksen kautta. JSON-vastauksessa API palauttaa nextPageToken-kentän. Välitä sen arvo pageToken-parametrina seuraavassa pyynnössä saadaksesi seuraavan sivun. Toista kunnes nextPageToken on tyhjä. Täysi läpikäynti kanavalle, jossa on 500 videota, vie 10 pyyntöä ja 1 000 kiintiöyksikköä.

Voinko etsiä videoita muilla kielillä kuin englanniksi?

Kyllä. q-parametri hyväksyy minkä tahansa kielen, mukaan lukien venäjän. YouTuben hakualgoritmi määrittää kielen osuvuuden automaattisesti. Pakottaaksesi rajauksen, lisää relevanceLanguage=ru-parametri; tulokset asetetaan paremmuusjärjestykseen venäjänkielisen sisällön hyväksi.

Miksi API palauttaa tyhjän taulukon, vaikka pyyntö on oikein?

Yleisin syy: publishedAfter on asetettu tulevaisuuden päivämäärälle tai tämän päivän päivämäärälle tarkalla kellonajalla. Käytä päivän alkua: T00:00:00Z. Toinen syy: suodattimien yhdistelmä, joka sulkee pois kaikki tulokset. Esimerkiksi videoDuration=long ja videoEmbeddable=true yhdessä pienen kanavan channelId-tunnuksen kanssa voi tuottaa nolla osumaa. Yksinkertaista pyyntö muotoon part=snippet&q=...&key=... ja lisää suodattimia yksi kerrallaan tarkistaen tulokset jokaisessa vaiheessa.

Hakutoiminnon rakentaminen tunnissa: mitkä työkalut sopivat mihinkin tehtävään

Työkalujesi valinta riippuu siitä, mitä tarkalleen ottaen olet rakentamassa. Jos tarvitset yksinkertaisen videogallerian kanavalle pienen yrityksen sivustolla, nappaa valmis PHP-kääre kuten madcoda/php-youtube-api: Composer-paketti, kolme riviä koodia, tulos viidessä minuutissa. Jos rakennat mukautettua hakua suodattimilla, välimuistituksella ja sivutuksella, kirjoita oma käsittelijä käyttäen cURLia ja WordPressin transientteja. Sivustolle, jolla on paljon liikennettä ja kymmeniätuhansia kävijöitä, lisää Redis-välimuistikerros transienttien päälle ja aseta taustasynkronointi WP-Cronin kautta; silloin sivut latautuvat millisekunneissa ja API-kiintiöitä kuluu vain välimuistin mitätöintiin.

Sinulla on jo API-avaimesi. Välimuistitus on määritetty. Enää on jäljellä koota URL tehtävääsi varten ja kirjoittaa tulostussilmukka. Lopputuloksena on elävä videosyöte, joka ei ole riippuvainen kolmannen osapuolen palveluista eikä ylitä kiintiörajoja.

Toimitus
ToimitusToimitustiimi→ All publications

Ammattimainen kirjoittajien ja toimittajien tiimi, joka on erikoistunut laadukkaan sisällön luomiseen.